> ## 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 Long Image 長尺画像生成

> 商品詳細ページやウェブページデザインの縦長画像を 1K / 2K で生成。電商の short / medium / long と商品・スタイル・被写体の参照画像に対応し、毎回 1 枚の 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-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": true
}'
```

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

payload = {
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "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-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "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_long_image"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": "invalid_request_error",
    "message": "reference image is not accessible for kling-v4-long-image: image_urls[0] returned HTTP 404; make sure the URL is public and still valid",
    "param": "",
    "type": "invalid_request_error"
  }
}
```

`model: "kling-v4-long-image"` を指定して `POST /v1/images/generations` に非同期タスクを送信します。`data[0].task_id` を取得し、`GET /v1/tasks/{task_id}` で結果を確認します。毎回 1 枚の縦長 PNG を返し、ウェブページモードではページデザイン画像を生成します。

## モード選択

| モード | `skill` | 参照画像 | 長さ |
| - | - | - | - |
| 商品詳細ページ | `ecommerce` | `image_urls`：商品画像 1–3 枚が必須 | `short` / `medium` / `long` |
| ウェブページデザイン | `webpage` | `image_with_roles`：スタイルと被写体を各最大 1 枚、省略可 | `length` は省略 |

## 認証

**Authorization** `string` *required*

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

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

**model** `string` *required*

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

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

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

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

**prompt** `string` *required*

必須で、空白のみは不可。英語のみの場合は最大 166,000 文字、中国語などのみの場合は最大 71,000 文字。混在する場合は比率に応じて計算します。レイアウト、セクション、文言、スタイル、被写体を記述できます。

**skill** `string` *required*

必須。`ecommerce`（商品詳細ページ）または `webpage`（ウェブページデザイン）を指定し、大文字・小文字は区別しません。参照画像のフィールドはモードごとに異なります。

**length** `string` (default: medium)

`skill: "ecommerce"` 専用。`short`、`medium`（デフォルト）、`long` は、おおよそ 2–5、6–10、11–18 セクションに対応します。実際の内容と高さは生成結果によります。ウェブページモードでは省略してください。指定すると HTTP 400 になります。

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

`1K`（デフォルト）と `2K` に対応し、大文字・小文字は区別しません。商品ページはすべての長さで両方を利用でき、`long + 2K` も対応します。出力幅はそれぞれ 1024 px と 2048 px、高さは内容に応じて変わります。`4K` は非対応です。

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

商品ページ専用で、商品画像 1–3 枚が必須。ウェブページでは省略し、`image_with_roles` を使用してください。公開アクセス可能な画像の直接 URL を指定します。ローカルファイルは[画像アップロード API](https://docs.apimart.ai/ja/api-reference/uploads/images.md)でアップロードし、返された `url` を指定できます。

**image\_with\_roles** `object[]`

ウェブページ専用で省略可能。`style` と `subject` は各最大 1 枚で、片方または両方を省略できます。商品ページではこのフィールドを省略してください。

**配列要素**

**url** `string` *required*

公開アクセス可能な参照画像の直接 URL。

**role** `string` *required*

`style` は見た目とレイアウトの参考、`subject` は維持する被写体を指定します。同じ役割は 1 回のみ指定できます。

**n** `integer`

毎回 1 枚の縦長画像を生成します。省略または整数 `1` のみ指定でき、その他の値は HTTP 400 になります。

**watermark** `boolean`

省略または `false` を指定できます。`true` は HTTP 400 になります。

> [!WARNING]
>
> `size`、`aspect_ratio`、`width`、`height`、`mask_url`、`sequential_image_generation`、`sequential_image_generation_options` は指定できません。`null` や空文字列でも HTTP 400 になります。

## 参照画像の要件と指定方法

JPG / JPEG / PNG に対応。1 枚あたり 30 MB 以下、幅・高さともに 300 px 以上、比率は 2:5–5:2。URL が HTTP 403 / 404 / 410 を返す、寸法・比率が不適切、または容量超過の場合は同期的に HTTP 400 を返し、タスク作成も生成課金も行いません。配信元のタイムアウトなどは一旦受理後にタスクが失敗し、事前引き落とし分が返金されます。

プロンプトでは `@Image1`、`@Image2` などを使用できます。商品ページは `image_urls` の順、ウェブページはスタイル、被写体の順です。片方のみ指定した場合は `@Image1` です。

## リクエスト例

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

### 商品ページ：long + 2K

```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-long-image",
  "skill": "ecommerce",
  "prompt": "Create a long product detail page using the front view in @Image1, side view in @Image2, and close-up in @Image3. Include key features, materials, use scenes, and care instructions.",
  "image_urls": [
    "https://example.com/product-front.jpg",
    "https://example.com/product-side.jpg",
    "https://example.com/product-detail.png"
  ],
  "length": "long",
  "resolution": "2K"
}'
```

### スタイルと被写体を参照したウェブページ

```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-long-image",
  "skill": "webpage",
  "prompt": "Design a product landing page using the visual style of @Image1 and preserving the product in @Image2. Include a hero section, features, and a call to action.",
  "image_with_roles": [
    {
      "url": "https://example.com/style.png",
      "role": "style"
    },
    {
      "url": "https://example.com/product.jpg",
      "role": "subject"
    }
  ],
  "resolution": "2K"
}'
```

### プロンプトのみでウェブページを生成

```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-long-image",
  "skill": "webpage",
  "prompt": "Design a welcoming coffee shop webpage with warm colors, a hero section, a menu, and store information",
  "resolution": "1K"
}'
```

## タスクの確認

[タスク照会 API](https://docs.apimart.ai/ja/api-reference/tasks/status.md) を約 10 秒間隔で確認します。`task_id` を保存し、待ち時間が長くても生成リクエストを重複送信しないでください。

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

| 状態 (`data.status`) | 処理方法 |
| - | - |
| `pending` / `processing` | 照会を続けます。`data.cost` は事前引き落とし額、`data.billing_status` は `held` です。 |
| `completed` | `data.result.images[0].url[0]` を取得します。`data.billing_status` は `settled`、`data.cost` は確定額です。 |
| `failed` | `data.error.message` を確認します。`data.billing_status` は `refunded`、`data.cost` は `0` となり、事前引き落とし額は全額返金されます。 |

以下は成功結果の構造例です。`images` と `url` は配列で、このモデルは毎回 1 枚の縦長画像を返します。

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_long_image",
    "status": "completed",
    "progress": 100,
    "billing_status": "settled",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-long-image.png"
          ],
          "expires_at": 1795331293
        }
      ]
    }
  }
}
```

`data.result.images[0].expires_at` の Unix 秒タイムスタンプまでにダウンロードしてください。それ以降はリンクが失効します。

> [!NOTE]
>
> 生成には通常数分かかり、`long + 2K` の実測例は 432 秒でした。`estimated_time` は現在 60 秒固定のため、完了までのカウントダウンやタイムアウト判定に使用しないでください。所要時間は内容と負荷で変わり、実測例は上限ではありません。
>
> 高さとファイル容量は内容に応じて変わります。`long + 2K` の一例は `2048×46615`、63.9 MB でした。これは出力上限ではありません。結果が 50 MB を超える場合もあるため、ダウンロードと大きな画像の表示に配慮してください。

## 料金

毎回、選択した出力区分の長尺画像 1 枚分と参照画像分を課金します。**出力区分の単価 + 参照枚数 × 参照画像単価**。商品・スタイル・被写体の画像はすべて対象で、最初の参照画像も課金されます。

出力は以下の 8 区分です。料金キーは `kling-v4-long-image@<区分>`、参照画像は `kling-v4-long-image@input` です。生成リクエストの `resolution` には引き続き `1K` または `2K` のみ指定します。

| モード | 長さ | `1K` | `2K` |
| - | - | - | - |
| 商品詳細ページ | `short` | `1K-SHORT` | `2K-SHORT` |
| 商品詳細ページ | `medium` | `1K-MEDIUM` | `2K-MEDIUM` |
| 商品詳細ページ | `long` | `1K-LONG` | `2K-LONG` |
| ウェブページデザイン | `length` は省略 | `1K-WEBPAGE` | `2K-WEBPAGE` |

送信時に事前引き落とし、成功時に確定し、失敗時は全額返金します。単価とアカウント割引は[料金ページ](https://apimart.ai/pricing)をご確認ください。

## よくあるエラー

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

| エラー抜粋 | 対処方法 |
| - | - |
| `` `prompt` is required for kling-v4-long-image `` | 空でないプロンプトを指定します。 |
| `` `skill` is required for kling-v4-long-image `` | `skill` を指定します。 |
| `` `skill` must be ecommerce or webpage for kling-v4-long-image `` | `ecommerce` または `webpage` を使用します。 |
| `` skill=ecommerce on kling-v4-long-image requires 1 to 3 product images in `image_urls` `` | 商品画像を 1–3 枚指定します。 |
| `` skill=ecommerce on kling-v4-long-image supports at most 3 product images in `image_urls` `` | 商品画像は最大 3 枚です。 |
| `` `image_with_roles` is only for skill=webpage on kling-v4-long-image `` | 商品ページでは `image_urls` を使い、`image_with_roles` を省略します。 |
| `` `length` must be short, medium or long for kling-v4-long-image `` | 長さは `short`、`medium`、`long` です。 |
| `` `length` only applies to skill=ecommerce for kling-v4-long-image `` | ウェブページでは `length` を省略します。 |
| `` skill=webpage on kling-v4-long-image does not take `image_urls` `` | ウェブページでは `image_urls` を省略し、`image_with_roles` を使います。 |
| `` `image_with_roles[0].role` must be style or subject for kling-v4-long-image `` | `style` または `subject` のみ使用します。 |
| `kling-v4-long-image supports at most 1 image with role style` | 各役割は最大 1 枚です。被写体の重複も不可です。 |
| `` `resolution` must be 1K or 2K for kling-v4-long-image `` | `1K` または `2K` を指定します。 |
| `` `size` is not supported by kling-v4-long-image `` | 非対応の寸法・比率・シリーズのフィールドを削除します。`null` や空文字列も不可です。 |
| `` `n` is not supported by kling-v4-long-image: each request returns one long image `` | `n` を省略または整数 `1` にします。 |
| `reference image is not accessible for kling-v4-long-image` | 公開アクセスと URL の有効性、403 / 404 / 410 を確認します。 |
| `unsupported reference image dimensions for kling-v4-long-image` | 幅・高さともに 300 px 以上、比率は 2:5–5:2 にします。 |
| `reference image too large for kling-v4-long-image` | 参照画像は各 30 MB 以下です。 |


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