可靈影片與生圖 API

{
  "error": {
    "message": "request body does not match the JSON contract: json: unknown field \"size\"",
    "type": "invalid_request_error"
  }
}

{ "url": "https://cdn.example.com/file.png" }

{ "file_id": "your-file-id" }

{
  "model": "kling-v3-omni",
  "prompt": "<<<element_1>>> 和 <<<element_2>>> 在乾淨的攝影棚桌面上緩慢旋轉",
  "duration": 5,
  "resolution": "1080p",
  "audio": false,
  "images": [
    { "url": "https://cdn.example.com/first.png", "usage": "first_frame" },
    { "file_id": "last-frame-file-id", "usage": "last_frame" },
    { "url": "https://cdn.example.com/reference-a.png", "usage": "reference" },
    { "file_id": "reference-b-file-id", "usage": "reference" }
  ],
  "videos": [
    {
      "url": "https://cdn.example.com/character-motion.mp4",
      "reference_type": "feature",
      "keep_original_sound": false
    }
  ],
  "subjects": [
    { "id": "subject-92951593344", "name": "貓" },
    { "id": "subject-92951593345", "name": "狗" }
  ]
}

{
  "model": "kling-v3-omni",
  "prompt": "兩段式產品展示短片",
  "duration": 5,
  "shots": {
    "mode": "customize",
    "segments": [
      { "index": 1, "prompt": "盒子打開", "duration": 2 },
      { "index": 2, "prompt": "產品出現", "duration": 3 }
    ]
  }
}

{
  "model": "kling-v3-motion-control",
  "prompt": "跟隨舞者的動作",
  "resolution": "1080p",
  "images": [{ "file_id": "person-image-file-id" }],
  "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
  "extra": { "character_orientation": "video" }
}

curl https://api.essevin.com/v1/kling/faces \
  -H "Authorization: Bearer sk-你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{"videos":[{"file_id":"source-video-file-id"}]}'

{
  "model": "kling-lip-sync",
  "extra": {
    "session_id": "face-session-id",
    "face_choose": [
      { "face_id": "face-1", "sound_file": "https://cdn.example.com/voice.mp3" }
    ]
  }
}

  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-v3","prompt":"紅球在白桌面上滾動","duration":5,"resolution":"720p"}'

  -H "Authorization: Bearer sk-your-key"

# 出現表外欄位
request body does not match the JSON contract: json: unknown field "<欄位名>"

# prompt 與 images 都為空
prompt and input images cannot both be empty

# images[] 某項 url / file_id 都沒有或都有
images[<序號>] must provide exactly one of url or file_id

# url 不是公開的 http(s) 絕對位址
images[<序號>].url must be a publicly accessible absolute http(s) URL

# images[] 帶了 usage
images[<序號>].usage is not part of the image generation API; remove this field

# kling-image-v2-1 帶了圖片
model "kling-image-v2-1" is a text-to-image model and does not accept input images

# kling-image-v2-1-i2i 不是 1 張圖
model "kling-image-v2-1-i2i" requires exactly 1 input image

# kling-image-v2-1-multi-ref 不是 2–4 張圖
model "kling-image-v2-1-multi-ref" requires 2 to 4 input images

# 擴圖不是 1 張圖
image expansion requires exactly 1 input image

# 擴圖 extra 含四個比例以外的鍵
extra.<鍵> is not a verified parameter of the image expansion API

# 擴圖比例不是 0–2 的數字
extra.<鍵> must be a number between 0 and 2

# 四個比例全為 0
the four expansion ratios cannot all be 0

# 擴圖後面積超過原圖 3 倍
expanded area cannot exceed 3x the original image

# 非擴圖型號帶了 extra
model "<模型 ID>" does not accept unverified extra parameters

# 該型號沒有這個 quality 檔
model "<模型 ID>" does not support quality tier "<值>"

# n 不在 1–9
n must be between 1 and 9, got <值>

# 參考圖超過型號上限
model "<模型 ID>" accepts at most <上限> input images, got <張數>

{
  "model": "kling-image-v3",
  "prompt": "A ceramic teapot on a sunlit table",
  "quality": "1k",
  "n": 1
}

{
  "model": "kling-image-expand",
  "images": [
    {
      "url": "https://example.com/input.png"
    }
  ],
  "extra": {
    "left_expansion_ratio": 0.5,
    "right_expansion_ratio": 0.5,
    "up_expansion_ratio": 0,
    "down_expansion_ratio": 0
  }
}

{
  "id": "ktEXAMPLE",
  "object": "image.generation.task",
  "status": "queued",
  "model": "kling-image-v3",
  "requested_images": 1
}

{
  "id": "ktEXAMPLE",
  "status": "completed",
  "outputs": [
    "https://api.essevin.com/example-signed-image.png"
  ]
}

{
  "id": "ktEXAMPLE",
  "status": "failed",
  "error": {
    "code": "timeout",
    "message": "task did not reach a billable terminal state within 2 hours; polling stopped"
  }
}

# 沒有 prompt 也沒有任何素材（對口型除外）
prompt and input media cannot both be empty

# duration 為負數
duration cannot be negative

# 時長由素材決定的型號傳了 duration（動作控制、數字人、對口型）
duration of model <模型 ID> is determined by the input media; do not pass duration

# duration 超出型號範圍
model <模型 ID> supports <下限> to <上限> seconds, got <值>

# kling-o1 沒有參考生輸入時 duration 不是 5 或 10
Kling O1 without reference media only supports duration 5 or 10 seconds

# kling-v2-6 的 duration 不是 5 或 10
model kling-v2-6 only supports a duration of 5 or 10 seconds, got <值>

# aspect_ratio 不在 16:9 / 9:16 / 1:1 之內
aspect_ratio="<值>" is invalid; allowed values: 16:9 / 9:16 / 1:1

# voice_ids 非空（報錯以此開頭）
voice_ids is not available yet

# extra 含該型號不接受的鍵
extra.<鍵> is not in the verified parameter contract of model <模型 ID>

# extra 裡寫了分鏡、主體、音色或原聲參數（請改用結構化欄位）
extra.<鍵> cannot be passed through; use the structured shots parameter
extra.element_list cannot be passed through; use the structured subjects parameter
extra.voice_list is reserved; use voice_ids instead (voice selection is not available yet)
extra.keep_original_sound cannot be passed through; use videos[].keep_original_sound

# 素材 url / file_id 都沒有或都有；url 不是公開的 http(s) 絕對位址
<images 或 videos>[<序號>] must provide exactly one of url or file_id
<images 或 videos>[<序號>].url must be a publicly accessible absolute http(s) URL

# usage / reference_type 取值不合法
images[<序號>].usage="<值>" is invalid; allowed values: first_frame / last_frame / reference
videos[<序號>].reference_type="<值>" is invalid; allowed values: feature / base

# 普通生成缺少 usage / reference_type，或影片多於 1 個
images[<序號>].usage is required for standard Kling video requests
videos[0].reference_type is required for standard Kling video requests; allowed values: feature / base
standard Kling video requests accept at most 1 videos input

# 首尾幀規則
at most 1 first-frame image is allowed
at most 1 last-frame image is allowed
a last frame requires a first frame with usage=first_frame
Kling 2.1 first/last-frame generation only supports 1080p
a last frame is not supported with more than 2 reference images (got <張數>)

# 參考影片類型不被該型號支援，或 base 與圖片 / 主體混用
model <模型 ID> has no confirmed feature reference-video capability or price tier
model <模型 ID> has no confirmed base video-edit price tier
base video edit cannot be combined with images or subjects; only a single video to edit is accepted

# 參考圖數量
with a reference video, reference images + subjects cannot exceed 4, got <總數> (<圖數> images + <主體數> subjects)
without a reference video, reference images + subjects cannot exceed 7, got <總數> (<圖數> images + <主體數> subjects)
model <模型 ID> supports at most <上限> reference images, got <張數>
model <模型 ID> does not support reference-based generation

# 主體
subjects[<序號>].id is required (Kling fixed subjects must carry an Id)
model <模型 ID> does not support subjects (fixed subjects)
model <模型 ID> requires at least 1 image with usage=reference when subjects are used
prompt references "<<<element_N>>>" but no subjects were provided
prompt references "<<<element_N>>>" but subjects only has <個數> items
subjects[<序號>] is not referenced in prompt as <<<element_<N>>>>

# 分鏡
model <模型 ID> does not support shots (multi-shot storyboard)
shots.mode="<值>" is invalid; allowed values: intelligence / customize
shots.mode=customize requires segments
shots.mode=intelligence does not accept segments; shots are generated by the model
at most 6 shot segments are allowed, got <段數>
shots.segments[<序號>].index must be numbered consecutively from 1, got <值>
shots.segments[<序號>].prompt cannot be empty
shots.segments[<序號>].prompt exceeds 512 characters
shots.segments[<序號>].duration must be at least 1 seconds
sum of shot durations (<合計> s) must equal the total duration (<總時長> s)

# 動作控制
motion control requires exactly 1 motion video and 1 character image
motion control images[<序號>] does not accept usage; the character image role is fixed by the scene
motion control videos[<序號>] does not accept reference_type; the motion video role is fixed by the scene
extra.character_orientation must be image or video

# 數字人
Kling avatar requires at least 1 character image
model <模型 ID> supports at most 5 character images, got <張數>
Kling avatar does not accept videos input
Kling avatar requires exactly one of extra.sound_file or extra.audio_id
extra.sound_file must be a non-empty string
extra.audio_id must be a non-empty string
extra.sound_file must be a publicly accessible http(s) audio URL

# 對口型
Kling lip-sync does not accept images; use extra.session_id and extra.face_choose
Kling lip-sync requires a non-empty extra.session_id
Kling lip-sync requires an extra.face_choose array with exactly 1 item
extra.face_choose[0].<鍵> is not part of the lip-sync contract
extra.face_choose[0].face_id must be a non-empty string or a non-negative integer
extra.face_choose[0].sound_file must be a non-empty string
extra.face_choose[0].sound_file must be a publicly accessible http(s) audio URL

# 解析度 / 聲音 / 參考影片組合沒有對應價格檔
model "<模型 ID>" does not support billing bucket "<檔位>" for this request

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "kling-v3",
  "status": "failed",
  "created": 1790000000,
  "error": {
    "code": "timeout",
    "message": "task did not reach a billable terminal state within 2 hours; polling stopped"
  }
}