New API · Video Generation

让视频生成
像调用一个接口一样简单

从提交任务、查询进度到下载结果，一份面向 API 用户的完整接入手册。覆盖文生视频、图生视频、多参考素材与真人视频处理。

5 类视频模型异步任务 URL / Base64 分辨率独立计费真人参考视频

BASE URL https://api.catertx.com

11可计费模型 ID

3核心 API 端点

1单次任务生成数

URL统一结果格式

提交生成任务POST /v1/video/generations

保存 task_id异步任务唯一凭证

查询并下载等待 completed 后获取 URL

没有找到匹配内容
请尝试“Seedance”“Base64”“真人”“下载”或具体错误码。

章节 01

1. 接口信息#

API 基础地址：

https://api.catertx.com

所有请求都需要在 Header 中携带 API Key：

Authorization: Bearer sk-你的API密钥

请勿把 API Key 写入网页前端、公开仓库或分享给其他人。

接口列表#

功能	方法	地址
提交视频生成任务	POST	`/v1/video/generations`
查询任务状态	GET	`/v1/video/generations/{task_id}`
查询可用模型	GET	`/v1/models`

视频生成是异步任务：提交后先取得 task_id，再使用查询接口等待任务完成。

章节 02

2. 查询可用模型#

curl 'https://api.catertx.com/v1/models' \
  -H 'Authorization: Bearer sk-你的API密钥'

请求中的 model 必须与模型列表返回的 id 完全一致。如果平台显示的是简化名称或别名，请以 /v1/models 返回结果为准。

目前支持以下视频模型：

doubao-seedance-2-0-480p
doubao-seedance-2-0-720p
doubao-seedance-2-0-1080p
doubao-seedance-2-0-4k
doubao-seedance-2-5-480p
doubao-seedance-2-5-720p
MiniMax-H3-768p
MiniMax-H3-2k
grok-imagine-video-480p
grok-imagine-video-720p
gemini-omni-flash-preview

模型名末尾就是计费分辨率。例如 doubao-seedance-2-0-480p 固定生成 480p，用户不需要再传 resolution。不同模型名可以由平台设置不同价格。

章节 03

3. 通用提交方法#

curl -X POST 'https://api.catertx.com/v1/video/generations' \
  -H 'Authorization: Bearer sk-你的API密钥' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-720p",
    "prompt": "电影级镜头，一只白猫走过雨后的霓虹街道",
    "duration": 8,
    "ratio": "16:9",
    "n": 1,
    "response_format": "url"
  }'

成功返回：

{
  "id": "task_0123456789abcdef",
  "task_id": "task_0123456789abcdef",
  "status": "queued",
  "progress": 0
}

请保存 task_id，它是后续查询任务的唯一凭证。

章节 04

4. 通用请求字段#

字段	类型	是否必填	说明
`model`	string	是	带分辨率后缀的计费模型 ID
`prompt`	string	视模型而定	视频内容描述
`image`	string	否	单张首帧图片 URL 或 Base64 Data URL
`last_frame`	string	否	尾帧图片 URL 或 Base64 Data URL
`images`	array	否	多张图片
`videos`	array	否	参考视频或待编辑视频
`audios`	array	否	参考音频
`duration`	integer	视模型而定	输出时长，单位为秒
`resolution`	string	否	不需要传；输出分辨率由模型名后缀锁定
`ratio`	string	否	输出宽高比
`width`	integer	否	使用带分辨率后缀的模型时不要传
`height`	integer	否	使用带分辨率后缀的模型时不要传
`seed`	integer	否	随机种子，目前仅 Seedance 支持
`n`	integer	否	当前只能填写 `1`
`response_format`	string	否	当前只能填写 `url`
`user`	string	否	调用方自己的用户标识
`metadata`	object	否	模型专用扩展参数

通用限制：

一次请求只生成一个视频，n 只能为 1。
返回格式目前只支持 url。
当前所有视频模型均不支持设置输出 fps，请不要传 fps。
分辨率由 model 末尾的 -480p、-720p、-768p、-1080p、-2k 或 -4k 自动确定。
请不要再传 resolution、width 或 height。如果传入的分辨率与模型名冲突，接口会返回 400，不能使用低价模型生成高价分辨率。
ratio 仍然由用户按模型支持范围填写。
不需要提供回调地址。平台会在后台查询任务状态，用户只需使用本文的 GET 接口查询。

