Kling：動画生成 API

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

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

{
  "model": "kling-v3-omni",
  "prompt": "<<<element_1>>> and <<<element_2>>> rotate slowly on a clean studio table",
  "duration": 5,
  "resolution": "1080p",
  "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" }
  ]
}

{
  "videos": [
    {
      "url": "https://cdn.example.com/character-motion.mp4",
      "reference_type": "feature",
      "keep_original_sound": false
    }
  ]
}

{
  "subjects": [
    { "id": "subject-92951593344", "name": "cat" },
    { "id": "subject-92951593345", "name": "dog" }
  ]
}

{
  "model": "kling-v3-omni",
  "prompt": "A short product story in two shots",
  "duration": 5,
  "shots": {
    "mode": "customize",
    "segments": [
      { "index": 1, "prompt": "The box opens", "duration": 2 },
      { "index": 2, "prompt": "The product is revealed", "duration": 3 }
    ]
  }
}

{
  "model": "kling-v3-motion-control",
  "prompt": "Follow the dancer's movement",
  "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.hop-base.com/v1/kling/faces \
  -H "Authorization: Bearer sk-your-key" \
  -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" }
    ]
  }
}

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "kling-v3",
  "status": "queued",
  "created": 1790000000,
  "billing_bucket": "720p_silent_noref"
}

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "kling-v3",
  "status": "processing",
  "created": 1790000000
}

{
  "id": "ktEXAMPLE",
  "status": "completed",
  "outputs": [
    "https://api.hop-base.com/example-signed-image.png"
  ],
  "usage": { "bucket": "720p_silent_noref", "billed_seconds": 5, "cost": 2.55, "cost_usd": 0.375, "currency": "CNY" }
}

{
  "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"
  }
}

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

# 画像モデルを動画エンドポイントに送った(400)
model "<モデル ID>" is an image model; use /v1/images/generations

# 動画モデル ID がカタログにない(404)
model "<モデル ID>" is not in the Kling catalog

# 画像モデル ID がカタログにない(404)
model "<モデル ID>" is not an image model in this catalog

# メディアに url / file_id がない、または両方ある
<images または videos>[<番号>] must provide exactly one of url or file_id

# url が公開された絶対 http(s) アドレスでない
<images または videos>[<番号>].url must be a publicly accessible absolute http(s) URL

# prompt もメディアもない(リップシンクを除く)
prompt and input media cannot both be empty

# duration が負の数
duration cannot be negative

# 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

# 解像度 / 音声 / 参照動画の組み合わせに価格ティアがない
model "<モデル ID>" does not support billing bucket "<ティア>" for this request

# voice_ids が空でない(メッセージはこの文で始まります)
voice_ids is not available yet

# そのモデルが受け付けない extra のキー
extra.<キー> is not in the verified parameter contract of model <モデル ID>

# 入力素材で長さが決まるモデルに duration を送った
duration of model <モデル ID> is determined by the input media; do not pass duration

# usage がない、または値が不正
images[<番号>].usage is required for standard Kling video requests
images[<番号>].usage="<値>" is invalid; allowed values: first_frame / last_frame / reference

# 先頭・末尾フレームのルール
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 <枚数>)

# 参照画像の枚数
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

# reference_type がない、値が不正、または動画が 2 件以上
videos[0].reference_type is required for standard Kling video requests; allowed values: feature / base
videos[<番号>].reference_type="<値>" is invalid; allowed values: feature / base
standard Kling video requests accept at most 1 videos input

# 参照動画の種類にモデルが対応していない、または 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

# extra に元音声のパラメータを書いた
extra.keep_original_sound cannot be passed through; use videos[].keep_original_sound

# モーションコントロール
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

# 顔検出: 不正な JSON、または他のフィールドがある
request body does not match the JSON contract: …

# 顔検出: videos がない、または空の配列
videos is required and must contain at least one item

# リップシンク
Kling lip-sync does not accept images or videos; 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
extra.voice_list is reserved; use voice_ids instead (voice selection is not available yet)

# input_sensitive: prompt が審査で拒否
the prompt was rejected by content moderation; rephrase it and submit again

# input_sensitive: 参照素材が審査で拒否
the reference media was rejected by content moderation; replace it and submit again

# input_sensitive: 審査で拒否(対象の明示なし)
the prompt or reference media was rejected by content moderation; revise it and submit again

# output_video_sensitive / safety_rejected: 出力が審査でブロック
the generated result was blocked by content moderation; adjust the prompt or reference media and submit again

# rate_limited: 同時実行数の上限
this model is at its concurrency limit right now; please retry shortly

# unsupported_model: モデルのバージョンが提供終了
this model version is no longer available; switch to another model and submit again

# invalid_request: prompt が長すぎる
the prompt is too long for this model (at most 2500 characters); shorten it and submit again

# invalid_request: パラメータや素材が不正
the request was rejected as invalid by the model; check the parameters and media against the documented limits, then submit again

# reference_input_invalid: 参照素材を読み込めない
a reference image or video is missing or could not be read; make sure every URL is publicly reachable and points to a supported file, then submit again

# reference_input_invalid: 動作動画に人物の上半身全体が映っていない
the motion reference video was rejected: no complete human upper body was detected in it; use a video in which a real person's upper body (head to waist) is clearly visible, then submit again

# reference_input_invalid: 動作動画が長すぎる
the motion reference video is too long: max 10s when character_orientation=image, 30s when character_orientation=video; trim the video (or use character_orientation=video for clips up to 30s), then submit again

# reference_input_invalid: 入力動画が長すぎる(その他のモデル)
the input video is too long for this model; trim it to the documented maximum duration, then submit again

# generation_failed: 生成失敗(その他)
video generation failed; please retry, and contact support with the task ID if it keeps failing

# generation_failed: 完了前に停止
video generation was stopped before it finished; please retry, and contact support with the task ID if it keeps failing

# generation_failed: タスクを追跡できない(この文で終わります)
… contact support with the task ID

# timeout: 作成から 2 時間経っても終わらない
task did not reach a billable terminal state within 2 hours; polling stopped

# timeout: カスタムサブジェクトが 2 時間経っても終わらない
subject task did not reach a terminal state within 2 hours; polling stopped

# no_output: 出力なしでタスクが終了
video generation finished without a usable output; please retry, and contact support with the task ID if it keeps failing

# no_output: サブジェクト ID なしでカスタムサブジェクトが終了
subject creation finished without returning a subject ID; check the media and create it again