本文へスキップ
HopBase ドキュメント
ログイン

Kling の画像生成

Kling で画像を非同期に生成・拡張します。パラメータ、レスポンス、注意点をまとめています。

項目値
Base URLhttps://api.hop-base.com/v1
画像タスクを送信POST /v1/images/generations
タスクを照会GET /v1/video/tasks/{task_id}
プラン「Kling 公式」

Kling の画像モデルはすべて非同期タスクです。送信すると 202 とタスク id が返り、照会エンドポイントをポーリングすると、完了したタスクの outputs[] に画像 URL が入ります。

利用できるモデル

モデルモデル IDquality ティア参照画像公式価格
Kling 画像 3.0kling-image-v31k / 2k0〜1 枚$0.0294/ 枚
Kling 画像 3.0 Omnikling-image-v3-omni1k / 2k / 4k0〜10 枚$0.0294〜/ 枚
Kling 画像 O1kling-image-o11k / 2k / 4k0〜10 枚$0.0294〜/ 枚
Kling 画像 2.1（テキストから画像）kling-image-v2-11k / 2k不可$0.0147/ 枚
Kling 画像 2.1（画像から画像）kling-image-v2-1-i2i1k / 2kちょうど 1 枚$0.0294/ 枚
Kling 画像 2.1（複数参照）kling-image-v2-1-multi-ref1k / 2k2〜4 枚$0.0588〜/ 枚
Kling 画像拡張kling-image-expand1kちょうど 1 枚$0.0294/ 枚

選び方:テキストだけなら 2.1（テキストから画像）、4k や多数の参照画像が必要なら 3.0 Omni か O1、既存の画像を外側へ広げるなら画像拡張を選んでください。

リクエストパラメータ

パラメータ必須型と制限デフォルト説明
model必須文字列—上表の画像モデル ID
prompt画像なしでは必須文字列—空でない images と少なくとも一方
quality任意1k / 2k / 4k1k画質ティア。選べる値はモデルごとに異なる
n任意整数 1〜91生成枚数
imagesモデル別url / file_id の要素の配列—参照画像、または拡張する元画像
extra拡張専用4 つの拡張比率を持つオブジェクト—画像拡張を参照
  • 受け付けるのはこれらのフィールドのみで、size、aspect_ratio、response_format などは 400 になります。
  • model に動画モデルの ID を指定すると 400 になります。
  • quality は大文字・小文字を区別せず、high や standard など OpenAI 形式の値は拒否されます。
  • n は出力画像 1 枚ごとに課金されます。
  • 他の画像モデルで空でない extra を指定すると 400 になります。

参照画像

images[] の各要素には url か file_id のどちらか一方だけを指定し、usage は付けません。

{
  "model": "kling-image-v3-omni",
  "prompt": "2 枚の画像のカップを同じ木のテーブルに並べる",
  "quality": "2k",
  "images": [
    { "url": "https://cdn.example.com/cup-a.png" },
    { "file_id": "your-file-id" }
  ]
}
  • url は絶対パスで、パブリックにアクセス可能な http:// または https:// の URL である必要があります。
  • 空文字列、相対パス、file:// など HTTP(S) 以外のスキーム、プライベートやループバックのアドレス、認証情報を含む URL は送信時に同期的に拒否されます。
  • file_id は現在のキーで使える Kling 素材である必要があり、Seedance 素材 ID は使えません。
  • 参照画像の枚数はモデルごとに制限されます。利用できるモデルを参照してください。

画像拡張

kling-image-expand は 1 枚の画像を外側へ拡張します。比率は extra に指定します。

{
  "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
  }
}
  • 4 つの比率はそれぞれ 0〜2 の数値で、省略した比率は 0 です。
  • 4 つの比率をすべて 0 にはできません。
  • 拡張後の面積は元画像の 3 倍を超えられません:(1+左+右) × (1+上+下) ≤ 3。

レスポンス

送信に成功すると HTTP 202 が返り、タスク ID はトップレベルの id に kt57x<task-id> のような形式で入っています。

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