常用 metadata 字段：

字段	类型	适用模型	说明
`generate_audio`	boolean	Seedance	是否生成同步音频
`camera_fixed`	boolean	Seedance	是否固定镜头
`watermark`	boolean	Seedance	是否添加水印
`execution_expires_after`	integer	Seedance	任务超时时间，范围 3600～259200 秒
`video_contain_person`	boolean	Seedance 2.0/2.5	参考视频包含真人时设为 `true`；不要写成普通字符串
`aigc_watermark`	boolean	MiniMax-H3	是否添加 AIGC 水印
`task`	string	Gemini Omni	指定文生、图生、参考生或视频编辑模式

章节 05

5. 素材输入格式#

公网 URL#

{
  "image": "https://cdn.example.com/first.png",
  "last_frame": "https://cdn.example.com/last.png",
  "videos": ["https://cdn.example.com/reference.mp4"],
  "audios": ["https://cdn.example.com/reference.mp3"]
}

URL 必须能从公网直接访问。不能使用本地文件路径、127.0.0.1 或局域网地址。

Base64 Data URL#

{
  "image": "data:image/png;base64,iVBORw0KGgoAAA..."
}

纯 Base64 对象#

纯 Base64 不带 data:image/...;base64, 前缀，因此必须同时提供 mime_type：

{
  "images": [
    {
      "data": "iVBORw0KGgoAAA...",
      "mime_type": "image/png",
      "role": "first_frame"
    }
  ]
}

Base64 多参考图完整示例#

以下 images 数组格式适用于 Seedance 2.0、Seedance 2.5 和 gemini-omni-flash-preview。下面是 Seedance 2.5 的完整请求；Gemini 不接受 duration，请使用第 11 节的 Gemini 专用示例。MiniMax-H3 与 grok-imagine-video 不支持 Base64 图片。

curl -X POST 'https://api.catertx.com/v1/video/generations' \
  -H 'Authorization: Bearer sk-你的API密钥' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-720p",
    "prompt": "保持人物、服装和场景一致，生成角色走进咖啡店的视频",
    "duration": 12,
    "ratio": "16:9",
    "images": [
      {
        "data": "人物图片的纯Base64数据",
        "mime_type": "image/png",
        "role": "reference_image"
      },
      {
        "data": "服装图片的纯Base64数据",
        "mime_type": "image/jpeg",
        "role": "reference_image"
      },
      {
        "data": "场景图片的纯Base64数据",
        "mime_type": "image/png",
        "role": "reference_image"
      }
    ],
    "n": 1,
    "response_format": "url"
  }'

data 只填写 Base64 正文，不要包含 data:image/...;base64, 前缀；使用这种对象格式时必须填写正确的 mime_type。如果希望直接携带前缀，也可以将数组元素写成字符串形式的完整 Data URL。

真人参考图#

Seedance 2.0 和 Seedance 2.5 支持使用真人参考图片。平台会自动把输入图片转换为生成任务可使用的托管素材，用户仍然按照普通 image 或 images 格式提交：

curl -X POST 'https://api.catertx.com/v1/video/generations' \
  -H 'Authorization: Bearer sk-你的API密钥' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-0-720p",
    "prompt": "参考图中人物和服装，生成角色走进咖啡店的视频",
    "duration": 5,
    "ratio": "16:9",
    "images": [
      {"url": "https://cdn.example.com/person.jpeg", "role": "reference_image"},
      {"url": "https://cdn.example.com/clothes.jpeg", "role": "reference_image"}
    ],
    "n": 1,
    "response_format": "url"
  }'

指定图片作用#

{
  "images": [
    {"url": "https://cdn.example.com/first.png", "role": "first_frame"},
    {"url": "https://cdn.example.com/last.png", "role": "last_frame"},
    {"url": "https://cdn.example.com/reference.png", "role": "reference_image"}
  ]
}

