Проверено 2026-11-10 · версия API 2026-11-09 · Читать Markdown
Загрузка и хранение медиа
Байты медиа идут напрямую во временное приватное объектное хранилище. REST и MCP
возвращают инструкции по загрузке; они не принимают бинарное содержимое файлов в JSON инструментов.
Хранилище должно быть настроено на развертывании, иначе создание загрузки возвращает
provider_unavailable.
Жизненный цикл загрузки
- Вызовите
POST /api/v1/media/upload-intentsс именем файла, заявленным MIME и числом байтов. Сохраните возвращенныеassetIdиsessionIdкак отдельные идентификаторы. - Осмотрите
method. Дляpresigned_putзагрузите весь файл вuploadUrlс возвращенными заголовками. Дляmultipart_initiatedразбейте файл поpartSizeBytes, загрузите каждую пронумерованную часть по ее возвращенному URL и сохраните квитанцию ETag. Никогда не добавляйте bearer-ключ AiVideoEditor к запросам в хранилище. - Финализируйте на
POST /api/v1/media/{assetId}/finalizeсsessionIdи, для multipart, сmultipart.parts, содержащими каждыйpartNumberиetag. - Используйте финализированный ID ресурса в
mediaIdsчерновика. Само по себе намерение загрузки не делает ресурс пригодным к публикации.
Сервер наблюдает фактические байты и формат по неизменяемой итоговой копии. Заявленные размер/MIME — входные данные резервирования, а не доказательство валидности файла. Поддерживаемые базовые семейства — JPEG, PNG и MP4; отдельные назначения могут вводить более строгие лимиты. Текущий максимальный размер файла — 500 MiB (524,288,000 байтов). Файлы от 50 MiB и выше используют multipart, обычно с частями по 16 MiB. Всегда следуйте возвращенным размерам, URL и срокам действия, а не выводите их из этих значений по умолчанию.
{
"sessionId": "<session UUID from upload-intents>",
"multipart": {
"parts": [
{ "partNumber": 1, "etag": "<ETag returned by storage>" }
]
}
}
Это иллюстрация multipart-формы; включайте каждую фактическую часть. Финализация
одиночным PUT отправляет только sessionId. Давайте каждой новой мутации API свой
Idempotency-Key; сохраняйте его для безопасных идентичных повторов.
Возобновление или отмена
Истекшие подписанные URL — не постоянные адреса медиа. Запросите свежие URL multipart-частей
через POST /media/{id}/upload-parts с fromPart и toPart (включающий диапазон не более 64 частей). См. справочник API для ограниченной формы
запроса. Не перезагружайте завершенные части без необходимости и не завершайте multipart-
сборку напрямую через хранилище: финализацией управляет сервер.
Используйте POST /media/{id}/abandon при отмене незавершенной загрузки. Это освобождает
ее резервирование через общий процесс очистки. Истечение сессии или использованное
multipart-состояние может потребовать нового намерения; не угадывайте ключи объектов хранилища.
Временное хранение
GET /media/{id} возвращает статус и динамическую информацию deleteAfter, а не
постоянный публичный URL. Запланированные и выполняющиеся использования защищают медиа на время работы.
Политика по умолчанию хранит неиспользуемые медиа черновиков 14 дней, завершенные медиа 72 часа,
а неудавшуюся или неоднозначную работу 7 дней после соответствующей попытки. Фактическое
хранение зависит от всех оставшихся ссылок; deleteAfter может быть null.
Храните оригиналы. Если медиа истекло или удаляется, загрузите его заново перед публикацией.