88API88API
Руководство пользователяAI-приложенияAPIПомощь и поддержка
Видео (Video)

Полная спецификация Video API

Единая спецификация генерации видео 88API.

На этой странице описана единая спецификация генерации видео 88API; она применяется ко всем видеомоделям, которые предоставляет 88API. Вам достаточно взять ID model из списка моделей, доступных вашему API-ключу, и вызывать единый интерфейс с этой страницы.

Все видеозадачи сейчас используют общий протокол «получение моделей → отправка → опрос → скачивание». Разные аккаунты могут видеть разные ID моделей, а поддерживаемые длительность, соотношение сторон, разрешение и количество референсных материалов у моделей тоже различаются; не переносите возможности одной модели на другую.

Обновлено 2026-11-13. Параметры и примеры, специфичные для моделей каждого бренда, вынесены на отдельные страницы — см. Спецификации по брендам ниже. Рекомендуемый порядок: сначала вызовите GET /v1/models, чтобы получить ID моделей, доступных текущему ключу; на уже доступные HTTPS-материалы ссылайтесь напрямую; локальные файлы сначала загрузите → отправьте задачу генерации → получите URL результата опросом → воспроизведите, скачайте или используйте как референс в следующем раунде. Успешная загрузка не означает, что модель поддерживает этот тип материала: возможности модели и возможности хранилища — разные вещи.

Единое правило интеграции: сначала укажите в model точный id из ответа GET /v1/models, затем создайте задачу через POST /v1/videos, сохраните id из ответа и опрашивайте GET /v1/videos/{id}. В новых интеграциях не используйте старый /v1/video/generations и не полагайтесь на task_id. Все видеомодели возвращают результат через опрос; не указывайте callback_url.

1. Минимальные правила единой интеграции

Если один клиент должен работать с несколькими видеомоделями, достаточно зафиксировать следующий порядок:

  1. Запросите GET /v1/models с текущим API-ключом.
  2. Выберите из ответа id модели, к которой у вашего аккаунта действительно есть доступ; не прописывайте жёстко в глобальной конфигурации названия из каталога моделей, исторические названия или названия, которые видны другим аккаунтам.
  3. Отправляйте задачи в едином формате запроса POST /v1/videos.
  4. Запрашивайте задачу только по публичному id из ответа; не разбирайте и не составляйте никакие другие ID задач.
  5. Получайте видео по url, video_url или result_url из ответа о завершении.

Рекомендуемые общие поля:

НазначениеРекомендуемое полеПояснение
МодельmodelДолжен быть точным ID модели, полученным текущим ключом из /v1/models
ТекстpromptДля генерации видео только по тексту обычно обязателен; можно ли его опустить, зависит от модели
Длительностьduration или secondsОдно из двух, в секундах; предпочтительно duration
Соотношение сторонratio или aspect_ratioРекомендуется для задания соотношения сторон кадра; допустимые значения зависят от целевой модели
Референсные изображенияimagesРекомендуются публичные HTTPS-адреса или уже загруженные URL assets.88api.ai
Референсное видеоmetadata.referenceVideosТолько если целевая модель это поддерживает
Референсное аудиоmetadata.referenceAudiosТолько если целевая модель это поддерживает
Первый и последний кадрmetadata.firstFrame, metadata.lastFrameТакже соблюдайте правила целевой модели для первого и последнего кадра и взаимоисключения материалов

Таблица выше описывает запись, общую для большинства моделей. У некоторых брендов поля отличаются (например, для Wan первый и последний кадр и референсы рекомендуется передавать в массиве media, а нераспознанные поля материалов возвращают 400); ориентируйтесь на Спецификации по брендам.

size — поле совместимости, которое используют некоторые модели и старые клиенты. Новым клиентам следует предпочитать ratio или aspect_ratio и выбирать конкретное значение по описанию возможностей целевой модели.

Во всех примерах ниже <MODEL_ID> означает реальный ID модели, полученный из /v1/models описанным выше способом, а не фиксированную строку, одинаковую для всех аккаунтов.

2. Краткий справочник по эндпоинтам

НазначениеМетод и путьПояснение
Получить моделиGET https://api.88api.ai/v1/modelsВозвращает ID моделей, видимых текущему API-ключу; ориентируйтесь на ответ
Отправить генерациюPOST https://api.88api.ai/v1/videosОтправляет текст и референсные материалы, возвращает id задачи
Запросить задачуGET https://api.88api.ai/v1/videos/{id}Статус, прогресс и ошибки
Запросить загрузку файлаPOST https://api.88api.ai/v1/media/uploadsПередаёт хеш файла, размер в байтах и MIME, возвращает краткосрочное разрешение на загрузку
Загрузить бинарные данныеPUT {upload_url}Используются выданные заголовки загрузки, API-ключ не передаётся
Получить видеоGET {url}Предпочтительно URL результата из ответа о завершении; не составляйте путь самостоятельно
Старый адрес содержимогоGET https://api.88api.ai/v1/videos/{id}/contentСовместимое перенаправление для архивированных видео; не универсальный способ скачивания всех результатов

Заголовки запроса