role	作用
`first_frame`	首帧
`last_frame`	尾帧
`reference_image`	参考图片，不强制成为首帧或尾帧
`reference_video`	参考视频
`reference_audio`	参考音频

多图请求建议明确填写 role，避免模型把第一张图片误认为首帧。

通用单文件大小限制：

类型	最大大小
图片	30 MiB
音频	50 MiB
视频	500 MiB

具体模型可能还有更严格的格式、时长和大小限制。

章节 06

6. 模型能力对照#

模型系列	对外计费模型后缀	支持的输入	时长	Seed
Seedance 2.0	`-480p`、`-720p`、`-1080p`、`-4k`	文本、首尾帧、真人/普通参考图、参考视频、参考音频	4～15 秒	支持
Seedance 2.5	`-480p`、`-720p`	文本、首尾帧、真人/普通参考图、参考视频、参考音频	4～30 秒	支持
MiniMax-H3	`-768p`、`-2k`	文本、首尾帧或多模态参考	4～15 秒	不支持
Grok Imagine Video	`-480p`、`-720p`	单图或多图参考	1～15 秒	不支持
Gemini Omni	无后缀，固定 720p	文生、图生、多图参考、视频编辑	模型决定	不支持

章节 07

7. Doubao Seedance 2.0#

可用模型 ID：

doubao-seedance-2-0-480p
doubao-seedance-2-0-720p
doubao-seedance-2-0-1080p
doubao-seedance-2-0-4k

支持文生视频、首尾帧、多张参考图片、参考视频和参考音频。图片可使用公网 URL 或 Base64；参考视频和参考音频必须使用公网 URL。

平台会自动处理图片素材转换，API 用户不需要也不应传入内部转换参数。

可用扩展参数：

字段	类型	说明
`metadata.generate_audio`	boolean	是否生成同步音频
`metadata.camera_fixed`	boolean	是否固定镜头
`metadata.watermark`	boolean	是否添加水印
`metadata.execution_expires_after`	integer	任务超时时间，范围 3600～259200 秒
`metadata.video_contain_person`	boolean	参考视频包含真人时设为 `true`；仅用于网关识别，不会发送给上游生成接口

多模态参考生成#

{
  "model": "doubao-seedance-2-0-4k",
  "prompt": "保持角色外观一致，在森林中向镜头跑来",
  "duration": 15,
  "ratio": "16:9",
  "seed": 123456,
  "images": [
    {"url": "https://cdn.example.com/first.png", "role": "first_frame"},
    {"url": "https://cdn.example.com/last.png", "role": "last_frame"},
    {"url": "https://cdn.example.com/character.png", "role": "reference_image"}
  ],
  "videos": ["https://cdn.example.com/motion.mp4"],
  "audios": ["https://cdn.example.com/music.mp3"],
  "n": 1,
  "response_format": "url",
  "metadata": {
    "generate_audio": true,
    "camera_fixed": false,
    "watermark": false
  }
}

参考视频包含真人#

只有参考视频确实包含真人时才设置 metadata.video_contain_person=true

curl -X POST 'https://api.catertx.com/v1/video/generations' \
  -H 'Authorization: Bearer sk-你的API密钥' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "doubao-seedance-2-0-1080p",
  "prompt": "@图片1 参考@视频1 进行舞台表演，音频使用@音频1",
  "duration": 15,
  "ratio": "16:9",
  "images": [
    {"url": "https://cdn.example.com/person.png", "role": "reference_image"}
  ],
  "videos": ["https://cdn.example.com/person-dance.mp4"],
  "audios": ["https://cdn.example.com/music.mp3"],
  "n": 1,
  "response_format": "url",
  "metadata": {
    "video_contain_person": true,
    "generate_audio": true,
    "watermark": false
  }
}'

注意：

该开关目前仅适用于 Seedance 2.0 和 Seedance 2.5 的参考视频。
参考视频必须是官方服务能够访问的公网 HTTP/HTTPS URL，Base64 视频不能用于真人素材转换。
不包含真人时不要设置，系统会直接提交原始参考视频，速度更快。
任务查询中的 preparing_reference_video、processing_reference_video、submitting 分别表示正在准备素材、正在处理素材和正在提交生成任务。
该参数只由平台入口识别，不会出现在发送给模型服务的生成参数中。
素材处理是异步步骤。POST 接口返回 queued 只代表任务已接收，最终是否成功仍要通过 GET 接口查询。

