# Kling Image 4.0 Long — /images/generations

Kuaishou Kling Image 4.0 の長尺画像モード（Beta）：EC 商品詳細ページや Web ページのデザインを 1 枚の縦長画像で生成します。1K / 2K、C2PA コンテンツクレデンシャル付きの PNG オリジナルを納品し、ページの種類・長さ・解像度で課金します。

**エンドポイント:** `POST https://kovapi.com/v1/images/generations`

## クイックスタート

ほかの画像 API と同じ非同期ジョブです。送信するとジョブ id が返り、ポーリングで結果を受け取ります。EC ページには商品画像 1〜3 枚が必要で、Web ページはテキストだけでも作れます。

**手順 1：EC ページのジョブを送信（skill、length、resolution と商品画像）**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "1 枚目の画像のタンブラーの EC 商品詳細ページ：メインビジュアル、3 つのセールスポイント、利用シーン、日本語のコピー。写真に写っている情報だけを使い、スペックを作らない", "skill": "ecommerce", "length": "medium", "resolution": "1K", "images": ["https://example.com/mug.jpg"]}'
```

レスポンス（HTTP 202）

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "kling-image-4.0-long"
}
```

**ステップ 2 · `status` が `succeeded` か `failed` になるまで、2〜3 秒ごとに照会**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

成功時のレスポンス

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "kling-image-4.0-long",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "kling-image-4.0-long"}
}
```

**手順 3：data[0].url をダウンロードします。Kling が納品した PNG の長尺オリジナル（幅 1024 / 2048 px、高さは内容しだい）で、7 日間保存されます。**

**完全なサンプル（Python：送信 → 待機 → ローカルに保存）**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Web ページ：画像はなくてもよい
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "kling-image-4.0-long",
    "prompt": "スペシャルティコーヒー店「ノースバウンド・コーヒー」のトップページ：メイン画像と見出し、看板の豆 3 種、ブランドストーリー、フッター、日本語のコピー、温かみのあるミニマルなスタイル",
    "skill": "webpage",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

while job["status"] not in ("succeeded", "failed"):
    time.sleep(5)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("kling-image-4.0-long.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])
```

## 認証
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## リクエストパラメータ

`POST /v1/images/generations` のリクエスト本文（JSON）：

| パラメータ | 種別 | 必須 | 説明 |
| --- | --- | --- | --- |
| model | string | はい | モデル ID：`kling-image-4.0-long`。 |
| prompt | string | はい | 描きたい内容。画像から画像の場合は、どう変えるかを書きます。 |
| skill | string | いいえ | ページの種類：`ecommerce`（EC 商品詳細ページ。images に商品画像 1〜3 枚）か `webpage`（Web ページデザイン）。省略時は画像ありなら ecommerce、なしなら webpage。 |
| length | string | いいえ | EC ページの長さ：`short`（約 2〜5 セクション）、`medium`（既定、約 6〜10）、`long`（約 11〜18）。Web ページでは指定不要です。 |
| resolution | string | いいえ | `1K`（既定、幅 1024 px）か `2K`（幅 2048 px）。4K はありません。 |
| image / images | string / array | いいえ | EC ページ：商品画像 1〜3 枚（必須）。Web ページ：最大 2 枚で、既定では 1 枚目が主体の参照、2 枚目がスタイルの参照です。jpg / png、各辺 300 px 以上、縦横比 2:5〜5:2。1 枚につき $0.003 加算です。 |
| image_roles | array | いいえ | Web ページ専用：images の各画像に対応し、`subject` か `style`。それぞれ最大 1 枚。例：`["style", "subject"]`。 |
| n | integer | いいえ | 1 回の送信で長尺画像 1 枚のみ：n は 1 だけです。 |
| callback_url | string | いいえ | タスク終了時に結果を送る先。下の Webhook の項目をご覧ください。 |

## 料金

ページの種類・長さ・解像度ごとの 1 枚単位の課金で、参照画像は 1 枚につき $0.003 加算です。送信時に仮押さえし、失敗時は全額戻ります。

| 種類 | 1K · 1 枚あたりのクレジット | 1K · 1 枚あたりの料金（USD） | 2K · 1 枚あたりのクレジット | 2K · 1 枚あたりの料金（USD） |
| --- | --- | --- | --- | --- |
| EC 商品詳細ページ · 短 | 47 | $0.235 | 56 | $0.28 |
| EC 商品詳細ページ · 中 | 94 | $0.47 | 109 | $0.545 |
| EC 商品詳細ページ · 長 | 156 | $0.78 | 172 | $0.86 |
| Web ページ | 109 | $0.545 | 119 | $0.595 |

## サイズと形式

- 幅は固定：1K は 1024 px、2K は 2048 px。高さは内容しだいです（11-20 実測で 4,257〜16,270 px）。

- C2PA コンテンツクレデンシャル付きの PNG オリジナルで、切り抜き・リサイズはしません。2K の長尺画像は数十 MB になることがあります。

- 1 回につき完成した長尺画像 1 枚を返し、HTML や編集可能なデザインファイルは返しません。

## プロンプトの書き方

- ページの目的、言語、セクションの順番、セールスポイントとコピーを明記します。コピーの言語でプロンプトを書き、「日本語のコピー」のように明記してください。

- 実際の商品情報だけを書き、「提供した商品情報だけを使い、スペックを作らない」と加えてください。モデルは渡した内容を書き、細部を補うこともあります。

