Создание видеозадачи

Генерация видео — асинхронная задача: успешное создание лишь означает, что задача принята; сохраните id из ответа и затем запросите задачу, чтобы получить прогресс и результат. Один запрос создания соответствует одной задаче; запросы и обновление страницы не приводят к повторному созданию или повторному списанию средств.

Общие соглашения (базовый адрес, аутентификация, структура ответа, ограничение частоты запросов, идемпотентность) см. в разделе Аутентификация и базовые соглашения.

Обзор интерфейсов

Тело запроса, тело ответа и ID задачи у двух форматов полностью совпадают, можно выбрать любой; один и тот же ID задачи можно запросить по обеим группам путей.

Старым клиентам достаточно продолжать использовать /v1/video/generations — платформа на уровне входной точки обработает его через плагин видеозадач /v1/videos, менять поля или пути не нужно.

Подготовка переменных

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_API_ORIGIN="https://locopalai.com"
export LOCOPAL_VIDEO_MODEL_ID="从 /v1/models 返回的视频模型 ID"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/reference.png"
export LOCOPAL_VIDEO_URL="https://你的对象存储域名/reference.mp4"
export LOCOPAL_AUDIO_URL="https://你的对象存储域名/reference.mp3"
export LOCOPAL_TASK_ID="创建视频后响应中的 id"

Создание видеозадачи

Способ аутентификации

Authorization: Bearer <API_KEY>, используется платформенный API Key, созданный на странице «Ключи API» в консоли.

Тело запроса · application/json

Укажите хотя бы один текстовый ввод — prompt или content: если передан только content, платформа использует text первого элемента type: "text" как промпт. При отсутствии model возвращается HTTP 400; не передавайте модели параметры, поддержка которых не указана на странице описания.

Элементы content

Публичные материалы должны использовать напрямую загружаемый HTTPS URL и не зависеть от Cookie, Referer или страниц входа; изображения также могут использоваться в формате data:image/...;base64,... в зависимости от поддержки модели. Материалы библиотеки материалов в статусе Active используются через asset://<asset_id>; материалы реального человека можно отправлять только в модели с поддержкой библиотеки материалов реальных людей.

image_url, video_url и audio_url в массиве content передаются вышестоящей стороне в исходном типе; параметры верхнего уровня, такие как duration, ratio, resolution, seed, watermark, generate_audio, также передаются вместе с задачей и не требуют дополнительной обёртки в metadata.

Если нужна только одна обычная референсная картинка, можно использовать сокращённое поле верхнего уровня image_url:

{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "prompt": "镜头缓慢推进",
  "image_url": "https://your-object-storage.example/reference.png",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

Платформа преобразует image_url верхнего уровня в один элемент содержимого с референсным изображением. Если нужны несколько изображений, первый и последний кадры, референсное видео или референсное аудио, используйте массив content.

Пример запроса

Генерация видео из текста

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    { "type": "text", "text": "雨后的城市街道，镜头从水面倒影缓慢抬升，电影感" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}
JSON

Генерация видео из одного изображения

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "人物自然转身，衣摆随风摆动，镜头轻微环绕" },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/reference.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

Первый и последний кадры

Первый и последний кадры должны быть помечены как first_frame и last_frame соответственно и использовать два разных изображения.

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "镜头从室内平滑移动到窗外城市夜景" },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": { "url": "https://你的对象存储域名/first.png" }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": { "url": "https://你的对象存储域名/last.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

Несколько изображений и референсное видео

Так называемое в бизнесе «глубокое видео» не имеет отдельного поля deep_video в публичном интерфейсе — оно передаётся как референсное видео: type = video_url, role = reference_video. Каждое референсное изображение занимает отдельный элемент content; нельзя помещать несколько URL в один image_url.url.

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物为主体，沿用图片2的服装，参考视频的动作节奏和运镜，保持人物身份与产品外观一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "$LOCOPAL_IMAGE_URL" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://你的素材ID" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/scene.png" }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": { "url": "$LOCOPAL_VIDEO_URL" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 7,
  "generate_audio": false,
  "watermark": false
}
JSON