Authorization: Bearer sk-ваш-API-ключ
Content-Type: application/json
Accept: application/json

API-ключ должен храниться на сервере; его нельзя встраивать во фронтенд браузера, мини-программы или мобильного приложения.

ОперацияАутентификация
Создание и запрос задач; запрос разрешения на загрузкуAuthorization: Bearer ..., только к API api.88api.ai
Загрузка файлаX-Media-Upload-Token и Content-Type из headers без изменений
Чтение публичных медиафайловАдреса assets.88api.ai не требуют Bearer, Cookie или входа в аккаунт

Анонимное чтение не означает анонимную загрузку и не открывает сведения о задаче. Любой, у кого есть URL публичного медиафайла, может читать файл в течение срока его действия; не считайте URL строгим механизмом изоляции данных. Не передавайте свой API-ключ на адреса медиафайлов, официальные адреса результатов или цели перенаправлений.

Сначала получите ID моделей, доступных аккаунту

ID моделей не одинаковы для всех аккаунтов. При первой интеграции или периодическом обновлении списка моделей сначала выполните:

curl 'https://api.88api.ai/v1/models' \
  --header 'Authorization: Bearer sk-xxxx'

Выберите модель из data[].id в ответе и без изменений передавайте это значение в поле model последующих запросов POST /v1/videos. Не составляйте ID по отображаемому названию модели и не считайте, что названия из других аккаунтов или старой документации обязательно доступны текущему аккаунту.

{
  "object": "list",
  "data": [
    {
      "id": "<MODEL_ID>",
      "object": "model",
      "owned_by": "88api"
    }
  ]
}

3. Стандартный запрос на создание

Минимальный запрос «текст в видео»

curl --request POST 'https://api.88api.ai/v1/videos' \
  --header 'Authorization: Bearer sk-xxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "<MODEL_ID>",
    "prompt": "Серебристый спорткар в дождливом ночном городе, съёмка с низкой точки в движении, отражения неона, кинематографично",
    "duration": 8,
    "ratio": "16:9"
  }'

duration можно также передать строкой в поле seconds:

{
  "model": "<MODEL_ID>",
  "prompt": "Аэросъёмка побережья на рассвете, облака медленно плывут",
  "seconds": "8",
  "ratio": "16:9"
}

Общие поля запроса

ПолеТипОбязательноПояснение
modelstringДаТочный ID модели, полученный текущим API-ключом через GET /v1/models
promptstringПо условиюТекстовый промпт; лишь некоторые модели допускают пустое значение при наличии референсов
negative_promptstringНетНегативный промпт для моделей с несколькими референсами; для Veo можно также указать metadata.negativePrompt
durationintegerНетДлительность видео в секундах; одно из двух с seconds
secondsstringНетДлительность видео строкой, например "8"
ratiostringНетРекомендуемое поле соотношения сторон, например 16:9, 9:16
aspect_ratiostringНетСовместимый псевдоним ratio; допустимые значения зависят от целевой модели
sizestringНетПоле совместимости; в новых интеграциях не передавайте через него соотношение сторон
resolutionstringНетТолько если целевая модель поддерживает, например 480p, 720p, 1080p, 4k
imagestringНетURL одного референсного изображения
imagesstring[]НетМассив URL референсных изображений, рекомендуемый способ
videostringНетURL одного референсного видео; для Gemini Omni обязательно это поле верхнего уровня
videosstring[]НетМассив референсных видео; другие модели с несколькими референсами используют metadata.referenceVideos
seedintegerНетСлучайное зерно
generateAudio / generate_audiobooleanНетВключает синхронную генерацию звука на поддерживающих моделях; только если модель это допускает
metadataobjectНетРасширенные поля: референсные видео и аудио, первый и последний кадр и т. д.

Как запросить разрешение

Эндпоинт создания один для всех, но способ выбора разрешения у моделей может различаться. Сначала ориентируйтесь на ID модели из ответа GET /v1/models и описание её возможностей.

Модели с фиксированным разрешением: выбор через ID модели

У некоторых моделей выходное качество уже зафиксировано в названии или ID. Получите из GET /v1/models ID, реально доступные аккаунту, и выберите модель с нужным разрешением:

{
  "model": "<FIXED_RESOLUTION_MODEL_ID>",
  "prompt": "Машина медленно проезжает по улице ночного города",
  "duration": 8,
  "ratio": "16:9"
}

У моделей с фиксированным разрешением resolution не может временно изменить выходное разрешение. Даже если клиент передаёт resolution, не рассчитывайте, что оно переопределит возможности модели.

Модели с выбором разрешения: поле resolution

Некоторые модели поддерживают несколько разрешений; в этом случае передайте в запросе resolution в нижнем регистре:

{
  "model": "<MULTI_RESOLUTION_MODEL_ID>",
  "prompt": "Машина медленно проезжает по улице ночного города",
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9"
}

Фактически доступные разрешения и значения по-прежнему определяются /v1/models текущего API-ключа, описанием модели и серверной проверкой. Если клиенту нужна совместимость с несколькими моделями, поле resolution можно оставить: модели, которые его поддерживают, выберут по нему разрешение, а модели с фиксированным разрешением будут ориентироваться на model. Не используйте quality, vquality и не меняйте название модели, чтобы обойти ограничения её возможностей; неподдерживаемые комбинации возвращают 400.

