Kling Video V3
三種模型使用相同的 PopGo 影片任務介面；圖片數量、首尾影格語意與輸出規格各有差異。目前介面不開放參考影片、參考音訊；服務文件中的「音訊」欄位不等於宣告音訊參考輸入。
模型差異
| 模型 | 圖片 | 輸出音軌（服務文件） | 解析度 |
|---|---|---|---|
kling-video-v3 | 最多 2 張；第 1 張首影格，第 2 張尾影格 | 支援 | 720p / 1080p / 4K |
kling-video-v3-omni | 最多 7 張參考圖 | 支援 | 720p / 1080p / 4K |
kling-video-v3-turbo | 僅 1 張首影格 | 不支援音訊 | 720p / 1080p |
欄位與預設值
| 欄位 | 型別 | 規則 |
|---|---|---|
model | string | 必填，使用上表公開模型 ID |
prompt | string | 必填，描述主體、動作與鏡頭 |
seconds / duration | integer | 整數 3–15 秒；建議明確填寫，介面預設 5 秒 |
resolution | string | 依模型選 720p / 1080p / 4K；介面預設 720p，服務預設 4K；Turbo 不支援 4K |
aspect_ratio | string | 16:9 / 9:16 / 1:1；預設 16:9，圖生規則見下文 |
reference_images | object[] | 物件陣列；每項使用 url 或 image_url，可填公開 HTTP(S) URL 或完整圖片 Data URL |
使用 reference_images
直接呼叫 API 使用下方物件陣列。PopGo 也處理畫布上傳檔案與首尾影格欄位，但請勿同時傳多組別名。公開 URL 並非唯一來源，本機圖片可編碼為完整 Data URL。分享頁、登入頁、本機路徑都不是圖片 URL。
curl -X POST https://api.popgo.site/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL",
"prompt": "A person turns toward the camera",
"seconds": 5,
"resolution": "720p",
"reference_images": [
{"url": "YOUR_IMAGE_URL"}
]
}'
文生影片省略 reference_images；其他情況依陣列順序傳入。標準版的兩張圖是首尾影格，不是兩張風格參考。Omni 多圖用於主體或風格；Turbo 拒絕超過一張。
比例與輸出規格
服務文件記錄：標準版輸入 1024×1536 首影格，輸出為 2352×3524，比例跟隨第一張圖。固定畫幅請先裁剪輸入，不要假設 aspect_ratio 能覆寫所有圖生情境。畫布目前在首影格模式隱藏比例。
文件中的 Omni 5 秒 4K 範例為 3840×2160、24 fps、約 5.042 秒、8.9 Mbps、5.6 MB。這是單次觀察，不保證固定位元率或檔案大小。
不支援與待確認欄位
這三個模型目前不開放 reference_video、video_reference、reference_audio 或動作控制素材流程。generate_audio 控制輸出音軌，不能替代參考素材；目前畫布預設未開放該輸出開關。不要由 Omni 名稱推論動作控制。
quality 等未列明欄位可能被忽略；HTTP 200 不代表生效。seed、watermark 也不能由通用慣例推論支援。新增欄位前先確認目前介面文件，再檢查生成結果。
輪詢的四個注意事項
- 服務文件記錄 progress 可能一直為 0，直到 completed / 100；不要據此認定卡住或偽造百分比。
- 輪詢 model 可能為空；請保留提交時的模型 ID。
- usage 可能不存在；以 PopGo 用量及帳單判斷，不代表免費。
- 解析度、時長、幀率可能不回傳；下載後檢測媒體。回應時間戳也不是準確耗時依據。
文件記錄三次生成約 140、200、420 秒。建議每 10 秒輪詢，等待至少 15 分鐘；這不是時效保證。逾時後查詢原任務，勿再次提交。
錯誤與修正
| 現象 | 處理 |
|---|---|
| 400 參數錯誤 | 核對時長、比例、解析度與圖片數量，不原樣重試 |
| 404 模型或任務不存在 | 核對公開模型 ID、權限及 PopGo 任務 ID |
| 503 暫無帳號 / 502 服務暫時錯誤 | 有限退避；建立逾時先確認任務是否存在 |
| 影片未參考圖片 | 核對實際 reference_images、素材存取及結果影格；任務 ID 不證明參考生效 |
| Turbo 使用 4K 或音訊參數 | 移除不支援欄位，改用 720p / 1080p |
完成後透過 PopGo /content 或回應的可用結果 URL 下載。大檔案需足夠逾時；勿向第三方素材主機發送 PopGo API Key。完整範例見影片任務流程，費用以模型與價格為準。