Порядок массива — это порядок материалов. Рекомендуется явно указывать в промпте «изображение 1, изображение 2, изображение 3, референсное видео» и не полагаться на то, что сервер угадает порядок по именам файлов. Количество референсных изображений, наличие референсного видео и аудио, выходное разрешение и длительность определяются возможностями модели; подробнее см. в разделе Несколько изображений и референсное видео.

Несколько изображений, референсное аудио и фиксированное зерно

seed позволяет фиксировать результат сэмплирования; reference_audio служит референсом звука или ритма; duration, generate_audio, ratio, resolution, watermark — параметры верхнего уровня. Приведённый ниже пример соответствует часто используемым параметрам вертикального видео 9:16:

{
  "model": "doubao-seedance-2.0-D",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物和服装为主体，参考图片2的另一名角色，参考音频的情绪和节奏生成电影感画面，保持角色身份一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917114312-cyele" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917111324-mquys" }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": { "url": "https://your-object-storage.example/reference.mp3" }
    }
  ],
  "duration": 9,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

После успешного создания id / task_id из ответа по-прежнему опрашиваются в рамках процесса асинхронной задачи; референсное аудио должно быть HTTPS-адресом, доступным платформе, а материал asset:// должен предварительно находиться в статусе Active.

Параметры ответа

Тело ответа

{
  "created_at": 1789567067,
  "id": "task_QH33zpW2IRHEnrmBbZFvtPzodyXvevWu",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task_QH33zpW2IRHEnrmBbZFvtPzodyXvevWu"
}

Ответ создания не является фиксированным полным набором полей. Клиент должен полагаться на непустоту id / task_id и не считать наличие object или progress обязательным условием успешного приёма.

Получив HTTP 200 и ID задачи, даже при локальном тайм-ауте ожидания запрашивайте только исходную задачу и не создавайте её автоматически заново.

Ответ с ошибкой

При неудачной валидации параметров возвращается HTTP 400, code равен invalid_request, а message прямо указывает, что отсутствует или указано неверно:

{
  "code": "invalid_request",
  "message": "缺少提示词：请在 prompt 或 content 的 text 元素中提供文本描述",
  "data": null
}

Если баланса или квоты текущего API Key недостаточно для покрытия прогнозируемой стоимости, возвращается HTTP 403; задача не создаётся и расходы не возникают:

{
  "code": "insufficient_user_quota",
  "message": "余额不足：本次预计需要 ＄11.500000，当前可用 ＄0.002000，请充值或调整参数后重试",
  "data": null
}

Параллельность и темп отправки

Задачи генерации выполняются параллельно в фоне, а отправка и загрузка результатов занимают исходящую полосу платформы, поэтому платформа ограничивает число задач, одновременно находящихся в обработке: не более 2000 на одну учётную запись. При отправке после достижения предела возвращается:

{
  "code": "task_concurrency_exceeded",
  "message": "当前账号有 2000 个生成任务正在处理中，已达到并发上限 2000，请等待任务完成后再提交",
  "data": null
}

Рекомендуется организовывать пакетные задачи так:

• Сначала отправьте партию, дождитесь перехода задач в конечное состояние completed / failed и только затем отправляйте следующую; не повторяйте один и тот же запрос в цикле подряд;
• Чем больше референсных изображений и выше разрешение в одной отправке, тем дольше занимается исходящая полоса, поэтому число одновременно отправляемых задач следует соответственно уменьшать;
• Если нужно одновременно получить несколько видео, отслеживайте прогресс по ID задач, дожидайтесь завершения предыдущей партии и продолжайте, чтобы избежать повторной отправки и повторного списания средств.

Тарификация и валидация параметров

• Видеозадачи рассчитываются по фактическому расходу при завершении: успешное создание лишь означает, что задача принята; на этапе отправки предварительное удержание не производится и записи в счёте не появляются; после завершения задачи в счёте появляется только одна запись о фактическом списании.
• При отправке проверяется, покрывает ли баланс учётной записи (или квота текущего API Key) прогнозируемую квоту. При недостатке возвращается HTTP 403 с insufficient_user_quota, а сообщение об ошибке содержит «требуется в этот раз …, доступно сейчас …»; пополните баланс или скорректируйте параметры и отправьте заново. Задача при этом не создаётся и расходы не возникают.
• Перед отправкой проверяется тело запроса; при отсутствии содержимого сразу возвращается читаемое сообщение, и искать причину по ошибке вышестоящей стороны не требуется: