视频生成

搜索 /

视频模型以任务的形式响应，而不是一次性返回结果。POST /v1/videos 返回任务 ID 和 "status": "queued"，之后 GET /v1/videos/{task_id} 会持续报告进度，直到任务进入 completed 或 failed 状态。任务完成后，成品文件就是 metadata.url 下的签名 URL；该 URL 带有 Expires 参数，因此请下载文件，而不要只保存链接。失败的任务会在 error.code 和 error.message 中带回上游的错误码和错误信息，通常足以看出请求缺了哪个字段。POST /v1/video/generations 也会进入同一个处理程序，供已按该路径编写的客户端使用。

POST /v1/videos

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-i2v",
    "prompt": "the cat turns and walks toward the camera",
    "input_reference": "https://example.com/first-frame.jpg",
    "size": "1280*720",
    "duration": 5
  }'

# {"id":"task_9f2c...","task_id":"task_9f2c...","object":"video",
#  "model":"wan2.7-i2v","status":"queued","progress":0}

GET /v1/videos/{task_id}

curl https://api.chinaapi.ai/v1/videos/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"id":"task_9f2c...","object":"video","model":"wan2.7-i2v",
#  "status":"completed","progress":100,
#  "metadata":{"url":"https://.../output.mp4?Expires=..."}}

文生视频

wan2.7-t2v

只有 model 和 prompt 是必填字段。不传 size 和 duration 时，网关会以 1280*720、时长 5 秒提交。

图生视频

wan2.7-i2v

让一张静态图片动起来。input_reference 接收一个可公开访问的图片 URL，这张图片会作为首帧；请同时发送 size 和 duration。

参考生视频

wan2.7-r2v

根据参考素材生成视频。input_reference 接收一张参考图；要传多张，请改用 images，video_url 还可以添加一段参考视频——所有参考素材合计最多 5 个。不要同时发送 input_reference 和 images，因为网关只会保留 input_reference。

视频编辑

wan2.7-videoedit

按提示词编辑一段已有视频。video_url 接收源视频，必须是 2 到 10 秒的 MP4 或 MOV；size 决定输出尺寸。

30 秒视频

doubao-seedance-2-5-260628

参考图放在 images 中，input_reference 只接收一张；两者同时发送时都会保留。时长写在 seconds 或 duration 中，厂商参数放在 metadata 中，其中 resolution 取 480p 或 720p。

Seedance 2.0

doubao-seedance-2-0-260128

请求结构与 doubao-seedance-2-5-260628 相同，包括 metadata.content 的 role 规则。doubao-seedance-2-0-fast-260128 和 doubao-seedance-2-0-mini-260615 以质量换取速度和成本优势；另外，2.0 系列至少需要一个图片或视频参考，而 2.5 还接受仅有音频的输入。

Kling 3.0

kling-v3

首帧放在 image 中；该家族从不读取 input_reference。mode 默认为 std，duration 默认为 5 秒。其余参数都放在 metadata 中：image_tail 用于尾帧，sound 取 on 或 off（默认 off），此外还有 negative_prompt、cfg_scale 和 camera_control。

高性价比

kling-3.0-turbo

发送 prompt 即为文生视频；再加上 image，网关会组装上游所需的 contents 数组。尺寸相关参数位于 metadata.settings 下：resolution 取 720p 或 1080p，duration 为 3 到 15 秒，aspect_ratio 取 16:9、9:16 或 1:1。输出始终带有音频，且无法关闭。

多图参考

kling-v3-omni

一次以多张图片为参考进行生成。所有参数都放在 metadata 中，并且没有 resolution 字段——质量档位由 mode 决定。完整示例见下文。

原生音频

MiniMax-H3

接收网关自有的字段，并替你组装上游请求体：image 或 input_reference 作为首帧，images 作为参考图，video_url 作为参考视频。size 用于选择 768P 或 2K，duration 为 4 到 15 之间的整数。纯文本请求必须显式指定 metadata.ratio，且取值不能是 adaptive。

Hailuo

MiniMax-Hailuo-2.3

同类还有 MiniMax-Hailuo-2.3-Fast 和 MiniMax-Hailuo-02。这些模型只从顶层读取 prompt、duration 和 size；所有图片都要通过 metadata 传入，字段为 first_frame_image、last_frame_image 或 subject_reference。

480P 档位

happyhorse-1.1-t2v

同类还有 happyhorse-1.1-i2v 和 happyhorse-1.1-r2v。字段与 wan2.7 家族一致——prompt、input_reference、size、duration——而且这里的 480P 有定价，因此 wan2.7 会拒绝的 832*480 在这里可以使用。多个参考素材请放在 metadata.input.media 中，因为 images 字段触发的自动组装是 wan2.7-r2v 专有的。

