Полная спецификация 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. Минимальные правила единой интеграции
Если один клиент должен работать с несколькими видеомоделями, достаточно зафиксировать следующий порядок:
- Запросите
GET /v1/modelsс текущим API-ключом. - Выберите из ответа
idмодели, к которой у вашего аккаунта действительно есть доступ; не прописывайте жёстко в глобальной конфигурации названия из каталога моделей, исторические названия или названия, которые видны другим аккаунтам. - Отправляйте задачи в едином формате запроса
POST /v1/videos. - Запрашивайте задачу только по публичному
idиз ответа; не разбирайте и не составляйте никакие другие ID задач. - Получайте видео по
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/jsonAPI-ключ должен храниться на сервере; его нельзя встраивать во фронтенд браузера, мини-программы или мобильного приложения.
| Операция | Аутентификация |
|---|---|
| Создание и запрос задач; запрос разрешения на загрузку | 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"
}Общие поля запроса
| Поле | Тип | Обязательно | Пояснение |
|---|---|---|---|
model | string | Да | Точный ID модели, полученный текущим API-ключом через GET /v1/models |
prompt | string | По условию | Текстовый промпт; лишь некоторые модели допускают пустое значение при наличии референсов |
negative_prompt | string | Нет | Негативный промпт для моделей с несколькими референсами; для Veo можно также указать metadata.negativePrompt |
duration | integer | Нет | Длительность видео в секундах; одно из двух с seconds |
seconds | string | Нет | Длительность видео строкой, например "8" |
ratio | string | Нет | Рекомендуемое поле соотношения сторон, например 16:9, 9:16 |
aspect_ratio | string | Нет | Совместимый псевдоним ratio; допустимые значения зависят от целевой модели |
size | string | Нет | Поле совместимости; в новых интеграциях не передавайте через него соотношение сторон |
resolution | string | Нет | Только если целевая модель поддерживает, например 480p, 720p, 1080p, 4k |
image | string | Нет | URL одного референсного изображения |
images | string[] | Нет | Массив URL референсных изображений, рекомендуемый способ |
video | string | Нет | URL одного референсного видео; для Gemini Omni обязательно это поле верхнего уровня |
videos | string[] | Нет | Массив референсных видео; другие модели с несколькими референсами используют metadata.referenceVideos |
seed | integer | Нет | Случайное зерно |
generateAudio / generate_audio | boolean | Нет | Включает синхронную генерацию звука на поддерживающих моделях; только если модель это допускает |
metadata | object | Нет | Расширенные поля: референсные видео и аудио, первый и последний кадр и т. д. |
Как запросить разрешение
Эндпоинт создания один для всех, но способ выбора разрешения у моделей может различаться. Сначала ориентируйтесь на 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 медиафайлов
- Референсные видео и аудио передаются как публичные HTTPS URL, доступные для анонимного скачивания.
blob:, локальные пути иdata:video/...не являются универсальным способом передачи референсного видео; локальные файлы сначала загрузите, как описано в следующем разделе. - URL не должен зависеть от Cookie, сессии браузера, Referer или нестандартных заголовков.
- Нельзя использовать
localhost, частные IP-адреса, имена сервисов Docker или адреса, доступные только из вашей внутренней сети. - URL должен оставаться действительным всё время генерации; рекомендуемый срок действия — не менее 60 минут.
- Для изображений рекомендуются JPG, PNG или WebP; для видео — MP4/MOV; для аудио — MP3/WAV.
- Рекомендуется не более 50 МБ на видеофрагмент и не более 15 МБ на аудиофрагмент; слишком большие файлы могут не пройти этап скачивания или модерации.
- Прежде чем использовать сторонние материалы, убедитесь, что у вас есть необходимые авторские права, права на изображение и разрешения на использование.
То, что страница материала открывается, ещё не значит, что байты видео можно скачать: адрес должен отдавать сам медиафайл, а не 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 при загрузке |
sha256 | 32-байтовый дайджест 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 моделей.
Спецификации по брендам
Запись параметров и поля материалов у разных брендов не полностью совпадают; перед интеграцией прочитайте страницу соответствующего бренда:
| Страница бренда | Модели |
|---|---|
| Seedance | doubao-seedance-2.0, doubao-seedance-2.5, doubao-seedance-2.5-flash, doubao-seedance-2.0-fast, doubao-seedance-2.0-mini |
veo-3.1, veo-3.1-fast, gemini-omni-flash-1.1, gemini-omni-flash-1.2 | |
| MiniMax | minimax-h3 |
| Wan | wan3.0-video, wan3.0-video-prime |
| Grok | grok-imagine-video, grok-imagine-video-1.5 |
Сводная таблица возможностей моделей
| № | Возможности / публичное название | Длительность | Соотношение сторон | Выход | Лимит изображений / видео / аудио | Первый и последний кадр | Управление звуком |
|---|---|---|---|---|---|---|---|
| 1 | doubao-seedance-2.0 | 4–15 с; поддерживается -1 | 16:9 4:3 1:1 3:4 9:16 21:9 adaptive | 480P/720P/1080P/4K, по умолчанию 720P | 9 / 3 / 3 | Да, взаимоисключающе с обычными материалами | Звук по умолчанию, можно отключить |
| 2 | doubao-seedance-2.5 | 4–30 с; поддерживается -1 | То же | 480P/720P/1080P, по умолчанию 720P | 30 / 10 / 10 | Да, взаимоисключающе с обычными материалами | Звук по умолчанию, можно отключить |
| 3 | doubao-seedance-2.5-flash | 4–30 с; поддерживается -1 | То же | 480P/720P, по умолчанию 720P | 10 / 5 / 5 | Да, взаимоисключающе с обычными материалами; с первым кадром соотношение сторон берётся из изображения первого кадра | Звук по умолчанию, можно отключить |
| 4 | doubao-seedance-2.0-fast | 4–15 с; поддерживается -1 | То же | 480P/720P, по умолчанию 720P | 9 / 3 / 3 | Да, взаимоисключающе с обычными материалами | Звук по умолчанию, можно отключить |
| 5 | doubao-seedance-2.0-mini | 4–15 с; поддерживается -1 | То же | 480P/720P, по умолчанию 720P | 9 / 3 / 3 | Да, взаимоисключающе с обычными материалами | Звук по умолчанию, можно отключить |
| 6 | veo-3.1 | 4/6/8 с; с референсными изображениями — фиксированно 8 с; каждое продление добавляет 7 с | 16:9 9:16 | 720P/1080P/4K | 3 / 0 / 0 | Первый кадр, первый и последний кадр, референсные изображения | Нативный звук, отключается через generate_audio |
| 7 | veo-3.1-fast | Всегда 8 с | 16:9 9:16 | Всегда 720P | 3 / 0 / 0 | Первый кадр, первый и последний кадр, референсные изображения | Звук всегда есть |
| 8 | gemini-omni-flash-1.1 | 3–10 с, по умолчанию 3 с | 16:9 9:16 | 720P/1080P/4K | 10 / 3 / 0 | Первый кадр, первый и последний кадр | Не поддерживается |
| 9 | gemini-omni-flash-1.2 | 3–15 с, по умолчанию 3 с | 16:9 9:16 | 720P/1080P/4K | 10 / 3 / 0 | Первый кадр, первый и последний кадр | Не поддерживается |
| 10 | minimax-h3 | 4–15 с, по умолчанию 5 с | 16:9 (по умолчанию) 9:16 1:1 4:3 3:4 21:9; в 1080P/2K только 16:9 9:16 | 768P/1080P/2K (апскейл), по умолчанию 768P | 9 (в 1080P/2K — 6) / – / 3 | Только 768P, взаимоисключающе с обычными материалами | Звуковая дорожка всегда есть, не настраивается |
| 11 | wan3.0-video | 2–30 с, по умолчанию 5 с; поддерживается -1 | adaptive (по умолчанию) 16:9 9:16 1:1 4:3 3:4 21:9 | 480P/720P/1080P, по умолчанию 1080P | 10 / 5 / 5 (через массив media) | Да, взаимоисключающе с обычными материалами | Не настраивается |
| 12 | wan3.0-video-prime | То же | То же | То же | То же | То же | Не настраивается |
| 13 | grok-imagine-video | 1–15 с, по умолчанию 8 с; с референсными изображениями не дольше 10 с | 16:9 9:16 1:1 4:3 3:4 3:2 2:3 (через aspect_ratio) | 480P/720P | 14 / 0 / 0 | Только первый кадр, не вместе с референсными изображениями | Не поддерживается |
| 14 | grok-imagine-video-1.5 | 1–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": "Не удалось сгенерировать видео"
}
}Стратегия опроса
- После отправки подождите 3–5 секунд перед первым запросом.
- Рекомендуется опрашивать раз в 10–15 секунд, а не каждую секунду.
- Интерактивный клиент может закладывать бюджет ожидания 15 минут; сервер может сохранить ID задачи и продолжать опрос. Прекращение ожидания на клиенте не означает сбой, отмену или возврат средств.
- Пока задача в
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 401 | API-ключ отсутствует, неверен или недействителен |
| HTTP 403 | У текущего ключа нет доступа к модели или группе |
| HTTP 404 | Задача не существует, не принадлежит текущему аккаунту или результат ещё не готов |
| Загрузка: HTTP 409 | Объект уже существует и не может быть перезаписан; проверьте через HEAD и используйте успешно загруженный адрес |
| Медиафайл: HTTP 410 | Срок файла истёк; чтение и повторное использование его не продлевают, после очистки возможен и 404 |
| Загрузка: HTTP 415 | Сигнатура файла не соответствует заявленному MIME; смена расширения не превращает файл в другой формат |
| Медиафайл: HTTP 416 | Range выходит за границы файла или не поддерживается; уточните размер повторным HEAD |
| HTTP 429 | Слишком частые запросы или ограничение квоты; ориентируйтесь на Retry-After или используйте экспоненциальную задержку |
| HTTP 5xx | Временная ошибка сервиса; запросы статуса можно повторять с задержкой |
status=failed | HTTP-запрос успешен, но генерация не удалась; прочитайте error.message |
| Не удалось скачать материал | Убедитесь, что URL публично доступен, не истёк и не защищён от хотлинкинга или аутентификацией |
unsupported_reference_media | Модель не поддерживает этот тип референса; загрузка или смена домена не помогут |
must be a public HTTPS URL | Сначала загрузите локальный файл; нельзя передавать Blob, Data URL, HTTP или адреса, требующие входа |
input_download_failed | Проверьте фактическую доступность для целевого сервиса, DNS и сеть, срок действия медиафайла — а не только то, открывается ли адрес на вашей машине |
| Блокировка модерацией контента | Измените промпт или референсные материалы; не повторяйте запрос бесконечно без изменений |
POST /v1/videos пока не поддерживает пользовательский ключ идемпотентности. Если после отправки полного запроса произошёл сетевой тайм-аут, не отправляйте его сразу повторно вслепую — иначе может быть создано и оплачено несколько задач.
Речевые API 88API: TTS и STT
Документация по голосовым моделям Grok и Gemini: синтез речи через /v1/audio/speech, потоковый синтез речи через WebSocket, голосовой диалог Grok в реальном времени, транскрибация через /v1/audio/transcriptions и через чат с аудио; все голоса, форматы вывода, поля запроса, примеры cURL, OpenAI SDK, Python и Node.js.
Seedance Video API
Разрешение, длительность, соотношение сторон, референсные материалы, референсы с реальными людьми, первый и последний кадр, редактирование и продление видео, черновики, последний кадр и скачивание результатов для Seedance 2.0, 2.0 Fast, 2.0 Mini, 2.5 и 2.5 Flash (оплата по токенам).