视频模型统一接口文档

文档版本：2026-07-18
API Base URL：https://ai.lwaigc.cn
视频创建接口：POST /v1/videos

本文档面向中转站用户，说明当前生产环境可调用的视频模型、每个模型实际使用的请求字段，以及统一的任务、素材和下载接口。模型名区分大小写，请按文档原样发送。

1. 当前公开模型

已同时核对生产环境的启用渠道和模型路由，当前可调用的视频模型共 12 个。不同 API Key 所属分组不同，实际可调用模型以该 Key 请求 GET /v1/models 的结果为准。

请求中的 `model`	分辨率	时长	素材数量
`cy5-sd2.0fast`	480p / 720p	4–15 秒	9 图 / 3 视频 / 3 音频
`cy5-sd2.0Pro`	480p / 720p	4–15 秒	9 图 / 3 视频 / 3 音频
`firefly-seedance2-1080p`	固定 1080p	4–15 秒	9 图 / 3 视频 / 3 音频
`firefly-seedance2-720p`	固定 720p	4–15 秒	9 图 / 3 视频 / 3 音频
`firefly-seedance2-480p`	固定 480p	4–15 秒	9 图 / 3 视频 / 3 音频
`firefly-seedance2-fast-720p`	固定 720p	4–15 秒	9 图 / 3 视频 / 3 音频
`firefly-seedance2-fast-480p`	固定 480p	4–15 秒	9 图 / 3 视频 / 3 音频
`seedance2.0fast-720`	固定 720p	仅 10 或 15 秒	4 图 / 3 视频 / 1 音频
`seedance2.0pro-720`	固定 720p	4–15 秒	9 图 / 3 视频 / 3 音频
`sd2-431-720p-fast`	固定 720p	4–15 秒	4 图 / 3 视频 / 1 音频
`sd2-431-720p-pro`	固定 720p	4–15 秒	4 图 / 3 视频 / 1 音频
`grok-imagine-video-1.5-preview`	由 `size` 指定	6、10 或 15 秒	1 张首帧图片

已下线且没有启用调用渠道的旧模型不列入公开接口文档。

1.1 获取当前 Key 可用模型

http

GET /v1/models
Authorization: Bearer <API_KEY>

bash

curl 'https://ai.lwaigc.cn/v1/models' \
  -H 'Authorization: Bearer <API_KEY>'

目标模型没有出现在响应中时，表示该 Key 当前没有该模型的调用权限。

2. 接口总览

用途	方法	路径	鉴权
获取可用模型	`GET`	`/v1/models`	Bearer
创建视频任务	`POST`	`/v1/videos`	Bearer
查询视频任务	`GET`	`/v1/videos/{task_id}`	Bearer
播放或下载视频	`GET`	`/v1/videos/{task_id}/content`	Bearer
获取视频响应头	`HEAD`	`/v1/videos/{task_id}/content`	Bearer
带文件名的视频内容地址	`GET/HEAD`	`/v1/videos/{task_id}/content/{filename}`	Bearer
上传临时素材	`POST`	`/v1/assets`	Bearer
转存公网素材 URL	`POST`	`/v1/assets/url`	Bearer
读取签名素材	`GET/HEAD`	`/v1/assets/{asset_id}/content/{filename}`	签名参数
兼容音频引用上传	`POST`	`/v1/media-references`	Bearer

除服务端生成的签名素材 URL 外，接口统一使用：

http

Authorization: Bearer <API_KEY>

3. 创建视频任务

http

POST /v1/videos
Authorization: Bearer <API_KEY>
Idempotency-Key: client_xxx
Content-Type: application/json

3.1 所有模型共有字段

字段	类型	必填	说明
`model`	string	是	第 1 节中的准确模型名
`prompt`	string	是	视频提示词
`client_task_id`	string	强烈建议	稳定幂等标识，应与请求头 `Idempotency-Key` 完全一致

其余字段按第 4–8 节对应模型发送，不要混用不同模型的专属参数。

3.2 创建成功响应

首次创建成功返回 HTTP 202 Accepted：

json

{
  "id": "relay_video_xxx",
  "task_id": "relay_video_xxx",
  "client_task_id": "client_xxx",
  "status": "queued",
  "relay_state": "submitting",
  "progress": 0,
  "retry_after_ms": 6000
}

