创建视频任务

视频生成是异步任务：创建成功只表示任务已受理，需要保存响应里的 id 再查询任务读取进度和结果。一次创建请求对应一个任务，查询和页面刷新不会重复创建或重复计费。

公共约定（基础地址、认证、响应结构、限流、幂等）见认证与基础规范。

接口一览

用途	方法	路径	详细文档
创建视频任务	POST	`/v1/video/generations`	本页
创建视频任务（OpenAI 兼容写法）	POST	`/v1/videos`	本页
查询视频任务	GET	`/v1/video/generations/{task_id}`	查询视频任务
查询视频任务（OpenAI 兼容写法）	GET	`/v1/videos/{task_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"

创建视频任务

POST/v1/video/generations

认证方式

Authorization: Bearer <API_KEY>，使用控制台「API 密钥」创建的平台 API Key。

请求体 · application/json

Prop

Type

prompt 与 content 至少提供一种文本输入：只提交 content 时，平台会把第一个 type: "text" 元素的 text 作为提示词。model 缺失时返回 HTTP 400，不要向模型传入详情页未声明支持的参数。

content 元素

`type`	内容字段	`role`	说明
`text`	`text`	省略	文本提示词
`image_url`	`image_url.url`	`reference_image`	普通参考图，可提交多张
`image_url`	`image_url.url`	`first_frame`	视频首帧
`image_url`	`image_url.url`	`last_frame`	视频尾帧
`video_url`	`video_url.url`	`reference_video`	动作、运镜、节奏或画面参考视频
`audio_url`	`audio_url.url`	`reference_audio`	声音或节奏参考

公网素材必须使用可直接下载的 HTTPS URL，不能依赖 Cookie、Referer 或登录页面；图片也可以按模型支持情况使用 data:image/...;base64,...。素材库中状态为 Active 的素材使用 asset://<asset_id>；真人素材只能提交到支持真人素材库的模型。

content 数组中的 image_url、video_url、audio_url 会按原类型传给上游；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 数组。

请求示例

文生视频

content 是一个数组：文字用 { "type": "text", "text": "..." }，参考图用 type: "image_url"。纯文字生成时只放一个 text 项即可。

resolution、ratio、duration 必须落在当前模型支持的档位内。 generate_audio 与 watermark 不是所有模型都接受。

提交成功后只依赖返回的 id / task_id 去查询，不要重新创建任务。

纯文本生成视频

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。

响应参数

参数	类型	说明
`id`	string	公开任务 ID，查询任务时使用
`task_id`	string	与 `id` 相同的兼容字段
`model`	string	本次请求使用的模型 ID
`status`	string	受理成功时为 `queued`
`created_at`	integer	任务创建时间（Unix 秒）
`object`	string	可选；创建响应可能省略，查询成功后通常为 `video`
`progress`	integer	可选；创建响应可能省略，查询后返回当前进度

响应体

{
  "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
}

HTTP	常见原因	处理
`400`	缺少 `model`、JSON 格式错误、缺少提示词、参考素材角色或地址写错	按 `message` 修正后重新提交
`401`	API Key 缺失、失效或无权使用	更换有效 Key
`403`	余额或当前 Key 额度不足以覆盖预估费用（`insufficient_user_quota`）	充值或调低时长/清晰度等参数后重新提交，此时不会创建任务
`429`	在途任务达到并发上限（`task_concurrency_exceeded`）	按提示里的「当前 N 个 / 上限 M」等待已有任务完成后再提交
`429`	当前分组上游负载已饱和或请求频率受限	稍后重试，避免并发重复提交
`500`	任务创建失败	读取错误码；已有任务 ID 时继续查询原任务
`503`	当前模型不可用	重新查询 `/v1/models`，切换可用模型或稍后再试

并发与提交节奏

生成任务在后台并发执行，提交与结果下载都会占用平台出口带宽，因此平台对同时在处理中的任务数量设了上限：每个账号同时最多 2000 个。达到上限后再提交会返回：

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

建议这样组织批量任务：

先提交一批，等任务进入 completed / failed 终态后再提交下一批，不要用循环连续重试同一个请求；
单次提交的参考图越多、分辨率越高，占用出口带宽越久，同时提交的任务要相应减少；
需要同时产出多条视频时，按任务 ID 记录进度，等待上一批完成后继续，避免重复提交导致重复计费。

计费与参数校验

视频任务完成时按实际用量结算：创建成功只代表任务已受理，提交阶段不会预先扣费，也不会产生任何账单记录；任务完成后账单里只出现一条实际扣费记录。
提交时会校验账户余额（或当前 API Key 额度）是否覆盖本次预估额度。不足时返回 HTTP 403 与 insufficient_user_quota，错误信息会给出「本次预计需要 …，当前可用 …」，补齐余额或调整参数后重新提交即可；此时不会创建任务，也不会产生费用。
提交前会校验请求体，缺少内容时直接返回可读提示，不需要靠上游报错定位：

提示	原因	处理
`缺少提示词：请在 prompt 或 content 的 text 元素中提供文本描述`	没有文本描述	补上 `prompt`，或在 `content` 里加一个 `type: "text"` 元素
`content[0].role 不支持 "xxx"，可用值：reference_image、first_frame、last_frame、reference_video、reference_audio`	参考素材角色写错	按提示改用允许的角色
`content[0].image_url.url 不能为空`	参考素材地址为空	填 `asset://<素材ID>`、可公开下载的 HTTPS 地址或 `data:` 内联数据
`content[0] 参考素材不可用：地址需要是 https:// 公网地址、asset://<素材ID> 或 data: 内联数据`	素材地址协议不支持	改为平台素材 ID、HTTPS 直链或 `data:` 内联数据，不要用 `ftp://`、`file://` 或内网地址
`content[0] 参考素材不可用：素材库中找不到素材 xxx`	`asset://` 素材不存在，或不属于当前账号	先在素材库提交并等待状态变为可用，或核对账号
`duration 必须大于 0`	时长参数非法	改为模型支持的时长

本页目录