> ## 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 3 Image 图像生成

> 支持文生图、单图编辑和最多 10 张参考图，提供多种宽高比及最高 4k 分辨率。

<Info>
  本接口为异步接口。提交成功后返回 `task_id`，请通过 [任务查询](/cn/api-reference/tasks/status) 获取状态与图片。等待至 `completed` 或 `failed` 后停止轮询。`4k` 生成可能需要几分钟，建议将整体等待超时设为 10 分钟。
</Info>

<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-3-image",
      "prompt": "黎明时雾气笼罩的沿海公路，超宽幅电影镜头，一辆开着车灯的复古汽车",
      "aspect_ratio": "21:9",
      "resolution": "2k"
    }'
  ```

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

  response = requests.post(
      "https://api.apimart.ai/v1/images/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "flux-3-image",
          "prompt": "黎明时雾气笼罩的沿海公路，超宽幅电影镜头，一辆开着车灯的复古汽车",
          "aspect_ratio": "21:9",
          "resolution": "2k"
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "flux-3-image",
      prompt: "黎明时雾气笼罩的沿海公路，超宽幅电影镜头，一辆开着车灯的复古汽车",
      aspect_ratio: "21:9",
      resolution: "2k"
    })
  });
  console.log(await response.json());
  ```
</RequestExample>

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

## 请求头

<ParamField header="Authorization" type="string" required>
  Bearer 认证，格式为 `Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  固定为 `flux-3-image`。
</ParamField>

<ParamField body="prompt" type="string" required>
  文生图的画面描述，或图片编辑指令。不支持负面提示词，请正面描述希望生成的画面。

  支持在 `prompt` 中使用标签和 bbox JSON 指定布局或局部编辑区域，详见下方示例。
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图片列表，最多支持 10 张。支持公网可访问的 HTTP(S) URL 或 Base64 输入。

  不传时为文生图；传入一张时可进行单图编辑，传入多张时可进行多图参考。
</ParamField>

<ParamField body="aspect_ratio" type="string" default="auto">
  输出宽高比。支持：

  `21:9`、`2:1`、`16:9`、`3:2`、`7:5`、`4:3`、`5:4`、`1:1`、`4:5`、`3:4`、`5:7`、`2:3`、`9:16`、`1:2`、`9:21` 或 `auto`。

  兼容 `16x9` 形式的比例写法。使用 `auto` 时：

  * 编辑或多图参考：跟随第一张参考图的画幅。
  * 纯文生图：根据提示词决定；未确定画幅时使用 `1:1`。
</ParamField>

<ParamField body="size" type="string">
  宽高比的兼容参数，可替代 `aspect_ratio`，取值与其相同。建议只使用其中一个字段。

  不支持 `1024x1024` 等像素尺寸，传入会返回 HTTP 400。请通过 `resolution` 选择输出分辨率。
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  输出分辨率档位，支持 `768sq`、`1k`、`1.5k`、`2k`、`4k`，大小写不敏感，`768` 等同于 `768sq`。

  该参数决定计费档位。不传时按 `1k` 生成和计费；传入 `3k` 等不支持的值会返回 HTTP 400。
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  内容安全容忍度，取值为 0–4，0 最严格。
</ParamField>

<ParamField body="grounding" type="boolean" default="true">
  是否允许在生成前进行网页或图片检索。传入 `false` 可关闭。

  必须为布尔值，不能传字符串 `"false"` 或 `"true"`。
</ParamField>

<ParamField body="n" type="integer" default="1">
  每次请求生成 1 张图片，仅支持 `1`。需要多张时请分别提交任务，传入大于 1 的值会返回 HTTP 400。
</ParamField>

## 不支持的参数

以下参数传入后会返回 HTTP 400，不会静默忽略：

* `width`、`height`
* 像素尺寸形式的 `size`，例如 `1024x1024`
* `seed`、`steps`、`guidance`
* `output_format`、`negative_prompt`、`prompt_upsampling`、`mask_url`

需要更高分辨率时使用 `resolution`，需要特定画幅时使用 `aspect_ratio`。

## 编辑参考图

```json theme={null}
{
  "model": "flux-3-image",
  "prompt": "将图中的汽车改为红色，保留原有道路、背景和光照",
  "image_urls": ["https://example.com/car.jpg"],
  "aspect_ratio": "auto",
  "resolution": "2k"
}
```

请将示例 URL 替换为公网可访问的图片地址。多图参考时，在 `image_urls` 中提供多个地址，总数不超过 10 张。

## 多图参考

编辑、局部编辑和布局都使用本页同一接口及模型，按 `resolution` 计费。参考图按顺序编号：第一张为 `ref_image_0`，第二张为 `ref_image_1`；提示词中也可直接使用 `Image 1` / `Image 2`。

```json theme={null}
{
  "model": "flux-3-image",
  "prompt": "将 Image 1 转换成 Image 2 的风格。",
  "image_urls": [
    "https://example.com/subject.jpg",
    "https://example.com/style.jpg"
  ],
  "aspect_ratio": "auto"
}
```

## 局部编辑（bounding box）

先在 `prompt` 中用自然语言描述编辑指令，并使用 `<标签>` 指代元素（例如 `<car_1>`）；随后在同一个字符串中附加 JSON 数组，每个对象描述一个框。bbox 不是独立的请求参数。

| 字段 | 说明 |
| - | - |
| `id` | 与提示词中的标签对应，不包含尖括号。 |
| `from` | 元素来源，例如 `ref_image_0`；新绘制或重绘的元素使用 `null`。 |
| `src_bbox` | 元素在原图中的框；`from` 为 `null` 时，此字段也为 `null`。 |
| `tgt_bbox` | 元素在输出图中的框；与 `src_bbox` 相同表示原地保留，不同表示移动。 |
| `desc` | 描述元素需要如何修改或保持什么样。 |

所有框字段（`src_bbox`、`tgt_bbox`、`bbox`）均使用 `[上, 左, 下, 右]`，即 `[y1, x1, y2, x2]`。采用 **0–1000 归一化坐标**：左上角为 `[0,0]`，右下角为 `[1000,1000]`，不是实际像素坐标。

下面示例将框内汽车改为红色，并描述需要保留的背景。URL 和框位置仅为示例，请按实际图片替换。

```json theme={null}
{
  "model": "flux-3-image",
  "prompt": "在 <ref_image_0> 中，将汽车 <car_1> 改为红色，保留背景 <background_1>。 [{\"id\":\"car_1\",\"from\":null,\"src_bbox\":null,\"tgt_bbox\":[250,300,750,800],\"desc\":\"红色汽车，保持原有形状和朝向。\"},{\"id\":\"background_1\",\"from\":\"ref_image_0\",\"src_bbox\":[0,0,1000,1000],\"tgt_bbox\":[0,0,1000,1000],\"desc\":\"保留原有道路、背景和光照。\"}]",
  "image_urls": [
    "https://example.com/car.jpg"
  ],
  "aspect_ratio": "auto",
  "resolution": "2k"
}
```

### 移动元素

以下对象可放入提示词末尾的 bbox 数组：`from` 指定原图，`src_bbox` 是原位置，`tgt_bbox` 是新位置。自然语言指令中同时使用对应的 `<knight_1>` 标签。

```json theme={null}
{
  "id": "knight_1",
  "from": "ref_image_0",
  "src_bbox": [
    500,
    150,
    850,
    350
  ],
  "tgt_bbox": [
    194,
    55,
    544,
    255
  ],
  "desc": "一只迷你灰色钩针骑士玩偶。"
}
```

## 文生图布局

不传参考图时也可以指定布局，每个框使用 `id`、`bbox`、`desc`。请显式传入 `aspect_ratio`，坐标网格会随画幅拉伸。

```json theme={null}
{
  "model": "flux-3-image",
  "aspect_ratio": "1:1",
  "prompt": "极简插画：黑色奔跑人物剪影 <silhouette_1>，背景为纯黄绿色 <background_1>。 [{\"id\":\"background_1\",\"bbox\":[0,0,1000,1000],\"desc\":\"带有轻微纸张纹理的荧光黄绿色背景。\"},{\"id\":\"silhouette_1\",\"bbox\":[150,150,850,850],\"desc\":\"带点状纹理的黑色奔跑人物剪影。\"}]"
}
```

### 使用注意

* bbox JSON 是 `prompt` 字符串的一部分。手写请求 JSON 时，内部双引号需要转义为 `\"`；使用 SDK 或 JSON 序列化方法可自动完成转义。

