视频模型统一接口文档

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

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

1. 当前公开模型

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

请求中的 `model`	分辨率	时长	素材数量
`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 音频
`ft-seedance2.0-pro`	固定 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 音频
`sd2-933-720p-face`	固定 720p	4–15 秒	9 图 / 3 视频 / 3 音频
`gt-max-seedance2.0`	固定 720p	4–15 秒	9 图 / 3 视频 / 不支持音频
`mg-sd431-mini`	480p / 720p	4–15 秒	4 图 / 3 视频 / 1 音频
`mg-sd431-fast`	480p / 720p	4–15 秒	4 图 / 3 视频 / 1 音频
`mg-sd431-Pro`	480p / 720p	4–15 秒	4 图 / 3 视频 / 1 音频
`hn-sd官渠903-pro`	固定 720p	固定 15 秒	9 图 / 不支持视频 / 3 音频
`hn-sd903-pro`	固定 720p	固定 15 秒	9 图 / 不支持视频 / 3 音频
`hn-sd431-pro`	固定 720p	10 或 15 秒	4 图 / 3 视频 / 1 音频
`hn-sd431-fast`	固定 720p	10 或 15 秒	4 图 / 3 视频 / 1 音频
`hn-900fast`	固定 720p	固定 15 秒	9 图 / 不支持视频 / 不支持音频
`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 当前没有该模型的调用权限。

1.2 一个 Key 调用多个模型

同一个 API Key 可以调用 GET /v1/models 返回的所有模型，不需要为每个模型分别创建 Key。每次请求都以请求体中的 model 为准：调用哪个模型，就按该模型当前公布的价格和计费规则结算；不同模型的倍率、按次价格、时长价格和分辨率价格相互独立，不会因为共用同一个 Key 而串用。

例如，同一个 Key 可以先调用 mg-sd431-mini，再调用 hn-900fast，两次请求分别按照各自模型的规则计费。Key 只负责鉴权、额度和可用模型范围，不会固定所有请求使用同一个模型倍率。