4. Референсные изображения, видео и аудио

3.1 Референсные изображения

Несколько изображений всегда передаются в массиве верхнего уровня images:

{
  "model": "<MODEL_ID>",
  "prompt": "Сохранить лицо, одежду и цветовую гамму персонажа, он медленно идёт по берегу моря, мягкий кинематографичный свет",
  "duration": 10,
  "ratio": "16:9",
  "images": [
    "https://cdn.example.com/character-front.jpg",
    "https://cdn.example.com/character-side.jpg"
  ]
}

Одно изображение можно передать и через image или input_reference, но в новых интеграциях рекомендуется везде использовать массив images.

3.2 Референсное видео

Для моделей, которые по таблице возможностей поддерживают несколько референсных видео, используйте metadata.referenceVideos:

{
  "model": "<MODEL_ID>",
  "prompt": "Взять ритм монтажа и движение камеры из референса, но сохранить внешний вид объекта",
  "duration": 8,
  "ratio": "16:9",
  "images": ["https://cdn.example.com/subject.jpg"],
  "metadata": {
    "referenceVideos": [
      "https://cdn.example.com/camera-motion.mp4"
    ]
  }
}

3.3 Референсное аудио

Для моделей, которые по таблице возможностей поддерживают аудиореференс, используйте metadata.referenceAudios:

{
  "model": "<MODEL_ID>",
  "prompt": "Персонаж поёт в ритме референсного аудио, с естественной артикуляцией",
  "duration": 10,
  "ratio": "16:9",
  "images": ["https://cdn.example.com/singer.jpg"],
  "metadata": {
    "referenceAudios": [
      "https://cdn.example.com/voice-reference.mp3"
    ]
  }
}

Для референсных изображений minimax-h3 не используйте images верхнего уровня — передавайте их в metadata.referenceImages, см. спецификацию MiniMax Video API.

3.4 Смешанные материалы для моделей с несколькими референсами

{
  "model": "<MODEL_ID>",
  "prompt": "Технологичная реклама: внешний вид продукта с изображений, ритм камеры из видео и звуковая атмосфера из референсного аудио",
  "duration": 12,
  "ratio": "16:9",
  "images": [
    "https://cdn.example.com/product-front.jpg",
    "https://cdn.example.com/product-detail.jpg"
  ],
  "metadata": {
    "referenceVideos": [
      "https://cdn.example.com/motion-reference.mp4"
    ],
    "referenceAudios": [
      "https://cdn.example.com/sound-reference.mp3"
    ]
  }
}

Не используйте одновременно несколько полей-псевдонимов для одного типа материалов. Например, не передавайте одновременно images верхнего уровня и metadata.referenceImages: если присутствует несколько совместимых полей, сервер выберет один набор, объединение не гарантируется.

3.5 Требования к URL медиафайлов

  1. Референсные видео и аудио передаются как публичные HTTPS URL, доступные для анонимного скачивания. blob:, локальные пути и data:video/... не являются универсальным способом передачи референсного видео; локальные файлы сначала загрузите, как описано в следующем разделе.
  2. URL не должен зависеть от Cookie, сессии браузера, Referer или нестандартных заголовков.
  3. Нельзя использовать localhost, частные IP-адреса, имена сервисов Docker или адреса, доступные только из вашей внутренней сети.
  4. URL должен оставаться действительным всё время генерации; рекомендуемый срок действия — не менее 60 минут.
  5. Для изображений рекомендуются JPG, PNG или WebP; для видео — MP4/MOV; для аудио — MP3/WAV.
  6. Рекомендуется не более 50 МБ на видеофрагмент и не более 15 МБ на аудиофрагмент; слишком большие файлы могут не пройти этап скачивания или модерации.
  7. Прежде чем использовать сторонние материалы, убедитесь, что у вас есть необходимые авторские права, права на изображение и разрешения на использование.

То, что страница материала открывается, ещё не значит, что байты видео можно скачать: адрес должен отдавать сам медиафайл, а не HTML-страницу для просмотра. Доступность URL также не означает, что кодек, длительность или размеры соответствуют требованиям целевой модели. Изображения для видеомоделей Google можно также передавать в Base64 или загрузкой файла — см. спецификацию Google Video API; референсное видео по-прежнему принимается только по URL.

3.6 Загрузка локальных файлов: сначала запрос, затем PUT

Этот эндпоинт предоставляет временное хранилище медиафайлов; он не генерирует видео, не перекодирует, не сжимает и не извлекает кадры автоматически.

Шаг 1. Запросите разрешение на загрузку на своём сервере.

POST https://api.88api.ai/v1/media/uploads
Authorization: Bearer sk-xxxx
Content-Type: application/json
{
  "size": 1234567,
  "mime_type": "video/mp4",
  "sha256": "<SHA-256 исходных байтов файла в Base64URL без padding>"
}
ПолеПравило
sizeРазмер исходного файла в байтах, целое число от 1 до 100,000,000; не длина строки Base64
mime_typeДолжен совпадать с реальным форматом файла и с Content-Type при загрузке
sha25632-байтовый дайджест SHA-256 в кодировке Base64URL без =; не 64-символьная шестнадцатеричная строка

