建立影片

基礎參數使用公共欄位，進階輸入透過 metadata.contents 提交，生成設定與回呼、水印分別放在 metadata.settings 和 metadata.options 中。

POST/v1/video/generations

使用平台公共欄位建立影片，透過 metadata 設定文生、圖生或 Omni 操作。同時支援相容路徑 POST /v1/videos/generations，請求參數與主路徑一致。三種操作使用同一個 kling-4.0 模型；Omni 表示多參考能力，不是另一模型。

授權

bearerAuth

授權Bearer <token>

使用平台 API Key：Authorization: Bearer your-api-key。

傳遞位置: header

請求主體

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

使用 prompt 或 metadata.contents 提供提示詞與素材；根據操作選擇相應輸入，不能將原生欄位平鋪到平台請求頂層。

model*"kling-4.0"

三種操作使用同一個 Kling 4.0 模型。

預設值"kling-4.0"

可用值

"kling-4.0"

prompt?Prompt

正向和負向描述均可寫入提示詞。純英文最多 26000 字元，純非英文最多 11000 字元；混合輸入滿足 E/26000 + N/11000 <= 1，E、N 分別為英文和非英文字元數。

image?string

單張參考圖片 URL，快捷圖生輸入。

images?array<string>

一張圖片表示首幀，兩張表示首尾幀。更多幀透過帶類型的 metadata.contents 提交。

duration?integer

影片時長快捷欄位，單位為秒。顯式 metadata.settings 設定優先。

範圍3 <= value <= 30

seconds?integer

平台支援的時長快捷欄位；建議僅使用一種時長表達，顯式 metadata.settings 設定優先。

範圍3 <= value <= 30

size?string

解析度快捷欄位，使用 720p 或 1080p，不是像素寬高。建議使用 metadata.settings.resolution 設定解析度，不與 size 重複填寫。

可用值

"720p"
"1080p"

metadata?

原生擴充設定。顯式 settings 優先；顯式設定的 false 和 0 會保留，取值仍須符合對應原生操作的欄位約束。

回應主體

`application/json`

curl -X POST "https://api.agtcloud.cn/v1/video/generations" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0",
    "prompt": "陽光下的濱海科技園，鏡頭緩慢環繞白色建築。",
    "metadata": {
      "operation": "text-to-video",
      "settings": {
        "duration": 3,
        "resolution": "720p"
      },
      "options": {
        "watermark_info": {
          "enabled": false
        }
      }
    }
  }'

{
  "id": "123456789012345678",
  "task_id": "123456789012345678",
  "object": "video",
  "model": "kling-4.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1792732542
}

建立結果與查詢

建立成功回傳頂層任務物件，其中 id 與 task_id 是字串形式的任務 ID。儲存 task_id 後，透過平台查詢API 取得狀態和影片網址。

status: "queued" 表示任務已接收並排隊，progress: 0 不代表生成失敗；建立回應本身不包含最終影片網址。created_at 使用 Unix 秒時間戳，與原生回應中的毫秒時間戳不同。

選擇輸入方式

場景	輸入方式	詳細規則
文生影片	`prompt`；進階設定指定 `metadata.operation: "text-to-video"`	文生參數
圖生影片	`image` / `images`，或帶類型的 `metadata.contents`；操作為 `image-to-video`	圖片來源與關鍵幀限制
Omni 參考或編輯	使用 `metadata.operation: "omni-video"` 和 `metadata.contents`	素材類型、引用與組合限制

顯式填寫 metadata.settings 時，其設定優先於快捷欄位。圖片、影片的素材引用 id 選用；元素和音色的引用 id 必填。無論使用哪種輸入方式，填寫的素材引用 ID 在同一任務中均不得重複。

常見錯誤與排查

回應或錯誤資訊	檢查與處理
HTTP 401，`Invalid token`	檢查 `Authorization: Bearer your-api-key`；使用請求站點對應的有效 API Key
HTTP 400，`模型名称不能为空`	填寫 `model: "kling-4.0"`
HTTP 400，`prompt cannot be empty`	文生請求需要非空 `prompt`；進階輸入按對應原生操作填寫 `metadata.contents`
HTTP 400，`duration must be an integer`	使用整數，例如 `3`，不要傳字串 `"3"` 或小數
`settings.resolution ... is invalid`	將解析度填寫為 `720p` 或 `1080p`，不要填寫像素尺寸；建議删除 `size`，統一使用 `metadata.settings.resolution`
HTTP 400，`invalid JSON request body`	檢查引號、逗號和括號；請求體應是合法 JSON，不包含註釋

HTTP 400 可能回傳 code/message/data，也可能回傳 error 物件。code: "fail_to_fetch_task" 在建立階段也可能表示上游參數校驗失敗，請讀取 message 中的實際原因，不要只根據此業務碼反復重發。

message 可能是包含 code/message/request_id 的 JSON 字串，不是已經解析的物件；可在確認格式後再解析。若需協助排查，請保留請求 ID，不要提供 API Key。實際輸入限制請參閱對應原生操作，通用校驗錯誤中的範圍不代表模型能力。

授權

請求主體

回應主體

200application/json

400application/json

401application/json

建立結果與查詢

選擇輸入方式

常見錯誤與排查

`application/json`

`application/json`

`application/json`