
このKling Image 4.0 APIガイドでは、APIキーの取得から画像の完成までを順に説明します。cURLでの1回の呼び出し、待ち時間に上限を設けたPythonのポーリングループ、そして kling-4.0-image と kling-4.0-long-image のすべての入力モードで動作するJSONボディを紹介します。どれもまずKling Image 4.0のプレイグラウンドで試せます。以下のリクエストボディはすべてPoYoのドキュメントに準拠しています。
cURLで最初のKling Image 4.0 APIリクエスト
PoYoのダッシュボードでキーを作成し、サーバー上で POYO_API_KEY として保管します。次に、2Kのテキストから画像タスクを送信します。
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-4.0-image",
"input": {
"prompt": "High fashion model wearing a dress made of living moss, standing in an abandoned greenhouse, shafts of light, editorial photography",
"size": "16:9",
"resolution": "2K"
}
}'
レスポンスには code: 200 と data.task_id が含まれ、status: "not_started" となっています。送信したタスクは、まだ完成した画像ではありません。次のコマンドで状態を確認します。
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
ステータスは not_started、running、finished、failed です。finished になると、data.files に画像ごとのエントリが file_url と file_type: "image" 付きで入り、data.credits_amount にタスクの費用が表示されます。failed の場合は data.error_message を確認してください。
待ち時間に上限のあるPythonポーリングループ
以下は requests を使ってバックエンドで実行するコードです。HTTPステータスとボディの code フィールドの両方を確認し(バリデーションエラーはHTTP 200で code: 400 として返ることがあります)、failed で停止し、20分経過したら再送信せずに待機をやめます。再送信すると2回分課金されるためです。
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(resp):
resp.raise_for_status()
body = resp.json()
if body.get("code") != 200:
raise RuntimeError(f"PoYo error {body.get('code')}: {body.get('error')}")
return body["data"]
def run(payload, max_wait=1200, every=10):
task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
return [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
time.sleep(every)
raise TimeoutError("still running, poll task " + task_id + " again later")
urls = run({
"model": "kling-4.0-image",
"input": {
"prompt": "A ceramic pour-over kettle on a walnut counter, morning window light",
"size": "1:1",
"resolution": "2K",
},
})
print(urls)
時間のかかるジョブでは、代わりにペイロードのトップレベルに "callback_url": "https://your-domain.com/poyo-hook" を追加してください。タスクが完了または失敗すると、PoYoは同じタスクデータ(code/data のラッパーなし)をPOSTします。リクエストは X-Webhook-Signature のHMAC-SHA256で署名されており、検証方法はWebhookのドキュメントに記載されています。
image_urlsによる画像から画像
image_urls に公開HTTP(S) URLを1〜10個渡します。配列の順に、1つ目が @Image1、2つ目が @Image2 になります。プロンプトでそれぞれの役割を指定し、変えてはいけない部分を明記してください。
{
"model": "kling-4.0-image",
"input": {
"prompt": "Turn @Image1 into a late-evening scene with warm window light. Keep the furniture, layout and camera angle of @Image1 unchanged.",
"image_urls": ["https://example.com/living-room.png"],
"resolution": "2K"
}
}
image_urls は画像が1枚でも配列にする必要があります。各画像は30 MB以下、幅と高さがともに300 px以上、幅と高さの比が0.4〜2.5でなければなりません。
kling_elementsで被写体を一貫させる
エレメントとは、1つのキャラクターまたはオブジェクトを2〜4のアングルから写したもので、正面の画像を先頭にします。エレメントには image_urls のエントリが少なくとも1つ必要で、最大7つまで渡せます。画像とエレメントの合計上限は10です。
{
"model": "kling-4.0-image",
"input": {
"prompt": "Place @Element1 sitting on the sofa in @Image1, reading a book in warm evening light. Keep the room layout of @Image1 unchanged.",
"image_urls": ["https://example.com/living-room.png"],
"kling_elements": [
{
"element_input_urls": [
"https://example.com/character-front.png",
"https://example.com/character-side.png",
"https://example.com/character-back.png"
]
}
],
"resolution": "2K"
}
}
このリクエストの費用は、2K画像の13クレジットに、参照画像の1とエレメントの1を加えた15クレジット($0.075)です。
enable_sequentialによる画像セット
enable_sequential: true の場合、n は2〜10(デフォルト4)となり、モデルは同じ被写体とスタイルを持つ1つのセットとして画像を計画し、順番どおりに返します。オフの場合、n は1〜9で、独立した画像を返します。
{
"model": "kling-4.0-image",
"input": {
"prompt": "A four-panel story of a paper boat drifting from a rainy city gutter to a calm sunny lake, same boat in every panel, watercolor style",
"size": "3:2",
"enable_sequential": true,
"n": 4
}
}
リリース当日のテスト(PoYo本番API、2026年11月19日)では、n: 4 の16:9・2Kセットで2720×1536の画像が4枚返され、夜明け、正午、夕暮れ、夜を通して同じライダー、バイク、服装が保たれていました。費用は52クレジットで、送信から結果取得まで約4.9分でした。
縦長のWebページとECページ
モデルIDを kling-4.0-long-image に切り替え、skill を選びます。以下は、スタイル参照に従わせることもできるWebページデザインの例です。
{
"model": "kling-4.0-long-image",
"input": {
"prompt": "Design a long image for a specialty coffee brand's official website, including the hero section, product showcase, roasting philosophy, store information, and footer. Follow the visual style of @StyleImage. All text on the page is in English.",
"skill": "webpage",
"style_image_url": "https://example.com/style-reference.png",
"resolution": "2K"
}
}
商品写真1枚から作るEC詳細ページの例です。
{
"model": "kling-4.0-long-image",
"input": {
"prompt": "Design a product detail page for the insulated water bottle in @Image1: hero shot, key features, capacity and size, materials, and lifestyle scenes. All text on the page is in English.",
"skill": "ecommerce",
"image_urls": ["https://example.com/water-bottle.png"],
"length": "medium",
"resolution": "1K"
}
}
ヒント:ページの言語を指定しましょう。 テストでは、ページ内テキストの言語を指定しなかった英語のWebページ用プロンプトで、ページに中国語のテキストが入って返ってきました。プロンプトに「All text on the page is in English.」を追加すると解消したため、上の2つのボディはどちらもこの一文で終わっています。1KのWebページのテストでは、1024×4257の画像が1枚返され、110クレジット、約1.7〜2.2分でした。
image_urls と length は ecommerce 用、style_image_url と subject_image_url は webpage 用です。ページの長さと8K出力について詳しくはKling Image 4.0 APIによる8K画像とロング画像をご覧ください。
結果の保存
各 files[].file_url はPNGを指しています。アプリから直接リンクするのではなく、自社のストレージにコピーしてください。リリース当日のテストから、備えておくべき点が3つあります。
- サイズ。 16:9の8K画像1枚は、10880×6144、約128 MBのPNGでした。メモリに読み込むのではなくディスクにストリーミングし、クライアントの読み取りタイムアウトを延ばしてください。
- アルファチャンネル。 不透明な画像でも、ダウンロードしたファイルはRGBAのPNGでした。パイプライン、CDN、印刷ワークフローがRGBやJPEGを前提としている場合は、ダウンロード後に変換してください。
- 順序。 画像セットは順番どおりに返されるため、
filesのインデックスがそのまま絵コンテやスライドセットのフレーム番号になります。
送信前に確認しておきたいバリデーションルール
| ルール | モデル |
|---|---|
prompt は1〜50,000文字、空白のみは不可 | 両方 |
image_urls は1〜10項目。各30 MB、300 px以上、比率0.4〜2.5 | kling-4.0-image |
kling_elements は7以下、各2〜4個のURL、image_urls がある場合のみ。画像 + エレメントは10以下 | kling-4.0-image |
n はセットなしで1〜9、enable_sequential: true で2〜10 | kling-4.0-image |
resolution は 2K / 4K / 8K | kling-4.0-image |
skill: "ecommerce" には1〜3個の image_urls が必要。resolution は 1K / 2K | kling-4.0-long-image |
余分なフィールドは不可(output_format、seed、negative_prompt は拒否される) | 両方 |
対処すべきエラー
code | 意味 | 対処 |
|---|---|---|
| 400 | パラメータが無効 | ボディを修正する。そのまま再試行しない |
| 401 | APIキーがない、または無効 | ヘッダーを確認する |
| 402 | クレジット不足 | チャージしてから再送信する |
| 429 | レート制限 | 間隔を空けて後で再試行する |
| 500 / 502 / 503 | サーバーまたは上流のエラー | バックオフしながら送信を再試行する |
failed のタスクには課金されないため、失敗後の再送信は安全です。一方、自分の側でタイムアウトした後の再送信は安全ではありません。まず同じ task_id をポーリングしてください。
最初の請求額の計算方法
kling-4.0-image の費用は、1枚あたりの料金×画像枚数に、image_urls の各項目とエレメントごとに1クレジット(1リクエストにつき1回)を加えたものです。1クレジット = $0.005で計算すると次のとおりです。
| リクエスト | クレジット | USD |
|---|---|---|
| 上記の最初のcURL呼び出し(2K、1枚) | 13 | $0.065 |
| 同じプロンプトを8Kで | 32 | $0.16 |
| 上記のエレメント編集(2K、画像1枚 + エレメント1つ) | 15 | $0.075 |
| 2Kの4枚セット | 52 | $0.26 |
| 1KのWebページ、参照なし | 110 | $0.55 |
| 1Kのmedium ECページ、商品写真1枚 | 95 | $0.475 |
全料金表とその他の計算例はKling Image 4.0 APIの料金にあります。2つのモデルIDの概要はKling Image 4.0とはをご覧ください。
よくある質問
PythonでKling Image 4.0 APIを呼び出すには?
requests でJSONボディを https://api.poyo.ai/api/generate/submit にPOSTし、data.task_id を読み取ったら、finished になるまで /api/generate/status/{task_id} をポーリングして files[].file_url を読み取ります。上記のループは、期限とエラーチェック付きでこれを行います。
Kling Image 4.0 APIのモデルIDは何ですか?
テキストから画像、編集、画像セットには kling-4.0-image、縦長のWebページとECページには kling-4.0-long-image を使います。kling-4-0-image はページのスラッグにすぎません。
Kling Image 4.0 APIはWebhookに対応していますか?
はい。リクエストのトップレベルに callback_url を追加してください。タスクが完了または失敗すると、PoYoが署名付きのPOSTを送信します。
Kling Image 4.0 APIでJPEGを出力できますか? 出力形式を指定するフィールドはなく、結果はPNGです。私たちがダウンロードしたファイルは不透明な画像でもRGBAのPNGだったので、JPEGが必要な場合は自分の側で変換してください。
Kling Image 4.0の縦長Webページが別の言語で返ってきたのはなぜですか? プロンプトでページ内テキストの言語を指定しないと、モデルが言語を選ぶことがあります。たとえば「All text on the page is in English.」のように明記してください。