Поддерживаются для загрузки: video/mp4, video/webm, video/quicktime; audio/mpeg, audio/wav, audio/ogg, audio/mp4, audio/flac; image/png, image/jpeg, image/webp, image/gif. Лимит загрузки не равен лимиту референсов модели: файл по-прежнему должен соответствовать более строгим ограничениям целевой модели.

Пример ответа HTTP 200 (значения в угловых скобках — заполнители, а не реальные значения для вызова):

{
  "url": "https://assets.88api.ai/media/reference-media/<object-id>.mp4",
  "upload_url": "https://assets.88api.ai/media/reference-media/<object-id>.mp4",
  "method": "PUT",
  "headers": {
    "Content-Type": "video/mp4",
    "X-Media-Upload-Token": "<scoped-upload-token>"
  },
  "expires_at": 1789373400
}

Здесь expires_at — это срок действия разрешения на загрузку (Unix-секунды, около 10 минут), а не срок хранения файла; url на этом этапе тоже не означает, что файл уже загружен. Разрешение позволяет записать только указанный файл и не даёт доступа ко всему бакету.

Шаг 2. Загрузите исходные бинарные данные до истечения разрешения. Используйте upload_url, method и headers из ответа без изменений:

# Эти переменные берутся из ответа на запрос разрешения; не отправляйте API_KEY на адрес загрузки.
curl --request PUT "$UPLOAD_URL" \
  --header 'Content-Type: video/mp4' \
  --header "X-Media-Upload-Token: $UPLOAD_TOKEN" \
  --data-binary @reference.mp4

Это не multipart/form-data, не -F и не Base64 в JSON. Content-Length, MIME и байты файла должны совпадать с указанными в запросе; браузер может отправить File/Blob напрямую и сам сформирует Content-Length. Потоковые серверные клиенты тоже должны указывать правильную длину; не используйте chunked-загрузку с неизвестной длиной.

HTTP 201 означает, что загрузка завершена; в ответе возвращаются url, size, mime_type и expires_at. Вот этот expires_at — срок действия материала (Unix-секунды, 30 дней с момента загрузки объекта). Убедившись в успехе, поместите url в поле референса, которого требует целевая модель. Браузер должен получать разрешение через ваш собственный бэкенд и затем загружать файл напрямую; долгоживущий API-ключ нельзя раскрывать во фронтенде.

Перезапись по одному и тому же адресу загрузки запрещена: повторный PUT возвращает 409 — используйте уже успешно загруженный адрес. При неясном обрыве сети сначала проверьте этот URL анонимным HEAD, а не запрашивайте сразу новый объект. Загрузка и ссылки на материал не создают новых задач генерации.

5. Режим первого и последнего кадра для поддерживающих моделей

Первый и последний кадр передаются в metadata.firstFrame и metadata.lastFrame:

Пример ниже подходит для моделей с несколькими референсами, которые поддерживают эти поля. Veo и Gemini Omni также принимают metadata.firstFrame и metadata.lastFrame; другие варианты записи см. в спецификации Google Video API.

{
  "model": "<MODEL_ID>",
  "prompt": "Плавный переход от пустой площади ранним утром к той же композиции ночью, когда зажигаются огни",
  "duration": 10,
  "ratio": "16:9",
  "metadata": {
    "firstFrame": "https://cdn.example.com/start.jpg",
    "lastFrame": "https://cdn.example.com/end.jpg"
  }
}

Правила:

  • lastFrame нельзя использовать отдельно: обязательно укажите и firstFrame.
  • Большинство моделей с поддержкой первого и последнего кадра не позволяют сочетать их с обычными референсными изображениями, видео или аудио.
  • Если в таблице возможностей указано «взаимоисключающе», выберите либо первый и последний кадр, либо обычные референсные материалы.

6. Таблица возможностей текущих видеомоделей

Таблицы ниже описывают открытые возможности моделей; названия в таблицах не являются фиксированными ID моделей для запросов. В реальных запросах используйте id, который /v1/models возвращает текущему API-ключу; разные аккаунты могут видеть разные ID моделей.

Спецификации по брендам

Запись параметров и поля материалов у разных брендов не полностью совпадают; перед интеграцией прочитайте страницу соответствующего бренда:

Страница брендаМодели
Seedancedoubao-seedance-2.0, doubao-seedance-2.5, doubao-seedance-2.5-flash, doubao-seedance-2.0-fast, doubao-seedance-2.0-mini
Googleveo-3.1, veo-3.1-fast, gemini-omni-flash-1.1, gemini-omni-flash-1.2
MiniMaxminimax-h3
Wanwan3.0-video, wan3.0-video-prime
Grokgrok-imagine-video, grok-imagine-video-1.5

Сводная таблица возможностей моделей