实际可用模型始终以该 Key 调用 GET /v1/models 的结果为准；账户页面展示的模型价格为当前调用依据。

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}`	签名参数
读取签名素材（旧兼容）	`GET/HEAD`	`/v1/assets/{asset_id}/content`	签名参数
兼容音频引用上传	`POST`	`/v1/media-references`	Bearer
查询音频引用	`GET`	`/v1/media-references/{reference_id}`	Bearer
读取签名音频引用	`GET/HEAD`	`/v1/media-references/{reference_id}/content/{filename}`	签名参数
读取签名音频引用（旧兼容）	`GET/HEAD`	`/v1/media-references/{reference_id}/content`	签名参数

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

http

Authorization: Bearer <API_KEY>

2.1 媒体内容读取说明

临时素材、音频引用和已缓存的视频结果现在可能通过 HTTP 307 Temporary Redirect 跳转到对象存储读取文件字节。业务入口仍然是中转站 URL：

text

客户端 -> ai.lwaigc.cn 业务 URL -> 307 -> 对象存储签名 URL -> 200/206

调用方只保存中转站返回的 Relay URL，不要长期保存 307 Location 中的对象存储临时 URL。跨域跳转到对象存储后，不要继续携带 Authorization、Cookie 或 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–10 节对应模型发送，不要混用不同模型的专属参数。

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. GT Max Seedance 2.0

4.1 模型

`model`	分辨率	时长	素材数量
`gt-max-seedance2.0`	固定 `720p`	4–15 秒	9 图 / 3 视频 / 不支持音频

模型名区分大小写，必须按上表原样发送。该模型不支持音频参考。

4.2 实际请求字段

字段	类型	必填	规则
`model`	string	是	固定为 `gt-max-seedance2.0`
`prompt`	string	是	视频提示词
`seconds`	string 或 number	是	4–15 的整数
`resolution`	string	否	固定 `720p`，不要发送此字段
`aspect_ratio`	string	否	例如 `16:9`、`9:16`、`1:1`
`image_urls`	string[]	否	图片 URL，最多 9 张
`video_urls`	string[]	否	视频 URL，最多 3 条
`images_base64`	string[]	否	图片 Data URL 或 Base64
`client_task_id`	string	强烈建议	视频任务幂等标识

模型固定为 720p，不要发送 resolution。兼容单素材字段 image_url、video_url。不要发送 audio_url、audio_urls 或 audios_base64。兼容旧客户端使用 duration 表示秒数，但新客户端统一发送 seconds。

4.3 请求示例

json

{
  "model": "gt-max-seedance2.0",
  "client_task_id": "client_gt_max_xxx",
  "prompt": "保持人物外观一致，镜头缓慢向前推进",
  "seconds": 8,
  "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。中转站会在提交该模型上游前自动把 image_url/image_urls/images、video_url/video_urls/videos、audio_url/audio_urls/audios 合并为上游需要的 images、videos、audios 字段。

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. FT Seedance 2.0 Pro

6.1 模型能力

`model`	时长	素材数量
`ft-seedance2.0-pro`	固定 720p，4–15 秒整数，按秒计费	9 图 / 3 视频 / 3 音频

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

6.2 实际请求字段

字段	类型	必填	规则
`model`	string	是	固定为 `ft-seedance2.0-pro`
`prompt`	string	是	视频提示词
`seconds`	string 或 number	是	4–15 的整数
`aspect_ratio`	string	否	例如 `16:9`、`9:16`、`1:1`
`image_urls`	string[]	否	最多 9 张
`video_urls`	string[]	否	最多 3 条
`audio_urls`	string[]	否	最多 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 Pro 示例

json

{
  "model": "ft-seedance2.0-pro",
  "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 / 933 Face

7.1 模型能力

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

sd2-933-720p-face 使用 933 素材规格，支持真人脸素材，不需要额外发送真人模式参数。

7.2 实际请求字段

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

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

7.3 431 请求示例

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

7.4 933 Face 请求示例

json

{
  "model": "sd2-933-720p-face",
  "client_task_id": "client_sd2_933_face_xxx",
  "prompt": "保持人物面部和服装一致，镜头缓慢向前推进，动作自然",
  "seconds": 8,
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.png?expires=<EXPIRES>&signature=<SIGNATURE>"
  ]
}

8. MG SD431 Mini / Fast / Pro

8.1 模型与分辨率

`model`	可用分辨率
`mg-sd431-mini`	`480p`、`720p`
`mg-sd431-fast`	`480p`、`720p`
`mg-sd431-Pro`	`480p`、`720p`

必须显式发送 resolution，可传 480p 或 720p。该系列按照请求的真实分辨率计费；未配置的分辨率会返回 HTTP 400，错误码 unsupported_resolution。特别注意：720p+ 仅是后台价格配置的兼容写法，对客户端表示 720p，不表示支持 1080p。

8.2 实际请求字段

字段	类型	必填	规则
`model`	string	是	上表三个模型之一，`Pro` 的 P 必须大写
`prompt`	string	是	视频提示词
`seconds`	string 或 number	二选一	推荐字段；4–15 的整数。与 `duration` 只能传一个
`duration`	string 或 number	二选一	`seconds` 的兼容别名；4–15 的整数。新客户端优先使用 `seconds`
`resolution`	string	是	`480p` 或 `720p`
`aspect_ratio`	string	否	例如 `16:9`、`9:16`、`1:1`
`image_urls` / `images`	string[]	否	图片最多 4 张；必须是公网 HTTPS URL
`video_urls` / `videos`	string[]	否	视频最多 3 条
`audio_urls` / `audios`	string[]	否	音频最多 1 条；传音频时必须同时传至少 1 张图片
`client_task_id`	string	强烈建议	与 `Idempotency-Key` 使用同一稳定值

中转站继续兼容旧字段 image_url/image_urls、video_url/video_urls、audio_url/audio_urls。提交这三个 MG 模型上游前会自动合并、去重并转换为 images/videos/audios；其他视频模型不受该转换影响。

三个 MG SD431 模型均按其上游契约要求显式发送 aspect_ratio，仅支持 16:9、9:16、1:1；素材仅接受公网 HTTPS URL，不接受 Base64。提交上游时保留原模型名，seconds 或 duration 会统一转换为整数 duration。

json

{
  "model": "mg-sd431-mini",
  "client_task_id": "client_mg_xxx",
  "prompt": "镜头缓慢推进，人物自然转头，光线平稳变化",
  "seconds": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}

9. HN Seedance 2.0

9.1 模型能力

`model`	版本	分辨率	时长	素材数量
`hn-sd官渠903-pro`	官渠 903 Pro	固定 720p	固定 15 秒	9 图 / 不支持视频 / 3 音频
`hn-sd903-pro`	903 Pro	固定 720p	固定 15 秒	9 图 / 不支持视频 / 3 音频
`hn-sd431-pro`	431 Pro	固定 720p	10 或 15 秒	4 图 / 3 视频 / 1 音频
`hn-sd431-fast`	431 Fast	固定 720p	10 或 15 秒	4 图 / 3 视频 / 1 音频
`hn-900fast`	900 Fast	固定 720p	固定 15 秒	9 图 / 不支持视频 / 不支持音频

分辨率已经包含在模型能力中，不需要发送 resolution。hn-900fast 仅支持 900 素材规格，即最多 9 张图片、不支持视频和音频参考，并且画幅只能为 16:9 或 9:16。903 系列不支持视频参考；431 系列的图片、视频和音频数量上限分别为 4、3、1。

9.2 实际请求字段

字段	类型	必填	规则
`model`	string	是	固定为上表五个模型名之一
`prompt`	string	是	视频提示词
`seconds`	string 或 number	是	`hn-900fast` 和 903 系列只能为 `15`；431 系列只能为 `10` 或 `15`
`aspect_ratio`	string	否	`hn-900fast` 只能为 `16:9` 或 `9:16`；其他 HN 模型按其渠道能力填写
`image_urls` / `images_base64`	string[]	否	`hn-900fast` 和 903 最多 9 张；431 最多 4 张
`video_urls`	string[]	否	仅 431 系列支持，最多 3 条
`audio_urls` / `audios_base64`	string[]	否	`hn-900fast` 不支持；903 最多 3 条；431 最多 1 条
`client_task_id`	string	强烈建议	与 `Idempotency-Key` 使用同一稳定值

兼容单素材字段 image_url、video_url、audio_url，但不得向不支持对应素材类型的模型发送该字段。兼容旧客户端使用 duration 表示秒数；新客户端统一发送 seconds。

9.3 431 请求示例

json

{
  "model": "hn-sd431-pro",
  "client_task_id": "client_hn_431_xxx",
  "prompt": "保持人物外观一致，镜头缓慢向前推进",
  "seconds": 10,
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.png?expires=<EXPIRES>&signature=<SIGNATURE>"
  ]
}

HN 系列任务完成后，查询响应会额外返回顶层 HTTPS video_url。客户端应保存并直接读取该地址；重复查询同一任务仍会返回结果地址。

9.4 900 Fast 请求示例

json

{
  "model": "hn-900fast",
  "client_task_id": "client_hn_900fast_xxx",
  "prompt": "镜头平缓向前推进，保持主体外观和背景结构稳定",
  "seconds": 15,
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.png?expires=<EXPIRES>&signature=<SIGNATURE>"
  ]
}

10. Grok Imagine Video 1.5 Preview

10.1 模型名

text

grok-imagine-video-1.5-preview

10.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	强烈建议	视频任务幂等标识

10.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"
}

11. 幂等创建和断线重试

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

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。

12. 查询任务

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>'

12.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
}

12.2 完成

json

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

12.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"
  }
}

12.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，表示当前没有可信进度。

13. 视频播放和下载

仅在任务为 completed 后调用：

http

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

兼容带文件名路由：

http

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

接口支持 GET、HEAD 和 Range。首次请求必须访问中转站 /content 地址并携带 Bearer；若返回 307，后续跳转到对象存储地址时不要继续携带 Bearer、Cookie 或 API Key。

安全下载流程：

text

1. GET/HEAD /v1/videos/{task_id}/content，携带 Bearer。
2. 如果返回 200/206，直接读取响应体。
3. 如果返回 307，读取 Location。
4. 对 Location 发起同方法请求；Range 请求必须保留 Range 头。
5. 对对象存储 Location 的请求不携带 Bearer、Cookie 或 API Key。
6. 不要把 Location 完整写入日志或长期保存。

Range 示例：

http

GET /v1/videos/{task_id}/content
Authorization: Bearer <API_KEY>
Range: bytes=0-1023

预期响应：

text

完整 GET：200 或 307 后 200
合法 Range：206
越界 Range：416，并返回 Content-Range: bytes */总大小
HEAD：200 或 307 后 200

下载器应以最终响应的 Content-Type、Content-Length、Content-Range、ETag 为准。请求了非零 Range 但最终返回 200 时，表示服务器忽略 Range 或对象已变化，客户端应丢弃本地断点后从头覆盖下载，不能追加写入。

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

14. 临时素材

14.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，音频和视频返回检测到的时长。

14.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 地址会被拒绝。

成功响应与 POST /v1/assets 相同，返回顶层 url。导入成功后，请使用返回的中转站签名 URL，不要继续把原始公网 URL传给视频模型。

14.3 素材 URL 规则

将返回的完整 HTTPS url 原样写入目标模型的 URL 素材字段。
有效签名 URL 可以直接读取，不需要携带 Bearer。
签名 URL 读取时可能返回 307 跳转到对象存储；跳转后的请求不要携带 Bearer、Cookie 或 API Key。
HEAD、完整 GET 和 Range GET 都应被客户端支持。
不要修改文件名、后缀、expires 或 signature。
不要把真实签名 URL 写入公开日志或文档。
上传素材不会预扣视频生成费用；视频额度检查发生在创建视频任务时。

新上传素材默认返回带真实后缀的 V2 URL，后缀来自服务端文件内容检测。例如用户上传名为 reference.jpg、实际内容为 PNG 的文件，返回 URL 会以 .png 结尾。旧的无后缀签名 URL继续兼容。

支持的临时素材格式：

类型	支持格式	URL 后缀
图片	JPEG、PNG、WEBP、GIF	`.jpg`、`.png`、`.webp`、`.gif`
音频	MP3、WAV、M4A、AAC、OGG	`.mp3`、`.wav`、`.m4a`、`.aac`、`.ogg`
视频	MP4、WEBM、MOV、MKV	`.mp4`、`.webm`、`.mov`、`.mkv`

14.4 兼容音频引用

音频引用接口保留，用于需要 reference_id 的旧客户端或模型链路：

http

POST /v1/media-references
Authorization: Bearer <API_KEY>
Idempotency-Key: audio_ref_xxx
Content-Type: multipart/form-data

multipart 字段：

字段	必填	说明
`file`	是	单个音频文件
`purpose`	否	`provider_audio_reference` 或 `sora_audio_reference`
`project_id`	否	最长 128 字符

成功响应：

json

{
  "reference_id": "mref_xxx",
  "url": "https://ai.lwaigc.cn/v1/media-references/mref_xxx/content/mref_xxx.mp3?expires=<EXPIRES>&signature=<SIGNATURE>",
  "expires_at": "2026-07-18T12:00:00Z",
  "mime_type": "audio/mpeg",
  "size": 123456,
  "duration_ms": 8000,
  "purpose": "provider_audio_reference",
  "project_id": ""
}

未过期的音频引用可以查询当前元数据和签名 URL：

http

GET /v1/media-references/{reference_id}
Authorization: Bearer <API_KEY>

音频引用内容 URL 读取规则与 /v1/assets 相同：无需 Bearer，可能返回 307 到对象存储。

14.5 图片接口返回 URL 兼容

非流式图片接口仍使用原接口地址和请求字段，例如：

text

POST /v1/images/generations
POST /v1/images/edits

当上游返回 b64_json 且中转站成功持久化图片时，响应可能被改写为 data[].url：

json

{
  "created": 1780000000,
  "data": [
    {
      "url": "https://ai.lwaigc.cn/v1/assets/asset_xxx/content/asset_xxx.png?expires=<EXPIRES>&signature=<SIGNATURE>"
    }
  ]
}

因此图片客户端必须同时兼容 data[].url 和 data[].b64_json，不能只读取 b64_json。上游本来返回 URL 时，中转站保持 URL 形态，不保证所有图片结果都经过对象存储。

15. 常见错误

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 被用于不同请求体
`409`	`idempotency_request_in_progress`、`submission_unknown`	原幂等请求仍在处理或提交状态待确认，继续查询或稍后重试同一请求
`413`	`file_too_large`	素材超过上传限制
`429`	`storage_quota_exceeded`	临时素材存储已满，复用已有素材或等待过期清理后重试
`429`	`upload_rate_limited`	素材上传请求过于频繁，按 `Retry-After` 稍后重试
`429`	额度或模型频率限制	按错误提示处理；不要仅凭 429 判断为上传频率限制
`307`	`Temporary Redirect`	媒体内容跳转到对象存储，按原方法继续请求且不要转发 Bearer
`416`	`Range Not Satisfiable`	Range 越界，按 `Content-Range: bytes */总大小` 修正断点
`503`	`model_not_found`	当前模型对该分组暂不可用；未返回 `task_id` 时任务未创建
`5xx`	中转站或生成服务临时异常	使用原幂等键和原请求体安全重试

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

16. 推荐接入流程

使用当前 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；如果返回 307，跳转请求不携带 Bearer。
创建响应丢失时，使用原幂等键重发完全相同的 POST。
failed 后停止轮询，不要用同一任务 ID 继续下载。

媒体下载失败只重试下载请求，不要重新创建视频任务；否则可能导致重复生成和重复计费。

17. 计费说明

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

视频模型统一接口文档 ​

1. 当前公开模型 ​

1.1 获取当前 Key 可用模型 ​

1.2 一个 Key 调用多个模型 ​

2. 接口总览 ​

2.1 媒体内容读取说明 ​

3. 创建视频任务 ​

3.1 所有模型共有字段 ​

3.2 创建成功响应 ​

4. GT Max Seedance 2.0 ​

4.1 模型 ​

4.2 实际请求字段 ​

4.3 请求示例 ​

5. Firefly Seedance 2.0 ​

5.1 模型与固定分辨率 ​

5.2 实际请求字段 ​

5.3 请求示例 ​

6. FT Seedance 2.0 Pro ​

6.1 模型能力 ​

6.2 实际请求字段 ​

6.3 Pro 示例 ​

7. SD2 431 / 933 Face ​

7.1 模型能力 ​

7.2 实际请求字段 ​

7.3 431 请求示例 ​

7.4 933 Face 请求示例 ​

8. MG SD431 Mini / Fast / Pro ​

8.1 模型与分辨率 ​

8.2 实际请求字段 ​

9. HN Seedance 2.0 ​

9.1 模型能力 ​

9.2 实际请求字段 ​

9.3 431 请求示例 ​

9.4 900 Fast 请求示例 ​

10. Grok Imagine Video 1.5 Preview ​

10.1 模型名 ​

10.2 实际请求字段 ​

10.3 示例 ​

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

12. 查询任务 ​

12.1 处理中 ​

12.2 完成 ​

12.3 失败终态 ​

12.4 临时轮询故障 ​

13. 视频播放和下载 ​

14. 临时素材 ​

14.1 上传本地文件 ​

14.2 转存公网 HTTPS URL ​

14.3 素材 URL 规则 ​

14.4 兼容音频引用 ​

14.5 图片接口返回 URL 兼容 ​

15. 常见错误 ​

16. 推荐接入流程 ​

17. 计费说明 ​

视频模型统一接口文档

1. 当前公开模型

1.1 获取当前 Key 可用模型

1.2 一个 Key 调用多个模型

2. 接口总览

2.1 媒体内容读取说明

3. 创建视频任务

3.1 所有模型共有字段

3.2 创建成功响应

4. GT Max Seedance 2.0

4.1 模型

4.2 实际请求字段

4.3 请求示例

5. Firefly Seedance 2.0

5.1 模型与固定分辨率

5.2 实际请求字段

5.3 请求示例

6. FT Seedance 2.0 Pro

6.1 模型能力

6.2 实际请求字段

6.3 Pro 示例

7. SD2 431 / 933 Face

7.1 模型能力

7.2 实际请求字段

7.3 431 请求示例

7.4 933 Face 请求示例

8. MG SD431 Mini / Fast / Pro

8.1 模型与分辨率

8.2 实际请求字段

9. HN Seedance 2.0

9.1 模型能力

9.2 实际请求字段

9.3 431 请求示例

9.4 900 Fast 请求示例

10. Grok Imagine Video 1.5 Preview

10.1 模型名

10.2 实际请求字段

10.3 示例

11. 幂等创建和断线重试

12. 查询任务

12.1 处理中

12.2 完成

12.3 失败终态

12.4 临时轮询故障

13. 视频播放和下载

14. 临时素材

14.1 上传本地文件

14.2 转存公网 HTTPS URL

14.3 素材 URL 规则

14.4 兼容音频引用

14.5 图片接口返回 URL 兼容

15. 常见错误

16. 推荐接入流程

17. 计费说明