--- title: "POST /storage/url — Ссылка на файл" url: https://lumean.app/developers/docs/api/post-storage-url locale: ru description: "Ссылка на файл" generated: 2026-11-08 operationId: storage.url method: POST path: /storage/url scopes: [orders.download] spec_version: 1.0.0 --- # POST /storage/url **Ссылка на файл** Бэкенд выдаёт временную ссылку для скачивания файла-результата вашего заказа. Передайте `path` файла (как он указан в заказе) и получите ссылку, по которой файл можно скачать обычным GET-запросом. **Параметры:** - `path` — путь к файлу из вашего заказа - `download` — при `true` ссылка помечается как вложение: файл скачается под человекочитаемым именем заказа, а не откроется во вкладке **Безопасность:** - Ссылка действительна ограниченное время, затем истекает - Доступны только файлы ваших собственных заказов; запрос чужого файла вернёт 403 **Требуемое право ключа:** `orders.download`. - Право ключа: `orders.download` ## Запрос ```bash curl -X POST 'https://api.lumean.app/api/public/storage/url' \ -H 'Accept: application/json' \ -H 'X-API-KEY: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "path": "storage/42/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/result/output.mp3" }' ``` ## Параметры | Поле | Где | Тип | Обяз. | Описание | | --- | --- | --- | --- | --- | | `X-Locale` | header | `string` | — | Язык локализованных текстов ответа (`message`, подписи, причины ошибок), код ISO-639-1. Необязателен; без него — язык аккаунта владельца ключа, затем `Accept-Language`, затем язык по умолчанию. Неизвестный или неподдерживаемый код пропускается так же, как отсутствующий. | | `X-Timezone` | header | `string` | — | IANA-зона (`Europe/Moscow`), в которой ответ показывает моменты времени — ISO-8601 со смещением. Необязателен; без него даты приходят в UTC. Невалидная зона игнорируется. Применённую зону сервер возвращает в одноимённом заголовке ответа. | ## Тело запроса Возвращает временную ссылку (`data.url`, TTL ~60 минут). Качайте её обычным `GET` — заголовок `X-API-KEY` для скачивания не нужен и не передаётся. Content-Type: `application/json` | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `path` | `string` | обяз. | Путь файла целиком, как он пришёл в `result.files[]` или `result.service_files[]` заказа. Собирать путь вручную не нужно и не получится — он содержит служебные сегменты. | | `download` | `boolean` | — | При `true` ссылка помечается как attachment: файл скачается под человекочитаемым именем заказа, а не откроется во вкладке браузера. | | `number_base` | `integer` — `0` · `1` | — | С какого числа нумеруются чанки в имени файла: `1` → первый чанк «001», `0` → «000». По умолчанию `1`. | | `number_padding` | `integer` — 1..4 | — | Ширина номера чанка с ведущими нулями, `1..4`: `3` → «007». По умолчанию `3`. Держите одинаковым с запросом ZIP-архива, иначе один и тот же чанк называется по-разному поштучно и внутри архива. | **Пример** ```json { "path": "storage/42/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/result/output.mp3" } ``` ## Сценарии тела ### Файл результата Путь берётся целиком из result.files[] заказа. ```json { "path": "storage/42/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/result/output.mp3" } ``` ### Ссылка на скачивание download: true — файл сохранится под именем заказа, а не откроется во вкладке. ```json { "path": "storage/42/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/result/output.mp3", "download": true, "number_base": 1, "number_padding": 3 } ``` ## Ответы ### 200 — Временная ссылка в `data.url`. Живёт около часа; качайте обычным `GET`, без `X-API-KEY`. **Поля ответа** | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `success` | `boolean` | обяз. | Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь `true`, а ошибка приходит телом другой формы, где этого поля может не быть вовсе. | | `message` | `string` | обяз. | Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются. | | `data` | `object` | обяз. | Полезная нагрузка ответа. | | `data.url` | `string` | обяз. | Временная ссылка на файл. Качается обычным `GET` **без** заголовка `X-API-KEY`. Живёт ограниченное время — не сохраняйте её надолго, запрашивайте перед скачиванием. | **Пример** ```json { "success": true, "message": "Download link generated.", "data": { "url": "https://s3.lumean.app/lumean/storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260717%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260717T150000Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c" } } ``` ### 401 — Невалидный или отсутствующий API-ключ **Поля ответа** | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. | | `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). | | `data` | `null` — nullable | обяз. | Всегда `null`, когда запрос отклонён до обработки. | **Пример** ```json { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } ``` ### 403 — Нет доступа к файлу **Поля ответа** | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `success` | `boolean` | обяз. | Всегда `false` у ошибок. | | `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. | | `errors` | `null` — nullable | обяз. | Разбор по полям — только у ошибок валидации (`422`): ключ соответствует полю запроса, значение — список претензий к нему. У остальных кодов приходит `null`: разбирать нечего, причина целиком в `message`. | **Пример** ```json { "success": false, "message": "You do not have access to this file." } ``` ### 404 — Файл не найден: неверный `path` либо срок хранения заказа истёк. **Поля ответа** | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `success` | `boolean` | обяз. | Всегда `false` у ошибок. | | `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. | | `errors` | `null` — nullable | обяз. | Разбор по полям — только у ошибок валидации (`422`): ключ соответствует полю запроса, значение — список претензий к нему. У остальных кодов приходит `null`: разбирать нечего, причина целиком в `message`. | **Пример** ```json { "success": false, "message": "File not found." } ``` ### 422 — Ошибка валидации. Поля с ошибками перечислены в `errors`. **Поля ответа** | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. | | `message` | `string` | обяз. | Сводка ошибок валидации словами, на языке ответа (`X-Locale`). | | `errors` | `object` | обяз. | Разбор по полям: ключ — поле запроса, значение — список претензий к нему. | | `errors.*` | `array` — произвольные ключи | — | | **Пример** ```json { "success": true, "message": "string", "errors": {} } ``` ### 500 — Не удалось выпустить ссылку. Повторите запрос — операция идемпотентна. **Поля ответа** | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `success` | `boolean` | обяз. | Всегда `false` у ошибок. | | `message` | `null \| array \| string \| object` — nullable | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. | | `errors` | `null` — nullable | обяз. | Разбор по полям — только у ошибок валидации (`422`): ключ соответствует полю запроса, значение — список претензий к нему. У остальных кодов приходит `null`: разбирать нечего, причина целиком в `message`. | **Пример** ```json { "success": false, "message": "Failed to generate the download link. Please try again later." } ``` ### 503 — Файл временно недоступен (идёт подготовка), повторите позже **Поля ответа** | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `success` | `boolean` | обяз. | Всегда `false` у ошибок. | | `message` | `null \| array \| string \| object` — nullable | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. | **Пример** ```json { "success": false, "message": "Service temporarily unavailable." } ``` --- - Эта же страница в браузере: https://lumean.app/developers/docs/api/post-storage-url - Машинный справочник целиком: https://api.lumean.app/docs/llm.md