№Возможности / публичное названиеДлительностьСоотношение сторонВыходЛимит изображений / видео / аудиоПервый и последний кадрУправление звуком
1doubao-seedance-2.04–15 с; поддерживается -116:9 4:3 1:1 3:4 9:16 21:9 adaptive480P/720P/1080P/4K, по умолчанию 720P9 / 3 / 3Да, взаимоисключающе с обычными материаламиЗвук по умолчанию, можно отключить
2doubao-seedance-2.54–30 с; поддерживается -1То же480P/720P/1080P, по умолчанию 720P30 / 10 / 10Да, взаимоисключающе с обычными материаламиЗвук по умолчанию, можно отключить
3doubao-seedance-2.5-flash4–30 с; поддерживается -1То же480P/720P, по умолчанию 720P10 / 5 / 5Да, взаимоисключающе с обычными материалами; с первым кадром соотношение сторон берётся из изображения первого кадраЗвук по умолчанию, можно отключить
4doubao-seedance-2.0-fast4–15 с; поддерживается -1То же480P/720P, по умолчанию 720P9 / 3 / 3Да, взаимоисключающе с обычными материаламиЗвук по умолчанию, можно отключить
5doubao-seedance-2.0-mini4–15 с; поддерживается -1То же480P/720P, по умолчанию 720P9 / 3 / 3Да, взаимоисключающе с обычными материаламиЗвук по умолчанию, можно отключить
6veo-3.14/6/8 с; с референсными изображениями — фиксированно 8 с; каждое продление добавляет 7 с16:9 9:16720P/1080P/4K3 / 0 / 0Первый кадр, первый и последний кадр, референсные изображенияНативный звук, отключается через generate_audio
7veo-3.1-fastВсегда 8 с16:9 9:16Всегда 720P3 / 0 / 0Первый кадр, первый и последний кадр, референсные изображенияЗвук всегда есть
8gemini-omni-flash-1.13–10 с, по умолчанию 3 с16:9 9:16720P/1080P/4K10 / 3 / 0Первый кадр, первый и последний кадрНе поддерживается
9gemini-omni-flash-1.23–15 с, по умолчанию 3 с16:9 9:16720P/1080P/4K10 / 3 / 0Первый кадр, первый и последний кадрНе поддерживается
10minimax-h34–15 с, по умолчанию 5 с16:9 (по умолчанию) 9:16 1:1 4:3 3:4 21:9; в 1080P/2K только 16:9 9:16768P/1080P/2K (апскейл), по умолчанию 768P9 (в 1080P/2K — 6) / – / 3Только 768P, взаимоисключающе с обычными материаламиЗвуковая дорожка всегда есть, не настраивается
11wan3.0-video2–30 с, по умолчанию 5 с; поддерживается -1adaptive (по умолчанию) 16:9 9:16 1:1 4:3 3:4 21:9480P/720P/1080P, по умолчанию 1080P10 / 5 / 5 (через массив media)Да, взаимоисключающе с обычными материаламиНе настраивается
12wan3.0-video-primeТо жеТо жеТо жеТо жеТо жеНе настраивается
13grok-imagine-video1–15 с, по умолчанию 8 с; с референсными изображениями не дольше 10 с16:9 9:16 1:1 4:3 3:4 3:2 2:3 (через aspect_ratio)480P/720P14 / 0 / 0Только первый кадр, не вместе с референсными изображениямиНе поддерживается
14grok-imagine-video-1.51–15 с, по умолчанию 8 сТо же480P/720P/1080P; не выше 720P с последним кадром, ключевыми кадрами, референсными изображениями или голосами14 (первый/последний кадр и ключевые кадры сверх лимита) / 0 / 0Первый и последний кадр плюс до 4 ключевых кадров, можно вместе с референсными изображениямиНе поддерживается

Нумерация в таблице начинается с 1 и служит только для удобства чтения, это не параметр запроса. Публичные названия и серии возможностей в таблице тоже приведены только для сопоставления; при реальном вызове обязательно используйте точный id, который /v1/models возвращает текущему API-ключу, и не составляйте названия самостоятельно.

Особые правила моделей