收到包含 task_id 的成功响应后，才表示任务已经建立。后续查询、播放和下载都使用返回的 relay_video_xxx。

4. CY5 Seedance 2.0

4.1 模型

`model`	版本	分辨率
`cy5-sd2.0fast`	Fast	`480p` 或 `720p`
`cy5-sd2.0Pro`	Pro	`480p` 或 `720p`

cy5-sd2.0Pro 中的 P 必须大写。

4.2 实际请求字段

字段	类型	必填	规则
`model`	string	是	固定为上表两个模型名之一
`prompt`	string	是	视频提示词
`seconds`	string 或 number	是	4–15 的整数
`resolution`	string	是	只能为 `480p` 或 `720p`
`aspect_ratio`	string	否	例如 `16:9`、`9:16`、`1:1`
`image_urls`	string[]	否	图片 URL，最多 9 张
`video_urls`	string[]	否	视频 URL，最多 3 条
`audio_urls`	string[]	否	音频 URL，最多 3 条
`images_base64`	string[]	否	图片 Data URL 或 Base64
`audios_base64`	string[]	否	音频 Data URL 或 Base64
`client_task_id`	string	强烈建议	视频任务幂等标识

兼容单素材字段 image_url、video_url、audio_url。兼容旧客户端使用 duration 表示秒数，但新客户端统一发送 seconds。

4.3 请求示例

json

{
  "model": "cy5-sd2.0fast",
  "client_task_id": "client_cy5_fast_xxx",
  "prompt": "保持人物外观一致，镜头缓慢向前推进",
  "seconds": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.png?expires=<EXPIRES>&signature=<SIGNATURE>"
  ]
}

5. Firefly Seedance 2.0

5.1 模型与固定分辨率

`model`	分辨率	版本
`firefly-seedance2-1080p`	1080p	标准版
`firefly-seedance2-720p`	720p	标准版
`firefly-seedance2-480p`	480p	标准版
`firefly-seedance2-fast-720p`	720p	Fast
`firefly-seedance2-fast-480p`	480p	Fast

分辨率已经包含在模型名中，不需要再发送 resolution。Fast 与标准版使用相同的请求字段。

5.2 实际请求字段

字段	类型	必填	规则
`model`	string	是	固定为上表五个模型名之一
`prompt`	string	是	视频提示词
`seconds`	string 或 number	是	4–15 的整数
`aspect_ratio`	string	否	例如 `16:9`、`9:16`、`1:1`
`image_urls`	string[]	否	图片 URL，最多 9 张
`video_urls`	string[]	否	视频 URL，最多 3 条
`audio_urls`	string[]	否	音频 URL，最多 3 条
`images_base64`	string[]	否	图片 Data URL 或 Base64
`audios_base64`	string[]	否	音频 Data URL 或 Base64
`client_task_id`	string	强烈建议	视频任务幂等标识

兼容单素材字段 image_url、video_url、audio_url。兼容旧客户端使用 duration 表示秒数，但新客户端统一发送 seconds。

5.3 请求示例

json

{
  "model": "firefly-seedance2-1080p",
  "client_task_id": "client_firefly_xxx",
  "prompt": "保持人物外观一致，镜头轻微环绕，衣物和头发自然摆动",
  "seconds": 8,
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.png?expires=<EXPIRES>&signature=<SIGNATURE>"
  ]
}

6. Seedance 2.0 Fast / Pro 720

6.1 模型能力

`model`	时长	素材数量
`seedance2.0fast-720`	仅 `10` 或 `15` 秒	4 图 / 3 视频 / 1 音频
`seedance2.0pro-720`	4–15 秒整数	9 图 / 3 视频 / 3 音频

两个模型均固定为 720p，不需要发送 resolution。

6.2 实际请求字段

字段	类型	必填	规则
`model`	string	是	固定为上表两个模型名之一
`prompt`	string	是	视频提示词
`seconds`	string 或 number	是	Fast 只能传 `10` 或 `15`；Pro 可传 4–15 的整数
`aspect_ratio`	string	否	例如 `16:9`、`9:16`、`1:1`
`image_urls`	string[]	否	Fast 最多 4 张；Pro 最多 9 张
`video_urls`	string[]	否	最多 3 条
`audio_urls`	string[]	否	Fast 最多 1 条；Pro 最多 3 条
`images_base64`	string[]	否	图片 Data URL 或 Base64
`audios_base64`	string[]	否	音频 Data URL 或 Base64
`client_task_id`	string	强烈建议	视频任务幂等标识

