影片生成
使用支援影片生成的 Model ID 建立任務、查詢狀態,再下載生成好的影片。
影片生成是非同步的:請求只會建立一個任務,任務成功後才能取得影片。開始前,請在模型頁確認所選模型支援的解析度、時長和各解析度價格。
請求端點
影片生成用一個端點建立任務,再用三個端點後續追蹤:
| 方法與路徑 | 用途 |
|---|---|
POST /v1/videos | 建立影片生成任務 |
GET /v1/videos/{id} | 查詢任務狀態 |
GET /v1/videos/{id}/content | 下載生成好的影片 |
DELETE /v1/videos/{id} | 刪除任務(模型介面支援時) |
所有路徑都以 https://api.vergora.ai 為前綴,驗證方式與其他請求相同(Authorization: Bearer YOUR_VERGORA_API_KEY)。只有建立任務會計費。
請求範例
POST https://api.vergora.ai/v1/videos{
"model": "YOUR_VIDEO_MODEL_ID",
"prompt": "雨夜街道上漂流的紙船,鏡頭緩慢推近",
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}建立成功後,回應中有任務的 id 和初始狀態。保存好這個 id,後續每個請求都要用到它。
採用 OpenAI 相容影片介面的模型使用 seconds 和 size(例如 "8" 和 "1280x720"),而不是 duration、resolution 和 ratio。每個模型頁的「API 呼叫」分頁都提供了對應格式的請求範例。
請求欄位
| 欄位 | 說明 |
|---|---|
model | 必須是支援影片生成的 Model ID |
prompt | 描述主體、動作、場景和鏡頭運動 |
content | 結構化輸入,模型支援時取代 prompt |
input_reference | 參考圖(首幀)的 URL |
duration | 影片時長(秒) |
resolution | 輸出解析度,如 720p、1080p |
ratio | 長寬比,如 16:9(也接受 aspect_ratio) |
| 其他參數 | 只在模型明確支援時使用 |
content 可以包含文字、參考圖或輸入影片。其他參數包括 seed、watermark、generate_audio、camera_fixed、service_tier,只傳給支援它們的模型。Seedance 2.0 / 2.5 不接受 seed 和 camera_fixed,閘道會替這些模型移除。Wan 2.5 / 2.6 與 W3.0 的聲音開關是 audio(布林值,預設開啟),不是 generate_audio。
請求本文使用 JSON。需要輸入影片時,傳入一個公開連結或已上傳檔案的 key(例如放在類型為 video_url 的 content 項目裡,見下文「參考圖與參考影片」);影片不支援 data: URI。帶輸入影片的請求按模型的「帶輸入影片」價格計費。
參考圖與參考影片
參考圖或參考影片可以用下面任一種形式提供。同一個欄位三種都接受,由閘道自動區分:
| 形式 | 範例 | 說明 |
|---|---|---|
| 公開連結 | https://cdn.example.com/clip.mp4 | 由模型服務方直接下載,必須能從公開網路存取 |
| 已上傳的檔案 | uploads/u42/20261112/0123…cdef.mp4 | POST /v1/uploads 回傳的 key(見下文)。請求送達模型服務方之前會被換成一個臨時連結 |
| 內嵌資料 | data:image/png;base64,… | 僅限圖片,影片不接受內嵌資料 |
參考素材放在模型介面約定的位置:首幀圖片用 input_reference,或者放進 content 裡類型為 image_url、video_url 的項目:
{
"model": "YOUR_VIDEO_MODEL_ID",
"content": [
{ "type": "text", "text": "同一個場景的夜晚,鏡頭緩慢推進" },
{
"type": "image_url",
"image_url": { "url": "https://cdn.example.com/frame.png" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "uploads/u42/20261112/0123…cdef.mp4" },
"role": "reference_video"
}
],
"resolution": "720p",
"duration": 5
}每個模型能帶幾份參考、是否支援參考影片,以模型頁為準。每段參考影片的時長都會計入費用。
上傳參考檔案
檔案在你的本機、沒有公開連結時,先上傳,再使用回傳的 key。
- 申請上傳位址。帶上檔案類型和精確的位元組數:
POST https://api.vergora.ai/v1/uploads{ "content_type": "video/mp4", "size": 2376873 }- 回應中有
key、upload_url、method(PUT)和需要帶上的headers。依這些請求標頭把檔案上傳到upload_url。位址 15 分鐘內有效,且只接受宣告的類型和大小。
{
"object": "upload",
"key": "uploads/u42/20261112/0123456789abcdef0123456789abcdef.mp4",
"upload_url": "https://…",
"method": "PUT",
"headers": { "Content-Type": "video/mp4" },
"expires_at": 1794500000
}- 在任何接受參考圖或參考影片的欄位中使用這個
key。
| 類型 | 支援的格式 | 大小上限 |
|---|---|---|
| 圖片 | JPEG、PNG、WebP、GIF | 20 MB |
| 影片 | MP4、MOV、WebM | 200 MB |
key 只對建立它的帳號有效。上傳的檔案必須確實是所宣告類型的圖片或影片,否則使用它的請求會被拒絕。上傳的檔案只保留有限的時間,key 失效後請重新上傳。
查詢任務狀態
影片任務通常需要幾十秒到幾分鐘。每隔幾秒查詢一次狀態:
GET https://api.vergora.ai/v1/videos/{id}| 狀態 | 含義 |
|---|---|
queued | 排隊中 |
running / in_progress | 生成中 |
succeeded / completed | 已完成,可以下載 |
failed / cancelled | 已結束且沒有影片,預扣金額全額退回 |
回應結構與模型介面保持一致。按 token 計費的模型還會回傳 usage,即計費所用的 token 數。
「任務已建立」不表示影片已經生成完成。保存任務 id,便於追查失敗原因和核對費用。
下載影片
GET https://api.vergora.ai/v1/videos/{id}/content回應本文就是影片檔案(通常為 MP4)。任務成功之前,這個端點回傳 409,錯誤碼為 video_not_ready:請繼續查詢狀態,不要在迴圈中重試下載。生成的檔案只保留一段時間,任務成功後請盡快儲存到自己的儲存空間中。
費用與重試
影片模型按解析度定價,按每秒影片或每百萬 token 計費;完整價目見模型頁。
- 建立任務時,先按請求中的解析度、長寬比和時長(以及輸入影片)從餘額中預扣一筆估算金額;請求沒有寫明時,按 1080p、16:9、15 秒估算。
- 任務成功後,按實際用量結算(模型回傳的 token 數,或生成影片的整秒數),但不會超過預扣金額:用得少,差額退回;用得多,超出部分不再扣費。
- 任務失敗或被取消時,預扣金額全額退回。查詢狀態和下載影片不收費。
| 回應 | 含義 |
|---|---|
403 insufficient_user_quota | 餘額不足以支付估算金額,不會建立任務 |
503 model_price_not_configured | 該模型尚未設定影片價格 |
409 video_not_ready | 任務成功前請求了下載 |
每次 POST /v1/videos 都會建立一個新任務並單獨計費。逾時後先在請求紀錄中確認是否已經建立了任務,再決定是否重新提交。