Поля у разных брендов заметно различаются; ниже перечислены самые частые ошибки, полные правила — на страницах брендов выше:

  • Wan wan3.0-video*: первый и последний кадр и референсы рекомендуется передавать в массиве media. metadata.firstFrame/lastFrame/referenceImages/referenceVideos/referenceAudios (и формы с подчёркиванием), firstFrame/first_frame/lastFrame/last_frame верхнего уровня и images верхнего уровня (1-е — первый кадр, 2-е — последний, не больше 2) тоже преобразуются в media. Нераспознанные поля материалов возвращают 400.
  • У Grok поля aspect_ratio и ratio равнозначны; если передано несколько полей соотношения сторон, их значения должны совпадать. Первый кадр — не больше одного; последний кадр передаётся в last_frame, ключевые кадры — в keyframes, референсные изображения — в reference_images, а grok-imagine-video-1.5 также может выбрать до 3 предустановленных голосов через reference_audios. Подробнее — в Grok Video API.
  • minimax-h3 принимает референсные изображения в metadata.referenceImages, первый и последний кадр — в metadata.firstFrame/lastFrame; назначение images верхнего уровня не фиксировано, указывайте его явно через metadata.referenceImages / metadata.firstFrame. 480P и 4K сняты с продажи.
  • Veo и Gemini Omni принимают референсное видео в video/videos верхнего уровня, а не в metadata.referenceVideos. gemini-omni-flash выведена из эксплуатации; Gemini Omni и veo-3.1-fast не поддерживают продление видео, а veo-3.1-fast всегда выдаёт видео 720P длительностью 8 секунд со звуком.
  • Seedance (doubao-seedance-2.0, doubao-seedance-2.5, doubao-seedance-2.5-flash, doubao-seedance-2.0-fast, doubao-seedance-2.0-mini) оплачивается по фактическим токенам; референсные материалы можно передавать в полях images, videos, audios, firstFrame/lastFrame и других, а также в массиве content из Volcengine Ark — на верхнем уровне или в metadata. Ссылки https:// на изображения и видео автоматически сохраняются в библиотеку, поэтому в качестве референса можно использовать фотографии и видео реальных людей. Готовое видео — это ссылка Ark, которая перестаёт работать через 24 часа; отправленную задачу отменить нельзя. Подробнее — в Seedance Video API.
  • seedance-2.0, seedance-2.5, seedance-2.0-mini, seedance-2.0-fast (посекундная оплата) выведены из эксплуатации 2026-11-12; ещё раньше из обращения выведены SD2.0, SD2.5 и названия моделей Seedance с суффиксом «官方版». Используйте одноимённые модели с префиксом doubao-.

7. Ответ на создание

После успешной отправки сразу возвращается публичный ID задачи:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "<MODEL_ID>",
  "status": "queued",
  "progress": 0,
  "created_at": 1788249600
}

Сохраните id. Стандартный эндпоинт не гарантирует возврат task_id; новые интеграции должны использовать id.

HTTP 200 означает «задача принята», а не то, что видео уже сгенерировано.

8. Опрос задачи

curl 'https://api.88api.ai/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Authorization: Bearer sk-xxxx'

Единые статусы

statusЗначениеДействие клиента
queuedПринята, в очередиПродолжать ждать
in_progressГенерируетсяПродолжать ждать
completedЗавершенаПрочитать возвращённый url, воспроизвести, скачать или использовать снова
failedОшибкаПрочитать error.code и error.message
unknownНеизвестный статусНенадолго повторить запрос; если статус сохраняется, обратиться в поддержку

Пример ответа о завершении:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "<MODEL_ID>",
  "status": "completed",
  "progress": 100,
  "created_at": 1788249600,
  "completed_at": 1788250200,
  "url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4",
  "video_url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4",
  "result_url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4"
}

Пример ответа об ошибке:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "<MODEL_ID>",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "video_generation_failed",
    "message": "Не удалось сгенерировать видео"
  }
}

Стратегия опроса

  1. После отправки подождите 3–5 секунд перед первым запросом.
  2. Рекомендуется опрашивать раз в 10–15 секунд, а не каждую секунду.
  3. Интерактивный клиент может закладывать бюджет ожидания 15 минут; сервер может сохранить ID задачи и продолжать опрос. Прекращение ожидания на клиенте не означает сбой, отмену или возврат средств.
  4. Пока задача в queued или in_progress, не отправляйте её повторно — иначе возможна повторная оплата.

Тайм-аут отдельного HTTP-запроса, общее время ожидания клиента и срок задачи на сервере — разные понятия. Не определяйте успех только по progress=100, ориентируйтесь на status. После восстановления страницы или сети можно продолжить опрос исходной задачи.

9. Получение видеофайла

Когда задача перешла в completed, в первую очередь используйте url из ответа на запрос; совместимые клиенты могут читать video_url / result_url. Эти поля — результат, выданный сервером; не составляйте путь к медиафайлу из ID задачи или внутренних ID.

# RESULT_URL берётся из ответа о завершении без изменений; не отправляйте API Key на медиасервер.
curl --fail --location "$RESULT_URL" --output result.mp4

Пояснения:

  • Клиент должен разрешать перенаправления HTTP 3xx; для curl нужен --location.
  • URL результата может быть адресом https://assets.88api.ai/media/... или исходным адресом платформы модели; используйте его как есть, не удаляйте и не изменяйте параметры и не заменяйте домен. Не добавляйте параметры запроса к адресам assets (это вернёт 400).
  • Старый /v1/videos/{id}/content выполняет совместимое перенаправление 307 для архивированных видео только ради совместимости со старыми клиентами; не используйте его как постоянную точку входа для получения результатов. При ответе 404 снова запросите задачу, чтобы получить фактический адрес результата, и не запускайте генерацию повторно вслепую.
  • Не составляйте, не сохраняйте и не используйте никакие другие ID задач; используйте только публичный id из ответа на отправку.
  • Если готовый результат нужно хранить долго, скачайте его в собственное объектное хранилище после завершения.

