> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kling V4 Image 画像生成

> テキストからの画像生成、最大 10 枚の参照画像による画像生成、2–4 枚の関連画像のシリーズ生成に対応。通常モードでは 1 回に 1–9 枚の 2K / 4K / 8K PNG を出力します。

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": true
}'
```

```python Python theme={null}
import requests

payload = {
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": True
}
response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": true
};
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example_kling_v4_image"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "`prompt` is required for kling-v4-image",
    "type": "invalid_request_error"
  }
}
```

`model: "kling-v4-image"` を指定して `POST /v1/images/generations` に非同期タスクを送信します。`data[0].task_id` を取得し、`GET /v1/tasks/{task_id}` で結果を確認します。

## 認証

**Authorization** `string` *required*

`Authorization: Bearer <token>` を使用します。`<token>` は APIMart API キーです。

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

**model** `string` *required*

`kling-v4-image` を指定します。

**nsfw\_check** `boolean` (default: false)

画像タスクを送信する前にコンテンツモデレーションを実行するかどうかを指定します。

* `true`：`omni-moderation-latest` でプロンプトと入力画像を審査
* `false` または省略：審査リクエストを行わず、審査コストや遅延を追加しない（デフォルト）

**prompt** `string` *required*

テキストからの生成、参照画像を使う生成、シリーズ生成のすべてで必須です。含めたい内容と避けたい内容を記述できます。英語のみの場合は最大 50,000 文字、中国語などのみの場合は最大 21,000 文字。複数言語が混在する場合は比率に応じて計算されます。

**image\_urls** `string[]`

公開アクセス可能な画像の直接 URL を最大 10 件指定します。ローカルファイルは[画像アップロード API](https://docs.apimart.ai/ja/api-reference/uploads/images.md)でアップロードし、返された `url` を指定できます。

JPG / JPEG / PNG / GIF に対応。1 枚あたり 30 MB 以下、幅・高さともに 300 px 以上、アスペクト比は 2:5–5:2。

送信時に参照画像を検証します。URL が HTTP 403 / 404 / 410 を返す、いずれかの辺が 300 px 未満、比率が 2:5–5:2 の範囲外、または 30 MB 超の場合、即座に HTTP 400 を返します。タスクは作成されず、生成料金も発生しません。配信元のタイムアウトなど、その他の取得エラーは一旦受理した後にタスクが失敗し、事前に引き落とした生成料金は全額返金されます。

プロンプト内で `@Image1`、`@Image2` などを使うと配列順に画像を指定できます。これらの記号を省略しても入力画像は参照されます。

**n** `integer` (default: 1)

通常モードの出力枚数。1–9 の整数で、デフォルトは 1。シリーズモードでは `n` を省略するか `1` を指定でき、出力枚数は `sequential_image_generation_options.max_images` で決まります。シリーズで `n > 1` を指定すると HTTP 400 が返ります。

**resolution** `string` (default: 2K)

`2K`（デフォルト）、`4K`、`8K` に対応し、大文字・小文字は区別しません。出力は PNG です。`1:1` の場合、2K は `2048×2048`、4K は `4096×4096`、8K は `8192×8192`。その他の比率では返された画像の実際の寸法を確認してください。

8K でもテキストからの生成、参照画像を使う生成、シリーズ生成に対応します。通常生成は 1–9 枚、シリーズは 2–4 枚、参照画像は最大 10 枚です。参照画像の形式・寸法条件と 1 枚あたり 30 MB の上限は変わりません。

**size** `string` (default: auto)

出力アスペクト比。`auto`（デフォルト）と次の 8 種類に対応します。

`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`。

`auto` はプロンプトや参照画像に応じて比率を決めます。`2048x2048` などのピクセル寸法は指定できません。

**aspect\_ratio** `string`

`size` の別名で、同じ値を指定できます。両方を指定した場合は `aspect_ratio` が優先されます。

**sequential\_image\_generation** `string` (default: disabled)

`disabled` または省略で通常生成。`auto` にすると関連する画像をシリーズとして生成し、`sequential_image_generation_options.max_images` が必須になります。この `auto` は枚数の自動決定を意味しません。

**sequential\_image\_generation\_options** `object`

シリーズモードの枚数を指定するオブジェクト。

**プロパティ**

**max\_images** `integer`

シリーズモードでは必須。2–4 の整数で出力枚数を指定します。省略、文字列 `"auto"`、範囲外の値はいずれも HTTP 400 になります。

> [!WARNING]
>
> `width`、`height`、`mask_url`、ピクセル形式の `size`、`watermark: true` は非対応で、指定すると HTTP 400 が返ります。

## リクエスト例

以下は `POST /v1/images/generations` に送信します。画像 URL は実際にアクセスできる直接リンクに置き換えてください。

### 参照画像を使った生成

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "Use the dog in @Image1 as a reference for a 3D animated character poster, preserving its fur color and features",
  "image_urls": [
    "https://example.com/dog.png"
  ],
  "size": "3:4",
  "resolution": "2K"
}'
```

### 4K 画像を 3 枚生成

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "A quiet mountain lake at sunrise, detailed landscape photography",
  "size": "16:9",
  "resolution": "4K",
  "n": 3
}'
```

### 8K 画像を 1 枚生成

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "A sweeping aerial view of a misty mountain valley at sunrise",
  "resolution": "8K",
  "size": "16:9",
  "n": 1
}'
```