提示 size 写成用星号连接的宽和高，例如 1280*720。不接受字母 x：传入 832x480 会返回 invalid size: 832x480, example: 1920*1080。duration 是以秒为单位的整数。对于 wan2.7-i2v、wan2.7-r2v 和 wan2.7-videoedit，网关会把 size 折算为分辨率档位，而上游只有两档，因此 720P 请发送 1280*720，1080P 请发送 1920*1080。832*480 这类 480P 尺寸在这三个模型上没有定价，要么被直接拒绝，要么先被接受、随后在上游以 InvalidParameter 失败；失败的任务会退款，但无论哪种情况，这一趟往返都白费了。wan2.7-t2v 则按所填的值原样使用。

提示 Kling 家族通过一张固定的对照表从 size 读取宽高比，表中的尺寸用字母 x 连接——1280x720、1920x1080、720x1280、1080x1920、1024x1024、512x512——表中没有的值一律当作 1:1，而且不会报错。因此，向 kling-v3 发送星号形式的 1280*720，得到的是一段正方形视频，而不是一条报错；画幅比例重要时，请直接设置 metadata.aspect_ratio。

提示 MiniMax-Hailuo-2.3、MiniMax-Hailuo-2.3-Fast 和 MiniMax-Hailuo-02 会静默丢弃顶层的 image、input_reference、images 和 video_url：请求会成功，但会按文生视频执行，也按文生视频计费。请改为把图片放进 metadata.first_frame_image，需要尾帧时加上 metadata.last_frame_image，主体参考则使用 metadata.subject_reference。MiniMax-H3 是这个家族中的例外，它确实会读取顶层字段。

kling-v3-omni · multi-image reference

curl https://api.chinaapi.ai/v1/video/generations \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "the character from the references walks through a neon-lit street",
    "metadata": {
      "image_list": [
        {"image_url": "https://example.com/character.jpg"},
        {"image_url": "https://example.com/outfit.jpg"},
        {"image_url": "https://example.com/scene.jpg"}
      ],
      "mode": "std",
      "duration": "5",
      "aspect_ratio": "16:9",
      "sound": "off"
    }
  }'

GET /v1/video/generations/{task_id}

curl https://api.chinaapi.ai/v1/video/generations/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"code":"success",
#  "data":{"task_id":"task_9f2c...","status":"SUCCESS",
#          "progress":"100%","fail_reason":"",
#          "result_url":"https://.../output.mp4"}}

提示参考图不带 type；该字段只用于标记 first_frame 或 end_frame，而只要没有首帧，就必须提供 aspect_ratio。mode 是质量档位——std、pro 或 4k——上游默认为 pro，按标价的 1.33 倍计费，4k 则按 5 倍计费；请显式发送 mode，让扣费与你的预期一致。duration 是 "3" 到 "15" 之间的字符串，sound 默认为 off。参考视频放在 video_list 中，并且必须设置 "refer_type": "feature"：编辑模式 base 按你提供的视频时长计费，提交前无法定价，因此会被拒绝。上游对参考图还有最小尺寸要求，图标大小的文件虽然能通过提交，任务随后却会以 Image pixel is invalid 失败；失败的任务会退款，但这一趟往返就白费了。

提示两条路径返回结果的结构不同。GET /v1/videos/{task_id} 按 OpenAI 视频格式返回，文件在 metadata.url，进度是一个数字。GET /v1/video/generations/{task_id} 返回 {"code": "success", "data": {…}}，文件在 data.result_url，data.status 是 SUCCESS 或 FAILURE 这样的大写单词，data.progress 是 "100%" 这样的字符串，失败时原因写在 data.fail_reason 中。请轮询你提交任务时所用的那条路径。

doubao-seedance-2-5-260628 · first frame

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "the subject slowly turns toward the camera",
    "images": ["https://example.com/first-frame.jpg"],
    "seconds": "5",
    "metadata": {"resolution": "480p"}
  }'

doubao-seedance-2-5-260628 · reference mode

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "keep the subject from the reference image",
    "seconds": "5",
    "metadata": {
      "resolution": "480p",
      "ratio": "16:9",
      "content": [
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/reference.jpg"},
          "role": "reference_image"
        }
      ]
    }
  }'

提示没有 role 的图片会被当作首帧，而不是参考图：输出沿用这张图片的宽高比；如果同时发送 ratio，会被拒绝并返回 InvalidParameter.TaskTypeConstraint；此时 seconds 设为 2 同样会被拒绝，设为 5 则可以。上游的 generate_audio 默认为 true，因此除非在 metadata 中把它设为 false，返回的文件都会带有音轨。给 metadata.content 的每一项都标上 role，即可使用完整的参考模式——最多 30 张图片、10 段视频和 10 段音频，支持纯音频输入，单次可生成 30 秒——该模式下也接受 ratio。