9.1 Хранение, воспроизведение и использование в других моделях

  • Загруженные на сайт материалы и архивированные видео хранятся 30 дней с момента загрузки соответствующего объекта; повторное чтение, запрос старой задачи и повторное использование срок не продлевают и новую копию не создают. Срок действия прямых ссылок платформы модели определяется самой платформой и может быть короче 30 дней (например, у готовых видео Seedance — всего 24 часа), поэтому скачивайте результаты своевременно.
  • Отсутствие параметров подписи и необходимости входа не означает бессрочного хранения: по истечении срока файл возвращает 410, а после очистки по жизненному циклу — возможно, 404. Наличие записи о задаче не означает, что бинарный файл всё ещё существует.
  • Публичные медиафайлы поддерживают GET, HEAD, одиночный Range и кросс-доменное чтение из браузера. Можно прочитать X-Media-Expires-At (Unix-секунды); успешный Range обычно возвращает 206. Кеширование не продлевает исходный срок действия и не гарантирует одинаковую скорость скачивания во всех регионах.
  • Результаты Veo можно использовать как входные данные для других моделей, поддерживающих референсное видео, если адрес ещё действителен, а формат, размеры и длительность соответствуют требованиям целевой модели. Поместите URL результата прямо в поле референса этой модели — скачивать и загружать заново не нужно; veo-3.1 принимает входное видео только при продлении, veo-3.1-fast входное видео не принимает, и ни одна из них не поддерживает референсное видео.
{
  "model": "<MODEL_ID>",
  "prompt": "Сохранить объект и движение из референсного видео и продолжить кадр",
  "duration": 4,
  "ratio": "16:9",
  "metadata": {
    "referenceVideos": ["<полный HTTPS URL результата предыдущей задачи>"]
  }
}

10. Полный пример опроса на JavaScript

Node.js 22+; на сервере задайте API_KEY, MODEL_ID и REFERENCE_FILE (путь к MP4-файлу). MODEL_ID должен быть взят из ответа GET /v1/models для текущего API-ключа. Если задать TASK_ID, пример сразу возобновит старую задачу без повторной загрузки и генерации. Пример создаёт одну платную генерацию и в конце лишь выводит тело следующего запроса, не запуская вторую генерацию автоматически. Для наглядности используется буферизация файла; при пакетной обработке больших файлов ограничивайте параллелизм.

// video-api-example.mjs — Node.js 22+, run with API_KEY, MODEL_ID, and REFERENCE_FILE.
import { readFile, stat } from "node:fs/promises";
import { createHash } from "node:crypto";