章节 08

8. Doubao Seedance 2.5#

可用模型 ID：

doubao-seedance-2-5-480p
doubao-seedance-2-5-720p

能力与 Seedance 2.0 相近，最大时长增加到 30 秒。根据最新接口定义，Seedance 2.5 的全部生成模式现在只支持 480p 和 720p，不再支持 1080p 或 4k。平台不会自动降级分辨率，以免计费模型与实际输出不一致。

和 Seedance 2.0 一样，平台会自动处理图片素材转换，API 用户不要自行传入内部转换参数。

可用扩展参数与 Seedance 2.0 相同：metadata.generate_audio、metadata.camera_fixed、metadata.watermark、metadata.execution_expires_after、metadata.video_contain_person。

720p 文生视频#

{
  "model": "doubao-seedance-2-5-720p",
  "prompt": "航拍雪山日出，云海缓慢流动，电影级光影",
  "duration": 15,
  "ratio": "16:9",
  "seed": 9527,
  "n": 1,
  "response_format": "url",
  "metadata": {
    "generate_audio": false,
    "watermark": false
  }
}

多张参考图#

{
  "model": "doubao-seedance-2-5-720p",
  "prompt": "参考人物、服装和场景，生成角色走进咖啡店的视频",
  "duration": 12,
  "ratio": "16:9",
  "images": [
    {"url": "https://cdn.example.com/person.png", "role": "reference_image"},
    {"url": "https://cdn.example.com/clothes.png", "role": "reference_image"},
    {"url": "https://cdn.example.com/cafe.png", "role": "reference_image"}
  ],
  "n": 1,
  "response_format": "url"
}

章节 09

9. MiniMax-H3#

可用模型 ID：

MiniMax-H3-768p
MiniMax-H3-2k

注意事项：

必须提供非空 prompt。
图片、视频和音频只能使用公网 URL，不能使用 Base64。
“首尾帧模式”和“多模态参考模式”不能混用。
最多一个首帧和一个尾帧，或者最多 9 张参考图、3 个参考视频、3 个参考音频。
参考音频不能单独使用，必须同时提供参考图片或参考视频。
不支持 seed。
纯文生视频必须指定具体比例，不能使用 adaptive。

可用扩展参数：metadata.aigc_watermark。

文生视频#

{
  "model": "MiniMax-H3-2k",
  "prompt": "一艘帆船穿过清晨薄雾，镜头缓慢拉远",
  "duration": 10,
  "ratio": "16:9",
  "n": 1,
  "response_format": "url",
  "metadata": {
    "aigc_watermark": false
  }
}

首尾帧模式#

{
  "model": "MiniMax-H3-768p",
  "prompt": "从白天自然过渡到夜晚",
  "duration": 10,
  "ratio": "adaptive",
  "images": [
    {"url": "https://cdn.example.com/day.png", "role": "first_frame"},
    {"url": "https://cdn.example.com/night.png", "role": "last_frame"}
  ],
  "n": 1,
  "response_format": "url"
}

多模态参考模式#

{
  "model": "MiniMax-H3-2k",
  "prompt": "参考人物和动作视频，生成舞台表演",
  "duration": 12,
  "ratio": "16:9",
  "images": [
    {"url": "https://cdn.example.com/person.png", "role": "reference_image"}
  ],
  "videos": ["https://cdn.example.com/dance.mp4"],
  "audios": ["https://cdn.example.com/music.mp3"],
  "n": 1,
  "response_format": "url",
  "metadata": {
    "aigc_watermark": false
  }
}

章节 10

10. Grok Imagine Video#

可用模型 ID：

grok-imagine-video-480p
grok-imagine-video-720p

注意事项：

必须同时提供 prompt 和至少一张图片。
图片只能使用公网 URL，不支持 Base64。
不支持纯文生视频、参考视频、参考音频和 seed。
分辨率：480p、720p。
比例：1:1、16:9、9:16、4:3、3:4、3:2、2:3。
时长：1～15 秒，默认 8 秒。