兼容单素材字段 image_url、video_url、audio_url。兼容旧客户端使用 duration 表示秒数，但新客户端统一发送 seconds。

6.3 Fast 示例

json

{
  "model": "seedance2.0fast-720",
  "client_task_id": "client_seedance_fast_xxx",
  "prompt": "人物自然转身看向镜头，背景光线缓慢变化",
  "seconds": 10,
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.jpg?expires=<EXPIRES>&signature=<SIGNATURE>"
  ]
}

6.4 Pro 示例

json

{
  "model": "seedance2.0pro-720",
  "client_task_id": "client_seedance_pro_xxx",
  "prompt": "镜头缓慢环绕主体，动作自然连贯，保持人物一致性",
  "seconds": 8,
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.png?expires=<EXPIRES>&signature=<SIGNATURE>"
  ]
}

7. SD2 431 Fast / Pro

7.1 模型能力

`model`	分辨率	时长	素材数量
`sd2-431-720p-fast`	固定 720p	4–15 秒	4 图 / 3 视频 / 1 音频
`sd2-431-720p-pro`	固定 720p	4–15 秒	4 图 / 3 视频 / 1 音频

7.2 实际请求字段

字段	类型	必填	规则
`model`	string	是	固定为上表两个模型名之一
`prompt`	string	是	视频提示词
`seconds`	string 或 number	是	4–15 的整数
`aspect_ratio`	string	否	例如 `16:9`、`9:16`、`1:1`
`image_urls`	string[]	否	图片 URL，最多 4 张
`video_urls`	string[]	否	视频 URL，最多 3 条
`audio_urls`	string[]	否	音频 URL，最多 1 条
`images_base64`	string[]	否	图片 Data URL 或 Base64
`audios_base64`	string[]	否	音频 Data URL 或 Base64
`client_task_id`	string	强烈建议	视频任务幂等标识

兼容单素材字段 image_url、video_url、audio_url。分辨率包含在模型名中，不需要发送 resolution。兼容旧客户端使用 duration 表示秒数。

7.3 请求示例

json

{
  "model": "sd2-431-720p-pro",
  "client_task_id": "client_sd2_431_xxx",
  "prompt": "第一张图片作为人物参考，镜头缓慢推进，动作自然",
  "seconds": 12,
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.png?expires=<EXPIRES>&signature=<SIGNATURE>"
  ]
}

8. Grok Imagine Video 1.5 Preview

8.1 模型名

text

grok-imagine-video-1.5-preview

8.2 实际请求字段

字段	类型	必填	说明
`model`	string	是	固定为 `grok-imagine-video-1.5-preview`
`prompt`	string	是	视频提示词
`images`	string[]	是	一张首帧图片，可发送 Data URL
`seconds`	string 或 number	是	只能为 `6`、`10` 或 `15`
`size`	string	是	例如 `1280x720`
`client_task_id`	string	强烈建议	视频任务幂等标识

8.3 示例

json

{
  "model": "grok-imagine-video-1.5-preview",
  "client_task_id": "client_grok_xxx",
  "prompt": "人物从首帧姿势开始自然转头，镜头轻微前推",
  "images": [
    "data:image/jpeg;base64,<BASE64_DATA>"
  ],
  "seconds": 10,
  "size": "1280x720"
}

9. 幂等创建和断线重试

每次业务生成应同时发送相同值：

http

Idempotency-Key: client_xxx

json

{
  "client_task_id": "client_xxx"
}

规则：

相同账号、相同 key、相同有效请求：返回原视频任务，不重复创建。
相同 key、不同请求体：返回 HTTP 409，错误码 idempotency_key_reused。
请求头与 body 中的值不一致：返回 HTTP 400，错误码 idempotency_key_mismatch。
client_task_id 最长 191 字节；建议只使用 ASCII 字母、数字、短横线和下划线。
幂等重放返回 HTTP 200；首次创建返回 HTTP 202。
创建响应丢失时，使用原 key 重发完全相同的请求，不要生成新 key。

幂等重放示例：

json

