视频生成 API 参考

字段	值
Base URL	https://api.gate.ai
认证	Authorization: Bearer <API_KEY>

提交视频生成任务

POST/api/v1/videos

提交异步视频生成任务，成功返回 202 及 job_id 供后续轮询状态。建议传入 Idempotency-Key 以防重复创建。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>
Content-Type	header	string	是	请求体格式
Idempotency-Key	header	string	否	幂等键，相同 key 重复提交时返回首次创建的任务，不会重复创建

请求体

名称	类型	必选	说明
model	string	是	模型 ID
prompt	string	是	视频描述，建议包含主体、动作、场景、镜头和风格。不同模型上限不同：Sora 500 字，Hailuo 2000 字，Wan T2V 1500 字、I2V 800 字。Gate.AI 本身不设硬性上限，超出后由上游拒绝并透传 502 / 503。
duration	integer	否	视频时长（秒），取值范围随模型不同
resolution	string	否	输出分辨率：480p、720p 或 1080p
aspect_ratio	string	否	宽高比：16:9、4:3、1:1、3:4、9:16、21:9 或 adaptive
generate_audio	boolean	否	是否生成音频
seed	integer	否	随机种子，-1 到 4294967295；相同 seed 不保证完全一致
size	string	否	精确输出尺寸，如 1280x720
input_references	array	否	可选参考素材数组，用于图生视频、首尾帧驱动、视频风格迁移或音频驱动生成
input_references\\\.type	string	是	参考素材类型：image、video 或 audio，必须与 role 匹配
input_references\\\.url	string	是	参考素材的 HTTPS 地址
input_references\\\.role	string	是	参考素材用途。可选值：first_frame（首帧图）、last_frame（尾帧图）、reference（外观参考图，影响生成但不作首帧、不锁定画面位置）、reference_video（参考视频）、reference_audio（参考音频）
metadata	object	否	业务透传字段，用于审计或来源标记
webhook_url	string	否	任务完成或失败后的回调地址

示例

json

1    {2        {3          "model": "bytedance/seedance-2.0",4          "prompt": "A golden retriever running on a sunny beach, cinematic camera movement",5          "duration": 6,6          "resolution": "720p",7          "aspect_ratio": "16:9",8          "generate_audio": false,9          "seed": -1,10          "input_references": [11            {12              "type": "image",13              "url": "https://cdn.example.com/portrait.jpg",14              "role": "first_frame"15            }16          ],17          "metadata": {18            "source": "playground"19          },20          "webhook_url": "https://example.com/webhooks/gateai-video"21        }

返回字段说明

名称	类型	说明
job_id	string	任务唯一 ID
status	string	任务状态：pending / in_progress / completed / failed
model	string	使用的模型
status_url	string	查询任务状态的完整 URL
message	string	服务端提示信息
current_balance	string	当前账户余额（USD）
estimated_cost	string	预估费用
pre_deduct_amount	string	预扣展示金额
balance_after_estimate	string	按预估费用计算后的余额
currency	string	货币类型，当前为 USD
billing_notice	string	计费提示

返回示例

json

1        {2          "code": 200,3          "msg": "",4          "data": {5            "job_id": "video_abc123",6            "status": "in_progress",7            "model": "bytedance/seedance-2.0",8            "status_url": "https://api.gate.ai/api/v1/videos/video_abc123",9            "message": "视频任务已提交，请调用 status_url 查询生成进度。",10            "current_balance": "100.0000000000",11            "estimated_cost": "1.0800000000",12            "pre_deduct_amount": "1.0800000000",13            "balance_after_estimate": "98.9200000000",14            "currency": "USDT",15            "billing_notice": "视频生成完成后按实际任务结果扣款，提交后请保持余额充足。"16          }17        }

返回结果

状态码	状态码含义	说明	数据模型
202	Accepted	任务已提交并排队，响应中包含用于轮询的 job_id。	VideoSubmitResponse
400	Bad Request	参数错误	ErrorResponse
401	Unauthorized	未登录或 Token 无效	ErrorResponse
402	Payment Required	余额不足，响应中包含预估费用与当前余额。	ErrorResponse
429	Too Many Requests	请求过于频繁，请降低调用频率。	ErrorResponse
500	Internal Server Error	服务内部错误	ErrorResponse

查询任务状态

GET/api/v1/videos/{job_id}

轮询任务状态、进度及计费信息。任务完成后响应中包含 download_url。

请求参数

名称	位置	类型	必选	说明
job_id	path	string	是	视频任务 ID
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>

返回字段说明

名称	类型	说明
job_id	string	任务唯一 ID
status	string	任务状态：pending / in_progress / completed / failed
model	string	使用的模型
status_url	string	查询任务状态的完整 URL
download_url	string	视频下载入口 URL（状态为 completed 后出现）
duration	integer	视频时长（秒）
resolution	string	输出分辨率
aspect_ratio	string	宽高比
generate_audio	boolean	是否包含音频
estimated_cost	string	预估费用
billed_cost	string	实际扣费金额
billing_status	string	计费状态：pre_deducted 或 settled
expires_at	string(ISO 8601)	视频文件过期时间
created_at	string(ISO 8601)	任务创建时间
completed_at	string(ISO 8601)	任务完成时间

返回示例

json

1        {2          "code": 200,3          "msg": "",4          "data": {5            "job_id": "video_abc123",6            "status": "completed",7            "model": "bytedance/seedance-2.0",8            "status_url": "https://api.gate.ai/api/v1/videos/video_abc123",9            "download_url": "https://api.gate.ai/api/v1/videos/video_abc123/content",10            "duration": 6,11            "resolution": "720p",12            "aspect_ratio": "16:9",13            "generate_audio": false,14            "estimated_cost": "1.0800000000",15            "billed_cost": "1.0800000000",16            "billing_status": "settled",17            "expires_at": "2026-06-26T05:00:00Z",18            "created_at": "2026-05-27T05:00:00Z",19            "completed_at": "2026-05-27T05:03:00Z"20          }21        }

返回结果

状态码	状态码含义	说明	数据模型
200	OK	成功	VideoStatusResponse
401	Unauthorized	未登录或 Token 无效	ErrorResponse
404	Not Found	任务不存在，或任务不属于当前 API Key。	ErrorResponse
500	Internal Server Error	服务内部错误	ErrorResponse

下载视频

GET/api/v1/videos/{job_id}

/content鉴权通过后 302 跳转至临时视频下载地址。

请求参数

名称	位置	类型	必选	说明
job_id	path	string	是	视频任务 ID
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>

返回示例

json

1        HTTP/1.1 302 Found2        Location: https://cdn.example.com/videos/video_abc123.mp4?expires=1780000000

返回结果

状态码	状态码含义	说明	数据模型
302	Found	跳转至临时视频下载地址。
401	Unauthorized	未登录或 Token 无效	ErrorResponse
404	Not Found	任务不存在，或任务不属于当前 API Key。	ErrorResponse
409	Conflict	任务尚未完成，视频暂不可下载。	ErrorResponse
410	Gone	视频内容已过期，无法下载。	ErrorResponse
500	Internal Server Error	服务内部错误	ErrorResponse