AiVideoEditor
Начните бесплатно
Меню

Проверено 2026-11-10 · версия API 2026-11-09 · Читать Markdown

Загрузка и хранение медиа

Байты медиа идут напрямую во временное приватное объектное хранилище. REST и MCP возвращают инструкции по загрузке; они не принимают бинарное содержимое файлов в JSON инструментов. Хранилище должно быть настроено на развертывании, иначе создание загрузки возвращает provider_unavailable.

Жизненный цикл загрузки

  1. Вызовите POST /api/v1/media/upload-intents с именем файла, заявленным MIME и числом байтов. Сохраните возвращенные assetId и sessionId как отдельные идентификаторы.
  2. Осмотрите method. Для presigned_put загрузите весь файл в uploadUrl с возвращенными заголовками. Для multipart_initiated разбейте файл по partSizeBytes, загрузите каждую пронумерованную часть по ее возвращенному URL и сохраните квитанцию ETag. Никогда не добавляйте bearer-ключ AiVideoEditor к запросам в хранилище.
  3. Финализируйте на POST /api/v1/media/{assetId}/finalize с sessionId и, для multipart, с multipart.parts, содержащими каждый partNumber и etag.
  4. Используйте финализированный 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. Храните оригиналы. Если медиа истекло или удаляется, загрузите его заново перед публикацией.