{
  "id": "relay_video_xxx",
  "task_id": "relay_video_xxx",
  "client_task_id": "client_xxx",
  "status": "in_progress",
  "relay_state": "polling",
  "progress": 31,
  "retry_after_ms": 6000
}

当前没有公开的“按 client_task_id 查询”接口。找回丢失的创建响应时，应使用相同幂等键重放原 POST。

10. 查询任务

http

GET /v1/videos/{task_id}
Authorization: Bearer <API_KEY>

bash

curl 'https://ai.lwaigc.cn/v1/videos/relay_video_xxx' \
  -H 'Authorization: Bearer <API_KEY>'

10.1 处理中

json

{
  "id": "relay_video_xxx",
  "task_id": "relay_video_xxx",
  "client_task_id": "client_xxx",
  "status": "in_progress",
  "relay_state": "polling",
  "progress": 47,
  "retry_after_ms": 6000
}

10.2 完成

json

{
  "id": "relay_video_xxx",
  "task_id": "relay_video_xxx",
  "status": "completed",
  "relay_state": "completed",
  "progress": 100
}

10.3 失败终态

任务业务失败通过 HTTP 200 返回终态：

json

{
  "id": "relay_video_xxx",
  "task_id": "relay_video_xxx",
  "status": "failed",
  "relay_state": "failed",
  "progress": 47,
  "error": {
    "code": "provider_task_failed",
    "message": "video task failed"
  }
}

10.4 临时轮询故障

json

{
  "id": "relay_video_xxx",
  "task_id": "relay_video_xxx",
  "status": "in_progress",
  "relay_state": "polling",
  "progress": 47,
  "poll_warning": {
    "code": "provider_poll_temporarily_unavailable"
  },
  "retry_after_ms": 12000
}

收到 poll_warning 时延后查询，不要重新创建任务。progress 可能为 null，表示当前没有可信进度。

11. 视频播放和下载

仅在任务为 completed 后调用：

http

GET /v1/videos/{task_id}/content
Authorization: Bearer <API_KEY>

bash

curl -L 'https://ai.lwaigc.cn/v1/videos/relay_video_xxx/content' \
  -H 'Authorization: Bearer <API_KEY>' \
  --output result.mp4

兼容带文件名路由：

http

GET /v1/videos/{task_id}/content/video.mp4

接口支持 GET、HEAD 和 Range。浏览器 <video> 标签不能直接携带 Bearer 时，业务后端应代理内容，或由前端使用带鉴权的 fetch 获取 Blob。不要把长期 API Key 放入公开网页。

12. 临时素材

12.1 上传本地文件

http

POST /v1/assets
Authorization: Bearer <API_KEY>
Idempotency-Key: asset_client_xxx
Content-Type: multipart/form-data

multipart 只要求一个字段：

text

file=<文件二进制>

bash

curl -X POST 'https://ai.lwaigc.cn/v1/assets' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Idempotency-Key: asset_client_xxx' \
  -F 'file=@reference.png'

新上传返回 HTTP 201，幂等重放返回 HTTP 200。响应中的 url 位于顶层：

json

{
  "id": "asset_xxx",
  "object": "asset",
  "mime_type": "image/png",
  "size": 123456,
  "duration_ms": null,
  "expires_at": "2026-07-18T12:00:00Z",
  "url": "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.png?expires=<EXPIRES>&signature=<SIGNATURE>"
}

图片的 duration_ms 为 null，音频和视频返回检测到的时长。

12.2 转存公网 HTTPS URL

http

POST /v1/assets/url
Authorization: Bearer <API_KEY>
Idempotency-Key: asset_url_xxx
Content-Type: application/json

json

{
  "url": "https://example.com/reference.png"
}

私网、回环、云元数据地址、file:// 和非 HTTPS 地址会被拒绝。

12.3 素材 URL 规则

将返回的完整 HTTPS url 原样写入目标模型的 URL 素材字段。
有效签名 URL 可以直接读取，不需要携带 Bearer。
不要修改文件名、后缀、expires 或 signature。
不要把真实签名 URL 写入公开日志或文档。
上传素材不会预扣视频生成费用；视频额度检查发生在创建视频任务时。

13. 常见错误