单图生视频#

{
  "model": "grok-imagine-video-720p",
  "prompt": "让图片中的机器人转身并向远处走去",
  "image": "https://cdn.example.com/robot.png",
  "duration": 8,
  "ratio": "16:9",
  "n": 1,
  "response_format": "url"
}

多图参考生成#

{
  "model": "grok-imagine-video-720p",
  "prompt": "结合角色和场景参考图生成短片",
  "duration": 10,
  "ratio": "3:2",
  "images": [
    {"url": "https://cdn.example.com/character.png", "role": "reference_image"},
    {"url": "https://cdn.example.com/scene.png", "role": "reference_image"}
  ],
  "n": 1,
  "response_format": "url"
}

生成成功返回（已脱敏）#

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_example_grok",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://api.catertx.com/v1/videos/task_example_grok/content",
    "data": {
      "task_id": "video_example_grok",
      "status": "completed",
      "format": "mp4",
      "url": "https://files.example.com/generated/grok-video.mp4",
      "metadata": {
        "model": "grok-imagine-video-720p",
        "duration": 8,
        "elapsed_seconds": 119,
        "resolution": "720p",
        "ratio": "16:9",
        "progress_stage": "completed",
        "progress_text": "视频生成完成"
      }
    }
  }
}

Grok 会在 data.data.url 中返回可直接下载的原始 MP4 地址。示例中的任务编号、文件域名和视频路径均为脱敏占位值。

章节 11

11. Gemini Omni Flash Preview#

模型 ID：

gemini-omni-flash-preview

支持四种任务：

metadata.task	用途
`text_to_video`	文生视频
`image_to_video`	单图生视频
`reference_to_video`	多图参考生视频
`edit`	视频编辑

如果不传 metadata.task，系统会根据输入素材自动选择任务类型。

注意事项：

不要传 duration，输出时长由模型决定。
不要传 seed。
输出固定为 720p，可省略 resolution 或填写 720p。
ratio 只能是 16:9 或 9:16。
最多 10 张图片、3 个视频。
不支持音频输入。
图片和视频都支持公网 URL、Data URL 或纯 Base64 对象。
上游完成结果是 Base64 视频数据，不提供原始公网下载 URL。平台会自动将 Base64 解码为 MP4，用户仍然按照本手册的 URL 下载方式获取视频，不需要自己处理 Base64。

文生视频#

{
  "model": "gemini-omni-flash-preview",
  "prompt": "云层上方的未来城市，飞行器从镜头前经过",
  "ratio": "16:9",
  "n": 1,
  "response_format": "url"
}

单图生视频#

{
  "model": "gemini-omni-flash-preview",
  "prompt": "让画面中的海浪缓慢运动",
  "image": "data:image/png;base64,iVBORw0KGgoAAA...",
  "ratio": "16:9",
  "n": 1,
  "response_format": "url",
  "metadata": {
    "task": "image_to_video"
  }
}

多图参考生视频#

{
  "model": "gemini-omni-flash-preview",
  "prompt": "保持角色和产品外观一致，生成一段广告视频",
  "ratio": "9:16",
  "images": [
    {
      "data": "人物图片的纯Base64数据",
      "mime_type": "image/png",
      "role": "reference_image"
    },
    {
      "data": "产品图片的纯Base64数据",
      "mime_type": "image/jpeg",
      "role": "reference_image"
    }
  ],
  "n": 1,
  "response_format": "url",
  "metadata": {
    "task": "reference_to_video"
  }
}

视频编辑#

{
  "model": "gemini-omni-flash-preview",
  "prompt": "把视频改成夜景，并增加柔和的霓虹灯光",
  "ratio": "16:9",
  "videos": [
    {
      "url": "https://cdn.example.com/source.mp4",
      "role": "reference_video"
    }
  ],
  "n": 1,
  "response_format": "url",
  "metadata": {
    "task": "edit"
  }
}

章节 12

12. 查询任务状态#

将提交接口返回的 New API task_id 放入地址。该编号通常以 task_ 开头：

curl 'https://api.catertx.com/v1/video/generations/task_0123456789abcdef' \
  -H 'Authorization: Bearer sk-你的API密钥'