const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error("Set API_KEY on your server");
const baseUrl = "https://api.88api.ai";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function apiJSON(path, body) {
  // No automatic POST retry: a timed-out create may already have been accepted.
  const response = await fetch(baseUrl + path, {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(120000),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  return response.json();
}

async function uploadMedia(file, mimeType) {
  const info = await stat(file);
  if (!info.isFile() || info.size < 1 || info.size > 100000000) {
    throw new Error("File must contain 1–100000000 bytes");
  }
  const bytes = await readFile(file);
  const permit = await apiJSON("/v1/media/uploads", {
    size: bytes.length, mime_type: mimeType,
    sha256: createHash("sha256").update(bytes).digest("base64url"),
  });
  const target = new URL(permit.upload_url);
  if (target.origin !== "https://assets.88api.ai" || permit.method !== "PUT") {
    throw new Error("Unexpected upload destination; do not send credentials");
  }
  const response = await fetch(target, {
    method: "PUT", headers: permit.headers, body: bytes,
    redirect: "error", signal: AbortSignal.timeout(120000),
  });
  // A 409/ambiguous upload is not automatically retried; HEAD permit.url first.
  if (response.status !== 201) throw new Error(`Upload HTTP ${response.status}`);
  return response.json();
}

async function waitForVideo(id, budgetMs = 15 * 60 * 1000) {
  const deadline = Date.now() + budgetMs;
  let delay = 4000;
  while (Date.now() < deadline) {
    await sleep(Math.min(delay, deadline - Date.now()));
    const remaining = deadline - Date.now();
    if (remaining <= 0) break;
    let response, state;
    try {
      response = await fetch(`${baseUrl}/v1/videos/${encodeURIComponent(id)}`, {
        headers: { Authorization: `Bearer ${apiKey}` },
        signal: AbortSignal.timeout(Math.min(30000, remaining)),
      });
      if (response.ok) state = await response.json();
    } catch {
      delay = Math.min(delay * 2, 60000);
      continue; // Retry a read, never create a replacement task.
    }
    if (response.status === 429 || response.status >= 500) {
      const retryAfter = response.headers.get("Retry-After");
      const seconds = retryAfter && /^\d+$/.test(retryAfter)
        ? Number(retryAfter)
        : (Date.parse(retryAfter || "") - Date.now()) / 1000;
      delay = Number.isFinite(seconds) && seconds > 0
        ? Math.max(1000, seconds * 1000)
        : Math.min(delay * 2, 60000);
      await response.body?.cancel();
      continue;
    }
    if (!response.ok) throw new Error(`Task ${id}: HTTP ${response.status}`);
    if (state.status === "completed") {
      const result = state.url || state.video_url || state.result_url;
      if (typeof result !== "string" || new URL(result).protocol !== "https:") {
        throw new Error(`Task ${id} completed without a usable HTTPS result URL`);
      }
      return result; // Keep official URLs and capability query parameters intact.
    }
    if (state.status === "failed") {
      throw new Error(`Task ${id}: ${state.error?.message || "video generation failed"}`);
    }
    if (!["queued", "in_progress", "unknown"].includes(state.status)) {
      throw new Error(`Task ${id}: unexpected status ${state.status}`);
    }
    delay = 12000;
  }
  throw new Error(`Stopped waiting for ${id}; save this ID and query later. Not cancelled.`);
}

async function main() {
  // Resume a saved task without uploading or creating another paid task.
  let id = process.env.TASK_ID;
  if (!id) {
    if (!process.env.MODEL_ID) throw new Error("Set MODEL_ID from GET /v1/models");
    if (!process.env.REFERENCE_FILE) throw new Error("Set REFERENCE_FILE");
    const media = await uploadMedia(process.env.REFERENCE_FILE, "video/mp4");
    const task = await apiJSON("/v1/videos", {
      model: process.env.MODEL_ID, prompt: "Сохранить объект и движение из референсного видео и продолжить кадр",
      duration: 4, ratio: "16:9", metadata: { referenceVideos: [media.url] },
    });
    id = task.id;
    if (!id) throw new Error("Create response did not contain a task ID; do not blindly retry");
    console.log("Save task ID:", id); // Persist to your database in production.
  }
  const resultURL = await waitForVideo(id);
  console.log("Result URL:", resultURL); // This grants media access; do not log publicly.
  // This only shows the NEXT request body; it does not create a second paid task.
  console.log(JSON.stringify({
    model: process.env.MODEL_ID, prompt: "Сохранить объект и движение из референсного видео и продолжить кадр",
    duration: 4, ratio: "16:9", metadata: { referenceVideos: [resultURL] },
  }, null, 2));
}

await main();

11. Обработка ошибок и повторы

СитуацияРекомендация
HTTP 400Проверьте название модели, длительность, соотношение сторон, количество материалов и расположение полей
HTTP 401API-ключ отсутствует, неверен или недействителен
HTTP 403У текущего ключа нет доступа к модели или группе
HTTP 404Задача не существует, не принадлежит текущему аккаунту или результат ещё не готов
Загрузка: HTTP 409Объект уже существует и не может быть перезаписан; проверьте через HEAD и используйте успешно загруженный адрес
Медиафайл: HTTP 410Срок файла истёк; чтение и повторное использование его не продлевают, после очистки возможен и 404
Загрузка: HTTP 415Сигнатура файла не соответствует заявленному MIME; смена расширения не превращает файл в другой формат
Медиафайл: HTTP 416Range выходит за границы файла или не поддерживается; уточните размер повторным HEAD
HTTP 429Слишком частые запросы или ограничение квоты; ориентируйтесь на Retry-After или используйте экспоненциальную задержку
HTTP 5xxВременная ошибка сервиса; запросы статуса можно повторять с задержкой
status=failedHTTP-запрос успешен, но генерация не удалась; прочитайте error.message
Не удалось скачать материалУбедитесь, что URL публично доступен, не истёк и не защищён от хотлинкинга или аутентификацией
unsupported_reference_mediaМодель не поддерживает этот тип референса; загрузка или смена домена не помогут
must be a public HTTPS URLСначала загрузите локальный файл; нельзя передавать Blob, Data URL, HTTP или адреса, требующие входа
input_download_failedПроверьте фактическую доступность для целевого сервиса, DNS и сеть, срок действия медиафайла — а не только то, открывается ли адрес на вашей машине
Блокировка модерацией контентаИзмените промпт или референсные материалы; не повторяйте запрос бесконечно без изменений

POST /v1/videos пока не поддерживает пользовательский ключ идемпотентности. Если после отправки полного запроса произошёл сетевой тайм-аут, не отправляйте его сразу повторно вслепую — иначе может быть создано и оплачено несколько задач.

Содержание

1. Минимальные правила единой интеграции
2. Краткий справочник по эндпоинтам
Заголовки запроса
Сначала получите ID моделей, доступных аккаунту
3. Стандартный запрос на создание
Минимальный запрос «текст в видео»
Общие поля запроса
Как запросить разрешение
Модели с фиксированным разрешением: выбор через ID модели
Модели с выбором разрешения: поле resolution
4. Референсные изображения, видео и аудио
3.1 Референсные изображения
3.2 Референсное видео
3.3 Референсное аудио
3.4 Смешанные материалы для моделей с несколькими референсами
3.5 Требования к URL медиафайлов
3.6 Загрузка локальных файлов: сначала запрос, затем PUT
5. Режим первого и последнего кадра для поддерживающих моделей
6. Таблица возможностей текущих видеомоделей
Спецификации по брендам
Сводная таблица возможностей моделей
Особые правила моделей
7. Ответ на создание
8. Опрос задачи
Единые статусы
Стратегия опроса
9. Получение видеофайла
9.1 Хранение, воспроизведение и использование в других моделях
10. Полный пример опроса на JavaScript
11. Обработка ошибок и повторы