> ## 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–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"
  }
}
```

使用 `kling-v4-image` 调用 `POST /v1/images/generations` 异步提交任务，从 `data[0].task_id` 获取任务 ID，再通过 `GET /v1/tasks/{task_id}` 查询结果。

## 认证

**Authorization** `string` *required*

使用 `Authorization: Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。

## 请求参数

**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[]`

最多 10 张参考图，使用公网可访问的图片直链。本地文件可先通过[图片上传接口](https://docs.apimart.ai/cn/api-reference/uploads/images.md)上传，再传返回的 `url`。

支持 JPG / JPEG / PNG / GIF，单张不超过 30 MB，宽、高均至少 300 px，宽高比在 2:5–5:2 之间。

提交时会检查参考图：链接返回 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 张参考图。参考图的格式、尺寸和单张 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`。请将示例图片地址替换为实际可访问的直链。

### 图生图

```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"
}'
```

### 一次生成 3 张 4K 图片

```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 图片

```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
}'
```

### 生成 4 张 8K 关联组图

组图使用 `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 张（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 分钟 |

建议每 5–10 秒查询一次任务，直到 `completed` 或 `failed`。`estimated_time` 固定返回 60 秒，不能用作实际完成时间或倒计时；请保留 `task_id`，避免因等待较久而重复提交。

8K 返回 PNG 原图，单张文件可能超过 100 MB。列表或预览建议使用自行生成的缩略图，或按需懒加载；提供原图下载入口，并提醒用户文件较大。

## 查询任务

通过[任务查询接口](https://docs.apimart.ai/cn/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>'
```

以下为成功结果的结构示意。图片地址位于 `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"
          ]
        }
      ]
    }
  }
}
```

## 计费

按实际生成张数和所选分辨率档位计费，参考图另外按张计费。具体单价以[价格页](https://apimart.ai/pricing)为准。

| 计费项目 | 价格项 |
| - | - |
| 每张 2K 输出图片 | `kling-v4-image@2K` |
| 每张 4K 输出图片 | `kling-v4-image@4K` |
| 每张 8K 输出图片 | `kling-v4-image@8K` |
| 每张输入参考图 | `kling-v4-image@input` |

* 普通生成 `n=3` 按 3 张输出计费；组图按实际返回张数计费。
* 每张参考图在每次请求中只计算一次，不随输出张数翻倍。例如 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 `` | `max_images` 使用 2–4 的整数，不传 `"auto"`。 |
| `` `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` | 参考图链接返回 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` | 单张参考图不得超过 30 MB；压缩后重新提交。 |
| `` `n` must be an integer between 1 and 9 for kling-v4-image (got: "3") `` | 使用 JSON 整数，如 `"n": 3`，不要传字符串 `"3"`；其他字段也须使用声明的字符串、数组或布尔类型。 |


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