# 多图参考生图

# 多图参考生图

---

## 创建任务

POST`/v1/images/multi-image2image`

cURL

```bash
curl --request POST \
  --url https://api-beijing.klingai.com/v1/images/multi-image2image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v2-1",
    "prompt": "身着飘逸红色连衣裙,在草原上，吉卜力风格。",
    "negative_prompt": "",
    "subject_image_list": [\
      { "subject_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png" },\
      { "subject_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png" }\
    ],
    "scene_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/background.jpeg",
    "style_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/16x9_jipuli.png",
    "n": 2,
    "aspect_ratio": "9:16"
  }'
```

200

```json
{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", // 任务ID，系统生成
    "task_info": { //任务创建时的参数信息
      "external_task_id": "string" //客户自定义任务ID
    },
    "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}
```

基于多张参考图片（主体、场景、风格）生成图像。

### 请求头

Content-Typestring必填默认值 application/json

数据交换格式

Authorizationstring必填

鉴权信息，参考接口鉴权

### 请求体

model_namestring可选默认值 kling-v2

模型名称

枚举值：kling-v2kling-v2-1

promptstring可选

正向文本提示词

- 不能超过 2500 个字符

subject_image_listarray必填

主体参考图片列表

- 最多支持 4 张图片，最少支持 1 张图片，用 key:value 承载，如下：

```json
"subject_image_list":[\
  { "subject_image":"image_url" },\
  { "subject_image":"image_url" },\
  { "subject_image":"image_url" },\
  { "subject_image":"image_url" }\
]
```

- API 端无裁剪逻辑，请直接上传已选主体后的图片

- 支持传入图片 Base64 编码或图片 URL（确保可访问）

- 注意：若您使用 Base64 方式，请不要在 Base64 编码字符串前添加任何前缀（如 `data:image/png;base64,`），直接传递 Base64 编码后的字符串即可。

- **正确的 Base64 编码参数：**

```plaintext
iVBORw0KGgoAAAANSUhEUgAAAAUA...
```

- 错误的 Base64 编码参数（包含 data: 前缀）：

```plaintext
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
```

- 图片格式支持 .jpg / .jpeg / .png

- 图片文件大小不能超过 10MB，图片宽高尺寸不小于 300px，图片宽高比要在 1:2.5 ~ 2.5:1 之间

### 请求参数

| 参数 | 说明 |
| ---- | ---- |
| model_name | 模型名称，包括 kling-v2, kling-v2-1 |
| prompt | 正向文本提示词 |
| subject_image_list | 主体参考图片列表，1-4张 |
| scene_image | 场景参考图 |
| style_image | 风格参考图 |
| n | 生成数量，范围 1-9 |
| aspect_ratio | 生成图片的纵横比 |

* * *

## 查询任务（单个）

GET`/v1/images/multi-image2image/{id}`

cURL

```bash
curl --request GET \
  --url https://api-beijing.klingai.com/v1/images/multi-image2image/{id} \
  --header 'Authorization: Bearer <token>'
```

200

```json
{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", // 任务ID，系统生成
    "task_info": { //任务创建时的参数信息
      "external_task_id": "string" //客户自定义任务ID
    },
    "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "task_status_msg": "string", // 任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "watermark_info": { "enabled": boolean },
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708, // 任务更新时间，Unix时间戳、单位ms
    "task_result": {
      "images": [\
        {\
          "index": 0, // 图片编号，0-9\
          "url": "string", // 生成图片的URL，例如：...\
          "watermark_url": "string" // 含水印图片下载URL，防盗链格式\
        }\
      ]\
    }
  }
}
```

### 查询任务（列表）

GET`/v1/images/multi-image2image`

cURL

```bash
curl --request GET \
  --url 'https://api-beijing.klingai.com/v1/images/multi-image2image?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
```

200

```json
{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": [\
    {\
      "task_id": "string", // 任务ID，系统生成\
      "task_info": { //任务创建时的参数信息\
        "external_task_id": "string" //客户自定义任务ID\
      },\
      "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）\
      "task_status_msg": "string", // 任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）\
      "final_unit_deduction": "string", // 任务最终扣减积分数值\
      "watermark_info": {\
        "enabled": boolean\
      },\
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms\
      "updated_at": 1722769557708, // 任务更新时间，Unix时间戳、单位ms\
      "task_result": {\
        "images": [\
          {\
            "index": 0, // 图片编号，0-9\
            "url": "string", // 生成图片的URL，例如：...\
            "watermark_url": "string" // 含水印图片下载URL，防盗链格式\
          }\
        ]\
      }\
    }\
  ]
}
```

### 请求头

Content-Typestring必填默认值 application/json

数据交换格式

Authorizationstring必填

鉴权信息，参考接口鉴权

### 查询参数

| 参数 | 说明 |
| ---- | ---- |
| pageNum | 页码，范围 [1, 1000] |
| pageSize | 每页数据量，范围 [1, 500] |