New API 的主要任务状态位于最外层 data.status：

`data.status`	说明
`NOT_START`	已提交或正在排队
`IN_PROGRESS`	正在生成
`SUCCESS`	已完成
`FAILURE`	生成失败

内层 data.data.status 使用 queued、in_progress、completed、failed，表达的是同一任务状态。

data.data.metadata.progress_stage 可能出现：

`progress_stage`	说明
`submitted` / `queued`	已接收，正在等待处理
`preparing_reference_video`	正在准备真人参考视频素材
`processing_reference_video`	素材已经提交，正在等待处理完成
`submitting`	素材可用，正在提交正式视频生成任务
`generating`	正在生成视频
`completed`	视频生成完成
`failed`	任务失败

生成中的返回示例：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_0123456789abcdef",
    "status": "IN_PROGRESS",
    "progress": "30%",
    "data": {
      "task_id": "video_0123456789abcdef",
      "status": "in_progress",
      "metadata": {
        "model": "doubao-seedance-2-5-720p",
        "progress_stage": "generating",
        "progress_text": "正在生成视频",
        "elapsed_seconds": 63,
        "requested_duration_seconds": 15,
        "resolution": "720p",
        "ratio": "16:9"
      }
    }
  }
}

elapsed_seconds 表示已经等待的时间，不代表剩余时间。New API 显示的 0%、30%、100% 是任务阶段提示，不是模型返回的精确生成百分比。

生成成功示例（已脱敏）#

以下示例根据实际生成成功结果整理，已经删除或替换用户编号、渠道编号、计费额度、内部模型名、真实任务编号、对象存储域名、AccessKey 和临时下载签名。实际响应可能包含更多平台记账字段，调用程序不应依赖这些附加字段。

Seedance、MiniMax-H3 和 Grok 的成功返回结构相同，都会在 data.data.url 中提供原始视频下载地址：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_0123456789abcdef",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://api.catertx.com/v1/videos/task_0123456789abcdef/content",
    "data": {
      "task_id": "video_0123456789abcdef",
      "status": "completed",
      "url": "https://上游文件域名.example/generated/video.mp4?临时签名参数",
      "format": "mp4",
      "metadata": {
        "model": "doubao-seedance-2-5-720p",
        "duration": 4,
        "elapsed_seconds": 120,
        "resolution": "720p",
        "ratio": "16:9",
        "progress_stage": "completed",
        "progress_text": "视频生成完成"
      }
    }
  }
}

字段关系：

data.task_id：New API 对外任务编号，通常以 task_ 开头，用于继续查询。
data.data.task_id：平台内部的视频任务编号，通常以 video_ 开头，普通用户不需要拿它查询 New API。
data.data.url：Seedance、MiniMax、Grok 等模型的上游原始下载 URL。
data.result_url：New API 统一生成的下载入口；Gemini Omni 必须使用这个地址。

Gemini Omni 因为上游只返回 Base64 视频数据，没有原始下载 URL。平台将 Base64 解码保存为 MP4 后，成功返回如下：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_0123456789abcdef",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://api.catertx.com/v1/videos/task_0123456789abcdef/content",
    "data": {
      "task_id": "video_0123456789abcdef",
      "status": "completed",
      "url": "/v1/videos/video_0123456789abcdef/content",
      "format": "mp4",
      "metadata": {
        "model": "gemini-omni-flash-preview",
        "elapsed_seconds": 53,
        "resolution": "720p",
        "ratio": "16:9",
        "progress_stage": "completed",
        "progress_text": "视频生成完成"
      }
    }
  }
}

成功结果的下载字段对照：

模型	推荐读取字段	是否为原始公网 URL
`doubao-seedance-2-0-*`	`data.data.url`	是
`doubao-seedance-2-5-*`	`data.data.url`	是
`MiniMax-H3-*`	`data.data.url`	是
`grok-imagine-video-*`	`data.data.url`	是
`gemini-omni-flash-preview`	`data.result_url`	否，由平台保存 Base64 视频后提供

建议前 1 分钟每 5 秒查询一次，之后每 10～15 秒查询一次。当 data.status 变成 SUCCESS 或 FAILURE 后停止查询。