### 関連する 8K 画像 4 枚のシリーズを生成

シリーズでは `max_images` に 2–4 を指定します。`n` は省略または `1` にでき、`1` を超える値は指定できません。数分かかる場合があるため、`task_id` を保存して状態を確認し、同じリクエストの再送は避けてください。

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "The same tree in spring, summer, autumn, and winter, consistent picture-book style",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {
    "max_images": 4
  },
  "size": "3:4",
  "resolution": "8K"
}'
```

## 8K 出力と所要時間の例

以下はテスト環境での実測例です。寸法、ファイルサイズ、所要時間は参考値であり、実際の結果によって異なります。

| 8K リクエスト | 出力寸法 | 1 枚のファイルサイズ | 完了までの時間 |
| - | - | - | - |
| 通常生成 1 枚（16:9） | `10880×6144` | 117 MB | 約 2.5 分 |
| 通常生成 4 / 9 枚（1:1） | `8192×8192` | 100–130 MB | 約 3 分 |
| シリーズ 4 枚（3:4） | `7040×9344` | 77–104 MB | 約 6 分 |

`completed` または `failed` になるまで 5–10 秒間隔で照会してください。`estimated_time` は 60 秒固定であり、実際の完了予測やカウントダウンには使用できません。`task_id` を保存し、待機中の重複送信を避けてください。

8K の結果は PNG 原画像で、1 ファイルが 100 MB を超える場合があります。一覧やプレビューでは自分で生成したサムネイルを使うか、必要時に読み込んでください。原画像のダウンロード導線を用意し、ファイルサイズが大きいことを表示してください。

## タスクの確認

[タスク照会 API](https://docs.apimart.ai/ja/api-reference/tasks/status.md) の `data.status` を確認します。`pending` / `processing` は処理中、`completed` は成功です。`failed` の場合は `data.error.message` を参照します。

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/task_example_kling_v4_image' \
  --header 'Authorization: Bearer <token>'
```

以下は成功結果の構造例です。画像 URL は `data.result.images[].url[]` にあり、`url` は配列です。すべての出力を取得し、早めにダウンロードしてください。

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_image",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-image.png"
          ]
        }
      ]
    }
  }
}
```

## 料金

実際の出力枚数と選択した解像度に応じて課金されます。参照画像は別途 1 枚ごとに課金されます。単価は[料金ページ](https://apimart.ai/pricing)を確認してください。

| 課金対象 | 料金項目 |
| - | - |
| 2K 出力画像 1 枚 | `kling-v4-image@2K` |
| 4K 出力画像 1 枚 | `kling-v4-image@4K` |
| 8K 出力画像 1 枚 | `kling-v4-image@8K` |
| 入力参照画像 1 枚 | `kling-v4-image@input` |

* 通常生成で `n=3` の場合は出力 3 枚分、シリーズは実際に返された枚数分を課金します。
* 各参照画像はリクエストごとに 1 回だけ計上し、出力枚数では乗算しません。参照画像 2 枚から 3 枚生成する場合、入力 2 枚と出力 3 枚分です。
* 生成に失敗したタスクの生成料金は発生せず、事前に引き落とした生成料金は全額返金されます。

## よくあるパラメータエラー

以下のエラーは送信時に同期的に HTTP 400 を返し、タスクを作成せず、生成料金も発生しません。送信エラーは `error.message`、タスク作成後の失敗は `data.error.message` を確認します。

| エラー抜粋 | 対処方法 |
| - | - |
| `` `prompt` is required for kling-v4-image `` | 空でないプロンプトを指定してください。 |
| `` `n` must be an integer between 1 and 9 `` | `n` は 1–9 の整数にしてください。 |
| `` `n` cannot be combined with sequential_image_generation=auto `` | シリーズでは `n` を省略または `1` にし、出力枚数は `max_images` で指定します。 |
| `` `sequential_image_generation_options.max_images` is required for kling-v4-image series mode `` | シリーズ生成には `max_images` が必要です。 |
| `` `sequential_image_generation_options.max_images` must be an integer between 2 and 4 `` | `"auto"` ではなく 2–4 の整数を指定します。 |
| `` `resolution` must be 2K, 4K or 8K for kling-v4-image `` | `2K`、`4K`、`8K` を指定してください。大文字・小文字は区別しません。 |
| `` `size` must be auto or one of 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 `` | ピクセル寸法ではなく `auto` または対応する比率を指定します。 |
| `kling-v4-image supports at most 10 reference images` | 参照画像は 10 枚以下にしてください。 |
| `reference image is not accessible for kling-v4-image` | 参照 URL が 403 / 404 / 410 を返しています。公開状態と有効期限を確認するか、画像を再アップロードしてください。 |
| `unsupported reference image dimensions for kling-v4-image` | 幅・高さともに 300 px 以上、比率は 2:5–5:2 にしてください。比率の範囲外も同じエラー接頭辞です。 |
| `reference image too large for kling-v4-image` | 参照画像は 1 枚あたり 30 MB 以下にしてください。圧縮して再送信してください。 |
| `` `n` must be an integer between 1 and 9 for kling-v4-image (got: "3") `` | 文字列 `"3"` ではなく、`"n": 3` のような JSON 整数を指定します。他のフィールドも指定された文字列・配列・ブール型を使用してください。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.