* 需要保留的区域也应列出，并在 `desc` 中说明保留要求。

* 提示词中的元素标签必须与 JSON 的 `id` 一一对应；`<ref_image_0>` 等参考图标识用于指向输入图片。

* 本模型没有 `mask` 参数，也不支持 `mask_url`；传入 `mask_url` 会返回 HTTP 400。bbox 编辑不使用蒙版上传参数。

## 提交响应

<ResponseField name="code" type="integer">
  响应状态码，成功为 `200`。
</ResponseField>

<ResponseField name="data" type="array">
  任务提交结果。

  <Expandable title="显示任务字段">
    <ResponseField name="status" type="string">
      提交成功时为 `submitted`，不代表生成完成。
    </ResponseField>

    <ResponseField name="task_id" type="string">
      任务 ID，用于查询任务状态与结果。
    </ResponseField>
  </Expandable>
</ResponseField>

## 查询任务结果

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

成功响应示例（图片 URL 为占位示例）：

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.jpg"]
        }
      ]
    }
  }
}
```

从 `data.result.images[0].url` 数组读取图片链接。如果任务状态为 `failed`，请检查返回的错误信息，不要继续等待图片。

## 分辨率与计费

按张计费，单价仅由 `resolution` 决定，与宽高比、参考图张数无关，参考图不额外加价。

| 分辨率档位 | 输出规模参考 |
| - | - |
| `768sq` | 约 768×768 |
| `1k`（默认） | 约 1MP |
| `1.5k` | 约 2MP |
| `2k` | 约 4MP |
| `4k` | 约 16MP |

输出规模为近似参考，实际像素尺寸以返回图片为准。各档价格以[模型定价](https://apimart.ai/pricing)为准。

任务失败或被内容审核拦截时全额退款。

## 常见参数错误

| 请求 | 结果与处理方式 |
| - | - |
| `resolution: "3k"` | HTTP 400，改用支持的 5 种档位之一 |
| `size: "1024x1024"` | HTTP 400，使用宽高比并通过 `resolution` 选择分辨率 |
| `n: 2` | HTTP 400，每次请求只生成 1 张图片 |
| 11 张参考图 | HTTP 400，最多提供 10 张 |
| `grounding: "false"` | HTTP 400，改为布尔值 `false` |


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