> ## 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，以及商品图、风格图和主体图参考。每次返回一张 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"
  }
}
```

使用 `kling-v4-long-image` 调用 `POST /v1/images/generations` 异步提交任务，从 `data[0].task_id` 获取任务 ID，再查询 `GET /v1/tasks/{task_id}`。每次输出一张 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 Key。

## 请求参数

**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`。传入公网可访问的图片直链；本地文件可先使用[图片上传接口](https://docs.apimart.ai/cn/api-reference/uploads/images.md)，再传返回的 `url`。

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

仅用于网页模式，可省略。`style` 和 `subject` 各最多 1 张，可只传其中一种，也可都不传。电商模式必须省略此字段。

**数组元素**

**url** `string` *required*

公网可访问的参考图片直链。

**role** `string` *required*

`style` 表示视觉和布局风格参考；`subject` 表示需要保留的主体。同一角色不能出现两次。

**n** `integer`

每次只生成一张长图。可以省略或传整数 `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，单张不超过 30 MB，宽、高均至少 300 px，宽高比在 2:5–5:2 之间。链接返回 HTTP 403 / 404 / 410、尺寸或比例不符、文件超限时，同步返回 HTTP 400，不创建任务、不扣生成费用。源站超时等其他取图失败会先受理，随后任务失败并退回预扣费用。

提示词中可用 `@Image1`、`@Image2` 等引用参考图。电商模式按 `image_urls` 顺序编号；网页模式按“风格图、主体图”顺序编号，只传其中一张时就是 `@Image1`。

## 请求示例

以下请求均发送到 `POST /v1/images/generations`。请将示例图片地址替换为实际可访问的直链。

### 电商长页：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"
}'
```

## 查询任务

通过[任务查询接口](https://docs.apimart.ai/cn/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` 都是数组，本模型每次返回一张长图。

```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，请考虑下载和展示大图的开销。

## 计费

每次请求按所选输出档位收取一张长图费用，另加参考图费用：**输出档位单价 + 参考图张数 × 参考图单价**。商品图、风格图、主体图均计费，首张参考图也收费。

输出共有以下 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` | 确认参考图直链公开、有效，排查 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.