この id で GET /v1/video/tasks/{task_id} をポーリングします。完了したタスクは次のようになります。

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "kling-image-v3",
  "status": "completed",
  "progress": 100,
  "created": 1790000000,
  "outputs": [
    "https://api.hop-base.com/example-signed-image.png"
  ],
  "usage": { "bucket": "img_1k", "billed_images": 1 }
}
フィールド型説明
idstringHopBase のタスク ID。送信時と照会時で同じ
objectstring送信時は image.generation.task、照会時は video.generation.task
statusstringqueued → processing → completed または failed
progressinteger進捗率。照会時のみ
requested_imagesintegerリクエストした枚数。送信時のみ
billing_bucketstring画質に対応する課金ティア。送信時のみ
outputsstring[]画像 URL の配列。completed のときのみ
usage.billed_imagesinteger課金された枚数。実際の出力枚数と同じ
error.code / error.messagestringfailed のときのみ。失敗したタスクを参照

終了状態は completed と failed のみなので、それ以外の値は実行中として扱ってください。

タスク終了後は、照会レスポンスのルートの usage に cost(このタスクで残高から実際に差し引かれた金額。課金なしの失敗は 0)と通貨の currency も含まれます。

例

テキストから画像のタスクを送信し、終了までポーリングしてから 1 枚目の画像をダウンロードします。

# 1. 送信
curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-image-v3",
    "prompt": "日差しの当たる木のテーブルに置かれた陶器のティーポット",
    "quality": "1k",
    "n": 1
  }'

# 2. 返された id で、status が completed か failed になるまで照会
curl https://api.hop-base.com/v1/video/tasks/ktYOUR_TASK_ID \
  -H "Authorization: Bearer sk-your-key"

注意事項

  • 画像 URL は api.hop-base.com から配信され、タスク完了時点から 6 時間有効なので、早めにダウンロードしてください。
  • 再度照会しても同じ URL が返るだけで有効期限は延長されず、期限切れのリンクは 410 を返します。
  • 作成から 2 時間経っても終わらないタスクは失敗扱いとなって課金されず、タスクは取り消せません。
  • Kling の画像生成は残高の予約を行わず、残高が 0 以下になった時点でのみブロックされます。
  • 課金対象の処理を送信する前に、GET /v1/models でキーが返す正確なモデル ID を確認してください。

よくあるエラー

送信時のエラーではタスクは作成されず、課金もされません。error.message に理由が示されます。

エラー対処
request body does not match the JSON contract: json: unknown field "size"余分なフィールドを削除し、画質は quality で指定
prompt and input images cannot both be emptyprompt か参照画像を追加
images[0] must provide exactly one of url or file_id各要素に url か file_id の一方だけを残す
images[0].url must be a publicly accessible absolute http(s) URL公開された HTTP(S) の URL を使う
model "kling-image-v3" does not support quality tier "4k"モデルが対応するティアを選ぶ
model "kling-image-v2-1-multi-ref" requires 2 to 4 input imagesモデルの要件に合わせて参照画像の枚数を調整
model "<モデル ID>" is not an image model in this catalogGET /v1/models で ID を確認(404)

失敗したタスク

タスクが失敗しても、照会は HTTP 200 で返り、status は failed になります。処理の分岐は error.code の安定したコードで行い、エラーの説明をユーザーに表示してください。以前に失敗したタスクにはコードがない場合があります。

状況error.code
prompt または参照画像が審査で拒否input_sensitive
出力が審査でブロックsafety_rejected
同時実行数の上限rate_limited
モデルのバージョンが提供終了unsupported_model
prompt が長すぎる、またはパラメータや素材が不正invalid_request
参照画像を読み込めないreference_input_invalid
生成失敗、または完了前に停止generation_failed
作成から 2 時間経っても終わらないtimeout
出力なしでタスクが終了no_output

課金

Kling の画像は出力画像 1 枚ごとに、モデルと画質ティアに応じたレートで課金されます。失敗したタスクとポーリングは課金されません。各モデルの価格は上表のモデルカードに、実際の適用レートはログイン後のモデルカタログに表示されます。

次のステップ

このページの内容

利用できるモデルリクエストパラメータ参照画像画像拡張レスポンス例注意事項よくあるエラー失敗したタスク課金次のステップ