Kling Image 4.0
Kling の画像モデルです。テキスト、最大 10 枚の参照画像、名前付きエレメントから、1 タスクで 1~9 枚の画像を 2K、4K、8K で生成・編集します。
- 非同期です。作成リクエストはすぐにタスク ID を返し、タスクが成功すると画像を取得できます。
- 1 タスクで
nにより 1~9 枚を生成し、各画像はresolutionの料金で課金されます。 - テキストからの生成に加え、公開 HTTPS リンクで渡した参照画像と名前付き
elements(合計 10 個まで)を使った編集・合成に対応します。 - プロンプトでは入力を指定します。
imagesは順に@image_1、@image_2…、エレメントは@とその名前です。 resolution(2K、4K、8K)ごとの 1 枚単位の料金に、参照画像とエレメント 1 つごとの固定料金が加わります。失敗したタスクは課金されません。
このモデルをテスト画面で開きます。BeatAPI の API キーを入力するとタスクを作成できます。実際に呼び出され、ご自身の残高から課金されます。
エンドポイントと認証
POST https://api.beatapi.io/v1/images/tasks
Authorization
string
必須
BeatAPI の API キーを Bearer <BEATAPI_API_KEY> の形式で送信します。キーはダッシュボードで作成できます。キーはサーバー側で保管し、ブラウザーやモバイルアプリに含めないでください。
ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。
リクエストの流れ
タスクを作成する
下記のパラメーターをエンドポイントに POST します。201 が返れば、タスクが受け付けられ、料金が残高から仮確保されたことを意味します。処理はバックグラウンドで実行されます。data.id を保存してください。
完了を待つ
GET /v1/tasks/{task_id} を呼び出し、status が succeeded または failed になるまで、呼び出しの間隔を data.poll_after_seconds(画像は 5 秒、動画は 8 秒)だけ空けてください。あるいは task.succeeded と task.failed のWebhookを登録することもできます。処理タイムアウトで停止したタスクはイベントを送信しないため、フォールバックとしてポーリングも続けてください。
入力モード
リクエストパラメーター
model
string
必須
実行するモデル。
値:kling-image-v4
値が正しくない場合
- 未指定:
"model" is required - 存在しないモデル ID:
"model" kling-image-v9 is not catalogued - 動画モデルをこのエンドポイントに送った:
"model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint
prompt
string
必須
描く内容、または参照画像で変える内容です。被写体、スタイル、光、構図、画像に入れる文字を書き、各入力を @ メンションで指定します。
長さ:1–20000 文字
- 長さは文字数で数えます(CJK の 1 文字は 1 文字です)。
- メンション:
imagesはリスト順に@image_1、@image_2…、エレメントは@に続けてそのnameを書きます。 - すべての
@image_Nは同じリクエストの画像を指す必要があります。画像が 2 枚なのに@image_3と書くと、タスク作成時に拒否されます。
値が正しくない場合
- 未指定:
"prompt" is required - 空、または上限を超える長さ:
"prompt" has an unsupported length - リクエストに含まれない画像のメンション:
the prompt names @image_3, which this request does not send
images
string[]
任意
編集・合成に使う参照画像です。プロンプトではリスト順に @image_1、@image_2 … と書きます。
要素数:1–10
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 各項目は JPEG または PNG ファイルを指す公開
https://リンクである必要があります。タスク作成時に BeatAPI は各リンクを読み取り、そのような画像でないもの、または下記の上限を外れるものを、位置を示して拒否します(images[0]が 1 つ目のリンク)。 imagesとelementsは合計 10 個までです。- リンク 1 つごとにタスクへ固定料金が加わります(課金を参照)。
値が正しくない場合
- 上限を超える:
"images" accepts at most 10 items - 空の配列:
"images" requires at least 1 item - https:// のリンクではない:
"images[0]" must be a public HTTPS URL - JPEG・PNG 以外のファイル(この例では WebP):
"images[0]" is not a PNG or JPEG image: the URL returned image/webp - リンクがエラーを返す:
"images[0]" could not be downloaded: the URL returned HTTP 404 - 画像とエレメントが合計 10 個を超える:
Kling Image 4.0 takes at most 10 images and elements together
例
elements
object[]
任意
キャラクター、動物、小物、衣装、シーンなどの名前付きの被写体です。それぞれ 2~4 枚の画像で示し、プロンプトでは @ に続けてその name を書きます。
要素数:≤ 10
- オブジェクトの配列です。各オブジェクトが受け付けるキーは次のとおりで、それ以外は受け付けません。
elements[].name(文字列、必須):英字、数字、アンダースコア、漢字の 1~20 文字。同じリクエスト内で大文字・小文字を区別せず一意である必要があります。image_N、video_N、voice_N、keyframe_N、object_N、audio_N、first_frame、last_frameは使えません。elements[].element_input_urls(文字列の配列、必須):エレメントの画像を指す公開 HTTPS リンク 2~4 個。1 枚目がメインビューです。elements[].tag(文字列、任意):エレメントの種類。elements[].description(文字列、任意):エレメントの説明。100 文字まで。- エレメントは画像のみです。このモデルは動画エレメントと音声付きのエレメントを受け付けません。
imagesとelementsは合計 10 個までです。エレメント 1 つごとに、含む画像の枚数にかかわらずタスクへ固定料金が加わります。
値が正しくない場合
- エレメントが 10 個を超える:
"elements" accepts at most 10 items - エレメントがオブジェクトではない:
"elements[0]" must be an object nameのないエレメント:"name" is required in "elements[0]"element_input_urlsのないエレメント:"element_input_urls" is required in "elements[0]"nameが空、または 20 文字を超える:"elements[0].name" has an unsupported lengthnameに他の文字を含む、または予約名:elements[0].name "image_1" is not a name Kling V4 accepts- 同じ
nameが 2 回(大文字・小文字を区別しない):elements[1].name "Hero" is used twice - 画像が 2 枚未満:
"elements[0].element_input_urls" requires at least 2 item - 画像が 4 枚を超える:
"elements[0].element_input_urls" accepts at most 4 items - 一覧にない
tag:"elements[0].tag" must be one of: [character animal prop costume scene effect others] - 100 文字を超える
description:"elements[0].description" has an unsupported length - 動画など、エレメントが受け付けないキー:
field "element_input_video_urls" is not supported in "elements[0]"
例
aspect_ratio
string
任意デフォルト: auto
画像の縦横比(幅:高さ)。
指定できる値:auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
デフォルト:auto
- 省略すると
autoになり、プロンプトと入力画像からモデルがフレームを決めます。形が重要な場合は比率を指定してください。
値が正しくない場合
- 一覧にない値:
"aspect_ratio" must be one of: [auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9]
resolution
string
任意デフォルト: 2K
画像のサイズ区分:2K、4K、8K。区分ごとに 1 枚あたりの料金が異なります。
指定できる値:2K, 4K, 8K
デフォルト:2K
- 省略すると
2Kが使われ、その料金で課金されます。 - 2K と 4K の画像は PNG、8K の画像は JPEG で返ります。
- K は大文字で指定してください。
2kは拒否されます。1K の区分はなく、2048x2048のようなピクセルサイズも受け付けません。
値が正しくない場合
- 一覧にない値(例:
1Kや2k):"resolution" must be one of: [2K 4K 8K]
n
integer
任意デフォルト: 1
このタスクで生成する画像の枚数です。すべての画像に同じプロンプト、入力、比率、区分が使われます。
デフォルト:1
範囲:1–9
- 省略すると
1です。 - 各画像は
resolutionの料金で課金されるため、nは画像部分の料金を倍増させます。参照画像とエレメントの料金はタスクごとに 1 回だけで、枚数分は重ねて課金されません。 - 課金は届いた画像の枚数に基づきます。
値が正しくない場合
- 範囲外、整数ではない、または文字列で送った:
"n" is outside its supported range
ゲートウェイはタスク作成前に、次の組み合わせも確認します。
nで 1 回のリクエストから 1~9 枚を生成します。各画像は解像度の料金で課金され、imagesの各画像と各エレメントはリクエストごとに 1 回ずつ追加で課金されます。- プロンプトでは
imagesの画像を順に@image_1、@image_2…、エレメントを@とその名前で指定します。すべての@image_Nは同じリクエストの画像を指す必要があります。 - 1 つのエレメントは、
element_input_urlsに入れた同じ被写体の画像 2~4 枚です(1 枚目がメインビュー)。imagesとelementsは合計 10 個までです。 - エレメント名は英字、数字、アンダースコア、漢字の 1~20 文字で、大文字と小文字を区別せずに重複できません。
image_N、video_N、voice_N、keyframe_N、object_N、audio_N、first_frame、last_frameは使えません。 imagesの画像は JPEG または PNG、20 MB 以下、縦横比 2:5~5:2、各辺 8192 px 以下です。2Kと4Kは PNG、8Kは JPEG で返ります。aspect_ratio: autoでは、プロンプトと入力画像からモデルがフレームを決めます。
入力メディアの上限
ゲートウェイはタスク作成前にすべての入力を読み取り、次の上限を超えるものは、その入力を示す 400 bad_request で拒否します。課金はされません。
- ゲートウェイはタスク作成前に
imagesの各リンクを読み取り、上限を外れたものを、どれかを示すメッセージで拒否します。例:images[0] has an aspect ratio of 3.10 (width/height); this model takes 0.4 to 2.5.課金はされません。 - エレメントの画像(
element_input_urls)については、タスク作成前には公開 HTTPS リンクかどうかだけを確認します。同じ上限内の JPEG または PNG ファイルを使ってください。 - ローカルのファイルを使う場合は、
POST /v1/filesでアップロードし、返されたdata.urlを渡してください。
プロンプトのメンション
入力ごとにメンションの書き方があります。
- 対応する画像のない
@image_Nは、タスク作成時に拒否されます。例:the prompt names @image_2, which this request does not send。
このモデルが受け付けないフィールド
画像エンドポイントは、ほかの画像モデルが使うフィールドもいくつか認識します。ここでそれらを送ると、無視されるのではなく拒否されるため、効果のない設定に料金を払うことはありません。
output_format、quality、seed、background、size、enhance_prompt→field "output_format" is not supported by model kling-image-v4(送ったフィールド名が入ります)。- それ以外の未知のフィールド →
unknown field: <name>。
リクエストに不正なフィールドが複数ある場合、メッセージはそのうち 1 つだけを示します。修正してからもう一度送ってください。
リクエスト例
テキストから画像
プロンプトから 2K の画像を 1 枚生成します。
1 タスクで 4 枚のバリエーション
同じプロンプトから 4K の画像を 4 枚生成します。各画像は 4K の料金で課金されます。
1 枚の画像を編集
商品写真をキャンペーン画像に再構成します。
複数の画像を合成
プロンプトで各参照画像をメンションで指定します。
名前付きエレメント
1 つの被写体を複数の角度から撮った画像をエレメントにし、名前で配置します。
レスポンス
タスクの作成(201)
タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。
完了したタスク
GET /v1/tasks/{task_id} は HTTP 200 と status: "succeeded" を返し、結果は data.output に入ります。
出力フィールド
失敗したタスク
失敗したタスクも、GET /v1/tasks/{task_id} では HTTP 200 になります。失敗はボディに示されます。仮確保された金額は全額戻されるため、課金されません。
完全なコード例
タスクを作成し、サーバーが示すポーリング間隔で完了を待ち、結果の URL を出力します。環境変数に BEATAPI_API_KEY を設定し、requests をインストールしてください。
課金
- 各画像は
resolutionごとの料金(下表)にnを掛けて計算します。imagesのリンクとelementsのエレメントは、1 つごとにタスクにつき 1 回、固定料金が加わります。 - 料金はタスク作成時に、残高から、キーに上限がある場合はその上限からも予約されます。タスクが作られる前に拒否されたリクエストは課金されません。
- 成功したタスクは届いた画像の枚数に応じて課金されます。失敗したタスクは予約額が全額返金され、
credits_refundedはcredits_reservedと等しく、credits_chargedとcredits_settledは 0 になります。
現在の定価です。料金ページと同じ金額です。割引を個別に契約しているアカウントでは、より低い金額になります。実際に課金された金額は、タスクの data.usage で確認できます。
よくあるエラー
HTTP エラー早見表
タスクが作られる前のエラーは、2xx 以外のレスポンスで返されます。課金はされません。error.code または error.retryable で処理を分岐してください。message には問題の内容が示されます。全一覧と再試行のルールはエラーにあります。
認証
API キーを Authorization: Bearer <BEATAPI_API_KEY> として送信してください。
ヘッダー
ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。
リクエスト
実行するモデル。
値:kling-image-v4
値が正しくない場合
- 未指定:
"model" is required - 存在しないモデル ID:
"model" kling-image-v9 is not catalogued - 動画モデルをこのエンドポイントに送った:
"model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint
描く内容、または参照画像で変える内容です。被写体、スタイル、光、構図、画像に入れる文字を書き、各入力を @ メンションで指定します。
長さ:1–20000 文字
- 長さは文字数で数えます(CJK の 1 文字は 1 文字です)。
- メンション:
imagesはリスト順に@image_1、@image_2…、エレメントは@に続けてそのnameを書きます。 - すべての
@image_Nは同じリクエストの画像を指す必要があります。画像が 2 枚なのに@image_3と書くと、タスク作成時に拒否されます。
値が正しくない場合
- 未指定:
"prompt" is required - 空、または上限を超える長さ:
"prompt" has an unsupported length - リクエストに含まれない画像のメンション:
the prompt names @image_3, which this request does not send
画像の縦横比(幅:高さ)。
指定できる値:auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
デフォルト:auto
- 省略すると
autoになり、プロンプトと入力画像からモデルがフレームを決めます。形が重要な場合は比率を指定してください。
値が正しくない場合
- 一覧にない値:
"aspect_ratio" must be one of: [auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9]
キャラクター、動物、小物、衣装、シーンなどの名前付きの被写体です。それぞれ 2~4 枚の画像で示し、プロンプトでは @ に続けてその name を書きます。
要素数:≤ 10
- オブジェクトの配列です。各オブジェクトが受け付けるキーは次のとおりで、それ以外は受け付けません。
elements[].name(文字列、必須):英字、数字、アンダースコア、漢字の 1~20 文字。同じリクエスト内で大文字・小文字を区別せず一意である必要があります。image_N、video_N、voice_N、keyframe_N、object_N、audio_N、first_frame、last_frameは使えません。elements[].element_input_urls(文字列の配列、必須):エレメントの画像を指す公開 HTTPS リンク 2~4 個。1 枚目がメインビューです。elements[].tag(文字列、任意):エレメントの種類。elements[].description(文字列、任意):エレメントの説明。100 文字まで。- エレメントは画像のみです。このモデルは動画エレメントと音声付きのエレメントを受け付けません。
imagesとelementsは合計 10 個までです。エレメント 1 つごとに、含む画像の枚数にかかわらずタスクへ固定料金が加わります。
値が正しくない場合
- エレメントが 10 個を超える:
"elements" accepts at most 10 items - エレメントがオブジェクトではない:
"elements[0]" must be an object nameのないエレメント:"name" is required in "elements[0]"element_input_urlsのないエレメント:"element_input_urls" is required in "elements[0]"nameが空、または 20 文字を超える:"elements[0].name" has an unsupported lengthnameに他の文字を含む、または予約名:elements[0].name "image_1" is not a name Kling V4 accepts- 同じ
nameが 2 回(大文字・小文字を区別しない):elements[1].name "Hero" is used twice - 画像が 2 枚未満:
"elements[0].element_input_urls" requires at least 2 item - 画像が 4 枚を超える:
"elements[0].element_input_urls" accepts at most 4 items - 一覧にない
tag:"elements[0].tag" must be one of: [character animal prop costume scene effect others] - 100 文字を超える
description:"elements[0].description" has an unsupported length - 動画など、エレメントが受け付けないキー:
field "element_input_video_urls" is not supported in "elements[0]"
例
"elements": [
{
"name": "Bottle",
"tag": "prop",
"description": "A matte smart water bottle",
"element_input_urls": [
"https://your-cdn.example.com/bottle-front.png",
"https://your-cdn.example.com/bottle-side.png"
]
}
]
編集・合成に使う参照画像です。プロンプトではリスト順に @image_1、@image_2 … と書きます。
要素数:1–10
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 各項目は JPEG または PNG ファイルを指す公開
https://リンクである必要があります。タスク作成時に BeatAPI は各リンクを読み取り、そのような画像でないもの、または下記の上限を外れるものを、位置を示して拒否します(images[0]が 1 つ目のリンク)。 imagesとelementsは合計 10 個までです。- リンク 1 つごとにタスクへ固定料金が加わります(課金を参照)。
値が正しくない場合
- 上限を超える:
"images" accepts at most 10 items - 空の配列:
"images" requires at least 1 item - https:// のリンクではない:
"images[0]" must be a public HTTPS URL - JPEG・PNG 以外のファイル(この例では WebP):
"images[0]" is not a PNG or JPEG image: the URL returned image/webp - リンクがエラーを返す:
"images[0]" could not be downloaded: the URL returned HTTP 404 - 画像とエレメントが合計 10 個を超える:
Kling Image 4.0 takes at most 10 images and elements together
例
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
]
このタスクで生成する画像の枚数です。すべての画像に同じプロンプト、入力、比率、区分が使われます。
デフォルト:1
範囲:1–9
- 省略すると
1です。 - 各画像は
resolutionの料金で課金されるため、nは画像部分の料金を倍増させます。参照画像とエレメントの料金はタスクごとに 1 回だけで、枚数分は重ねて課金されません。 - 課金は届いた画像の枚数に基づきます。
値が正しくない場合
- 範囲外、整数ではない、または文字列で送った:
"n" is outside its supported range
画像のサイズ区分:2K、4K、8K。区分ごとに 1 枚あたりの料金が異なります。
指定できる値:2K, 4K, 8K
デフォルト:2K
- 省略すると
2Kが使われ、その料金で課金されます。 - 2K と 4K の画像は PNG、8K の画像は JPEG で返ります。
- K は大文字で指定してください。
2kは拒否されます。1K の区分はなく、2048x2048のようなピクセルサイズも受け付けません。
値が正しくない場合
- 一覧にない値(例:
1Kや2k):"resolution" must be one of: [2K 4K 8K]
レスポンス
タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

