> ## 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.

# Flux Kontext 图像生成

>  - 异步处理模式，返回任务ID用于后续查询
- Pro 和 Max 均支持文本生成图片与参考图编辑
- 生成结果中的 expires_at 表示图片链接的过期时间 

<RequestExample>
  ```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": "flux-kontext-pro",
      "prompt": "把头发变成蓝色",
      "image_urls": ["https://example.com/portrait.jpg"],
      "size": "16:9",
      "output_format": "png"
    }'
  ```

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

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "flux-kontext-pro",
      "prompt": "把头发变成蓝色",
      "image_urls": ["https://example.com/portrait.jpg"],
      "size": "16:9",
      "output_format": "png"
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "flux-kontext-pro",
    prompt: "把头发变成蓝色",
    image_urls: ["https://example.com/portrait.jpg"],
    size: "16:9",
    output_format: "png"
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "身份验证失败，请检查您的API密钥",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "账户余额不足，请充值后再试",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## 支持的模型

| 模型名                | 说明                            |
| ------------------ | ----------------------------- |
| `flux-kontext-pro` | Flux Kontext Pro 图像生成与编辑模型    |
| `flux-kontext-max` | Flux Kontext Max 高质量图像生成与编辑模型 |

## Authorizations

<ParamField header="Authorization" type="string" required>
  所有接口均需要使用Bearer Token进行认证

  获取 API Key：

  访问 [API Key 管理页面](https://apimart.ai/keys) 获取您的 API Key

  使用时在请求头中添加：

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  模型名称

  * `flux-kontext-pro` - Kontext Pro 图像生成与编辑模型
  * `flux-kontext-max` - Kontext Max 高质量图像生成与编辑模型
</ParamField>

<ParamField body="prompt" type="string" required>
  图像生成或编辑的文本描述。
</ParamField>

<ParamField body="image_urls" type="array">
  参考图片列表。不传时为文生图，传入时为图片编辑。

  **限制：**

  * 最多支持 4 张图片
  * 支持公网可访问的 URL 或 Base64 输入
  * 输出图像与所有参考图的总像素不得超过 9MP

  如果参考图 URL 无法公开访问，任务可能只返回 `temporarily unavailable dependency`。遇到该提示时，请优先检查防盗链、访问权限和签名是否过期。
</ParamField>

<ParamField body="size" type="string" default="1:1">
  图像宽高比。也可以传入像素串，例如 `1024x1536`；Kontext 会将其映射到最接近的支持比例，不保证精确输出该像素尺寸。

  支持的宽高比：

  * `1:1` - 正方形（默认）
  * `4:3` - 横向 4:3
  * `3:4` - 纵向 3:4
  * `16:9` - 横向宽屏
  * `9:16` - 纵向竖屏
  * `3:2` - 横向 3:2
  * `2:3` - 纵向 2:3
  * `21:9` - 超宽屏
  * `9:21` - 超竖屏
</ParamField>

Kontext 不支持 `width` 或 `height`，传入任一字段都会导致任务失败；请使用 `size` 控制宽高比。`resolution` 对 Kontext 不生效，输出恒定在约 1MP。

<ParamField body="output_format" type="string" default="png">
  输出图片的编码格式

  * `png` - PNG 格式（默认）
  * `jpeg` - JPEG 格式
  * `webp` - WebP 格式
</ParamField>

<ParamField body="response_format" type="string">
  OpenAI 兼容响应形态字段，仅支持 `url` 或 `b64_json`。它不会改变图片编码；同时传入时，以 `output_format` 为准。
</ParamField>

<ParamField body="n" type="integer" default="1">
  每次生成的图片张数。仅允许传入 `1`；需要多张图片时，请并发提交多个任务。
</ParamField>

<ParamField body="seed" type="integer">
  随机种子。固定种子并保持其他参数一致时，可以复现相同结果；不传时随机生成。
</ParamField>

<ParamField body="prompt_upsampling" type="boolean" default="false">
  是否启用提示词增强

  * `true` - 启用
  * `false` - 禁用（默认）

  > 显式设置为 `false` 可关闭提示词改写。
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  安全容忍度

  取值范围：0-6，数值越高越宽松
</ParamField>

### 实际输出尺寸

| 比例     | 实际输出尺寸    |
| ------ | --------- |
| `1:1`  | 1024×1024 |
| `4:3`  | 1184×880  |
| `3:4`  | 880×1184  |
| `16:9` | 1392×752  |
| `9:16` | 752×1392  |
| `3:2`  | 1248×832  |
| `2:3`  | 832×1248  |
| `21:9` | 1568×672  |
| `9:21` | 672×1568  |

## 使用场景示例

**图片编辑（带输入图片）**

```json theme={null}
{
    "model": "flux-kontext-pro",
    "prompt": "把背景换成海滩",
    "image_urls": ["https://example.com/photo.jpg"],
    "size": "16:9",
    "output_format": "png"
}
```

**纯文生图（无输入图片）**

```json theme={null}
{
    "model": "flux-kontext-max",
    "prompt": "一只蓝色的猫",
    "size": "1:1",
    "seed": 12345
}
```

**多参考图编辑**

```json theme={null}
{
    "model": "flux-kontext-max",
    "prompt": "把图一的人物放进图二的场景，并统一光照",
    "image_urls": [
        "https://example.com/person.jpg",
        "https://example.com/scene.jpg"
    ],
    "size": "4:3"
}
```

## Response

<ResponseField name="code" type="integer">
  响应状态码
</ResponseField>

<ResponseField name="data" type="array">
  返回数据数组

  <Expandable title="属性">
    <ResponseField name="status" type="string">
      任务状态

      * `submitted` - 已提交
    </ResponseField>

    <ResponseField name="task_id" type="string">
      任务唯一标识符，用于后续查询任务结果
    </ResponseField>
  </Expandable>
</ResponseField>

## 查询任务结果

提交成功后，通过 `GET /v1/tasks/{task_id}` 轮询任务状态，详见 [任务查询接口](/cn/api-reference/tasks/status)。

### 成功响应示例

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "created": 1785133674,
    "completed": 1785133683,
    "actual_time": 9,
    "estimated_time": 15,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-flux-kontext.png"
          ],
          "expires_at": 1785220083
        }
      ]
    }
  }
}
```

取图路径：`data.result.images[0].url[0]`。`expires_at` 是该链接的 Unix 过期时间戳，请在过期前保存图片。

### 任务状态

| 状态                      | 含义                                     |
| ----------------------- | -------------------------------------- |
| `submitted` / `pending` | 任务已受理或正在排队，继续轮询                        |
| `processing`            | 生成中，继续轮询                               |
| `completed`             | 生成成功，结果位于 `result.images`              |
| `failed`                | 生成失败，查看 `data.error.message`；任务费用会全额退还 |

### 参数错误与失败响应

模型参数无效时，提交接口仍会返回 HTTP 200 和 `task_id`。请持续轮询，任务随后会进入 `failed` 状态，并在 `data.error.message` 中返回具体原因。失败任务会全额退款。

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "width/height are not supported by flux-kontext-pro"
    }
  }
}
```

`error.code` 固定为 `task_failed`，具体失败原因请读取 `error.message`。

## 注意事项

1. **异步处理**：提交后返回 `task_id`，需要轮询 `/v1/tasks/{task_id}` 获取结果。
2. **参考图要求**：最多支持 4 张参考图，可使用公网可访问的图片 URL 或 Base64 输入；输出与全部参考图合计不得超过 9MP。
3. **尺寸规则**：默认比例为 `1:1`。`width` / `height` 会导致任务失败，`resolution` 不改变约 1MP 的输出，像素格式的 `size` 会映射到最接近的支持比例。
4. **生成张数**：`n` 默认且只能为 `1`。
5. **提示词改写**：显式设置 `prompt_upsampling: false` 可关闭提示词改写。
6. **结果链接**：图片 URL 的有效期以对应的 `expires_at` Unix 时间戳为准，请及时保存。
7. **异步参数错误**：非法模型参数不会在提交时同步返回 4xx；必须轮询到 `failed` 并读取 `data.error.message`。