章节 13

13. 下载生成结果#

普通模型#

当 data.data.url 是完整的 http:// 或 https:// 地址时，直接下载原始视频：

curl -L \
  -o result.mp4 \
  '查询结果中data.data.url的完整地址'

原始视频 URL 通常带临时签名和有效期。请完整复制 URL、保留所有查询参数，并在任务完成后及时下载。

Gemini Omni#

Gemini 没有原始 URL，请直接使用查询结果最外层的 data.result_url，并继续携带同一个 New API 用户 API Key：

curl -L \
  -H 'Authorization: Bearer sk-你的API密钥' \
  -o result.mp4 \
  'https://api.catertx.com/v1/videos/task_0123456789abcdef/content'

不要把内层 /v1/videos/video_.../content 直接当作 New API 查询地址；对外下载应优先使用完整的 data.result_url。

检查下载结果#

ls -lh result.mp4
head -c 16 result.mp4

正常 MP4 文件开头附近通常能看到 ftyp。如果文件只有几十或几百字节，并且内容以 { 开头，它实际上是错误 JSON，不是视频文件。可以运行：

head -c 500 result.mp4

如果看到 private IP address not allowed，请把错误交给平台管理员处理。这表示平台内部下载地址被安全策略拦截，无需重新生成视频。

章节 14

14. 错误返回#

错误通常采用以下格式：

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "参数不符合当前模型要求",
    "param": "duration"
  }
}

常见状态码：

状态码	说明
400	请求格式错误、模型参数不支持或模型无权限
401	API Key 无效或未携带鉴权信息
404	任务不存在，或者任务不属于当前 API Key
409	视频尚未生成完成，暂时不能下载
429	请求过于频繁，请稍后重试
502	视频服务暂时异常，可稍后重新提交
504	网关等待超时；真人参考视频请确认已经设置 `metadata.video_contain_person=true`

下载接口返回 HTTP 200 也不代表文件一定是视频；如果文件异常小，请按照上一节检查文件内容。

常见参数错误：

Gemini 不能设置 duration 和 seed。
MiniMax-H3 不能使用 Base64，且两种素材模式不能混用。
Grok 必须提供公网图片。
Seedance 2.0 支持到 4K；Seedance 2.5 只支持 480p 和 720p。
Seedance 真人参考图与普通图片使用相同请求格式，不要自行传入平台内部的素材转换参数。
Seedance 参考视频包含真人时必须设置 metadata.video_contain_person=true。如果未设置，可能返回 reference_video_person_detected。
video_contain_person 只接受布尔值 true 或 false，推荐仅在确实包含真人时传入。
所有模型都不能传 fps，n 只能为 1。

章节 15

15. 最简调用流程#

1. POST /v1/video/generations 提交任务
2. 保存返回的 New API task_id（通常以 task_ 开头）
3. 每隔 5～15 秒 GET /v1/video/generations/{task_id}
4. data.status=SUCCESS 后停止查询
5. 普通模型读取 data.data.url；Gemini 读取 data.result_url
6. Gemini 下载时继续携带同一个 New API 用户 API Key

让视频生成像调用一个接口一样简单

1. 接口信息#

接口列表#

2. 查询可用模型#

3. 通用提交方法#

4. 通用请求字段#

5. 素材输入格式#

公网 URL#

Base64 Data URL#

纯 Base64 对象#

Base64 多参考图完整示例#

真人参考图#

指定图片作用#

6. 模型能力对照#

7. Doubao Seedance 2.0#

多模态参考生成#

参考视频包含真人#

8. Doubao Seedance 2.5#

720p 文生视频#

多张参考图#

9. MiniMax-H3#

文生视频#

首尾帧模式#

多模态参考模式#

10. Grok Imagine Video#

单图生视频#

多图参考生成#

生成成功返回（已脱敏）#

11. Gemini Omni Flash Preview#

文生视频#

单图生视频#

多图参考生视频#

视频编辑#

12. 查询任务状态#

生成成功示例（已脱敏）#

13. 下载生成结果#

普通模型#

Gemini Omni#

检查下载结果#

14. 错误返回#

15. 最简调用流程#

让视频生成
像调用一个接口一样简单