- プロンプトでは 1 枚目、2 枚目の画像を @image1、@image2 と書けます。

## タスクの状態と返却フィールド

`GET /v1/images/jobs/{id}` は次のステータスを返します。各フィールドの説明は [非同期タスク](https://docs.kovapi.com/ja/guide/async-jobs#fields) をご覧ください。2〜3 秒ごとに照会するか、Webhook を使ってください。

| ステータス | 意味 |
| --- | --- |
| queued | 順番待ち。`queue_position`（前にあるタスク数）と `eta_seconds`（予想待ち時間）が付きます。 |
| processing | 生成中。 |
| succeeded | 完了。結果は `data[0].url`、課金の内訳は `usage` にあります。 |
| failed | 失敗。理由は `error` にあり、予約したクレジットは全額返金されます。 |

1 つのアカウントで同時に生成できるタスクは 50 件までで、それ以上は送信順に順番待ちになります。15 分たっても始まらないタスクは失敗となり、全額返金されます。タスクの記録は 3 日間、画像のリンクは 7 日間保存されます。

## 生成にかかる時間

実測（11-20）：1K は約 1.5〜2.5 分、2K は約 2.5 分。ページが長いほど時間がかかり、混雑時はさらにかかることがあります。

## エラーと返金

送信時のエラーはすぐに HTTP 4xx / 5xx で返り、タスクは作成されず、課金もされません。受け付け後の失敗は照会エンドポイントで報告され、確保額は全額返金されます。すべてのコードは [エラーコード](https://docs.kovapi.com/ja/guide/errors) に載っています。

### 送信時に返るエラー

| HTTP | code | 原因 | 対処 |
| --- | --- | --- | --- |
| 400 | missing_prompt | `/v1/images/generations` に `prompt` がありません。 | `prompt` を追加してください。 |
| 400 | invalid_request | 参照画像を読み込めない（リンク切れ、画像ではない、16MB 超など。どれがなぜ読めないかは `message` に記載）、`/v1/images/edits` に参照画像がない、本文が JSON オブジェクトでない、または `n` が整数ではありません。 | `message` の内容に沿って直してから、もう一度送信してください。 |
| 400 | unsupported_resolution | このモデルには選択した解像度のグレードがありません（たとえば Grok の画像生成には 4K がありません）。 | 別のグレードを選んでください。各モデルが対応するグレードは、そのドキュメントに載っています。 |
| 400 | model_not_found | モデル ID のつづりが違う・`model` がない・そのモデルをこのエンドポイントでは使えない（たとえば対話モデルで画像のエンドポイントを呼び出した）のいずれかです。 | `GET /v1/models` または [API リファレンス](https://docs.kovapi.com/ja/api) にあるモデル ID を使ってください。 |
| 401 | invalid_api_key | キーが存在しない・削除された・無効化されているか、アカウントが停止されています。 | コンソールの「API Keys」ページでキーを確認してください。 |
| 402 | insufficient_quota | このリクエストの分を確保するだけの残高がありません。ゲートウェイはまずリクエストにかかりうる最大の費用を確保するため、同時に多くの呼び出しを送ったときにも起こることがあります。 | 一度に多くの呼び出しを送った直後なら、数秒待って再試行してください。そうでなければチャージしてください。 |
| 429 | rate_limit_exceeded | このキーに設定した 1 分あたりのリクエスト数の上限を超えました（直近 60 秒で数えます）。`Retry-After` ヘッダーは付きません。 | 数秒待ってから再試行するか、コンソールでこのキーの上限を引き上げてください。 |
| 503 | model_maintenance | モデルのメンテナンス中で、リクエストを受け付けていません。その間、別のモデルが代わりに回答することもありません。 | メンテナンスが終わってから再試行してください。状況は [サービス状態](https://kovapi.com/ja/status) で確認できます。 |
| 503 | service_unavailable | 当サイト側の一時的なエラーです（参照素材の保存に失敗した場合など）。`/v1/responses` が一時的に処理できないときも、`Retry-After` 付きで 503 を返します。 | しばらくしてから再試行してください。 |

### 失敗したタスク（`status` が `failed`）

| code | 発生する場面 | 対処 |
| --- | --- | --- |
| moderation_blocked | 画像：モデル提供元の安全審査がプロンプトまたは参照画像を拒否しました（コードが `content_policy_violation` の場合もあります）。 | プロンプトを書き直すか、参照画像を差し替えてください。そのまま再送信しても、たいてい再び拒否されます。 |
| upstream_error | その他の失敗：自動で再試行しても失敗した、順番待ちが 15 分を過ぎても始まらなかった、上流が理由を示さずに拒否した、などです。具体的な状況は `message` に書かれています。 | たいていは再送信すれば成功します。 |

## ポーリングの代わりに Webhook を使う

送信時に `callback_url` を付けると、タスクが終わった時点で（成功・失敗とも）、照会エンドポイントが返すものとまったく同じ内容をゲートウェイがその URL へ送ります。署名付きで、届かなかった場合は自動で再試行します。コンソールの「設定 → Webhook」で、アカウント全体の送信先を設定することもできます。 [Webhook のドキュメント →](https://docs.kovapi.com/ja/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "スペシャルティコーヒー店「ノースバウンド・コーヒー」のトップページ：メイン画像と見出し、看板の豆 3 種、ブランドストーリー、フッター、日本語のコピー、温かみのあるミニマルなスタイル", "skill": "webpage", "callback_url": "https://your-domain.com/webhook"}'
```
