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

返回欄位說明

名稱	類型	說明
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