HTTP	典型错误	含义与处理
`400`	`invalid_request`、`unsupported_model`、`invalid_duration`、`invalid_resolution`	修正模型名或参数，不要原样无限重试
`401`	`invalid_token`	API Key 缺失、无效或过期
`403`	分组或模型访问权限不足	检查该 Key 的可见模型和分组权限
`404`	`not_found`	任务不存在或不属于当前账号
`409`	`idempotency_key_reused`	相同 key 被用于不同请求体
`413`	`file_too_large`	素材超过上传限制
`429`	频率、额度或素材空间限制	按错误提示处理
`503`	`model_not_found`	当前模型对该分组暂不可用；未返回 `task_id` 时任务未创建
`5xx`	中转站或生成服务临时异常	使用原幂等键和原请求体安全重试

明确的非 2xx JSON 错误且没有 task_id，不是已创建任务。只有已经返回 task_id，随后进入 submission_unknown，才表示后台提交结果待确认。

14. 推荐接入流程

使用当前 Key 请求 GET /v1/models。
从第 1 节选择完全一致的公开模型名。
本地素材先通过 /v1/assets 上传，保存顶层 url。
为每次业务生成一个稳定 client_task_id。
将相同值写入 Idempotency-Key 和请求体。
调用 POST /v1/videos，保存返回的 task_id。
按 retry_after_ms 查询 /v1/videos/{task_id}。
completed 后读取 /content；failed 后停止轮询。
创建响应丢失时，使用原幂等键重发完全相同的 POST。

15. 计费说明

接口文档不写死价格。实际价格取决于平台当前模型定价、账号分组、时长和分辨率配置。调用方应以中转站价格页或服务方提供的价格表为准。

视频模型统一接口文档 ​

1. 当前公开模型 ​

1.1 获取当前 Key 可用模型 ​

2. 接口总览 ​

3. 创建视频任务 ​

3.1 所有模型共有字段 ​

3.2 创建成功响应 ​

4. CY5 Seedance 2.0 ​

4.1 模型 ​

4.2 实际请求字段 ​

4.3 请求示例 ​

5. Firefly Seedance 2.0 ​

5.1 模型与固定分辨率 ​

5.2 实际请求字段 ​

5.3 请求示例 ​

6. Seedance 2.0 Fast / Pro 720 ​

6.1 模型能力 ​

6.2 实际请求字段 ​

6.3 Fast 示例 ​

6.4 Pro 示例 ​

7. SD2 431 Fast / Pro ​

7.1 模型能力 ​

7.2 实际请求字段 ​

7.3 请求示例 ​

8. Grok Imagine Video 1.5 Preview ​

8.1 模型名 ​

8.2 实际请求字段 ​

8.3 示例 ​

9. 幂等创建和断线重试 ​

10. 查询任务 ​

10.1 处理中 ​

10.2 完成 ​

10.3 失败终态 ​

10.4 临时轮询故障 ​

11. 视频播放和下载 ​

12. 临时素材 ​

12.1 上传本地文件 ​

12.2 转存公网 HTTPS URL ​

12.3 素材 URL 规则 ​

13. 常见错误 ​

14. 推荐接入流程 ​

15. 计费说明 ​

视频模型统一接口文档

1. 当前公开模型

1.1 获取当前 Key 可用模型

2. 接口总览

3. 创建视频任务

3.1 所有模型共有字段

3.2 创建成功响应

4. CY5 Seedance 2.0

4.1 模型

4.2 实际请求字段

4.3 请求示例

5. Firefly Seedance 2.0

5.1 模型与固定分辨率

5.2 实际请求字段

5.3 请求示例

6. Seedance 2.0 Fast / Pro 720

6.1 模型能力

6.2 实际请求字段

6.3 Fast 示例

6.4 Pro 示例

7. SD2 431 Fast / Pro

7.1 模型能力

7.2 实际请求字段

7.3 请求示例

8. Grok Imagine Video 1.5 Preview

8.1 模型名

8.2 实际请求字段

8.3 示例

9. 幂等创建和断线重试

10. 查询任务

10.1 处理中

10.2 完成

10.3 失败终态

10.4 临时轮询故障

11. 视频播放和下载

12. 临时素材

12.1 上传本地文件

12.2 转存公网 HTTPS URL

12.3 素材 URL 规则

13. 常见错误

14. 推荐接入流程

15. 计费说明