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

# GPT-Image-2.6 图像生成

> 使用 Flare 与 Sunburst 异步生成和编辑图片，支持标注引导、GIF 动图与 SVG 矢量图。

文生图、图生图、GIF 和 SVG 均调用 `POST /v1/images/generations`。提交后读取 `data[0].task_id`，再查询任务获取文件链接。

```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": "gpt-image-2.6-flare",
  "prompt": "A cozy reading nook by a rainy window, warm lamp light",
  "size": "1:1",
  "resolution": "1k",
  "quality": "medium",
  "n": 1
}'
```

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

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "gpt-image-2.6-flare",
        "prompt": "A cozy reading nook by a rainy window, warm lamp light",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1
    },
)
response.raise_for_status()
print(response.json()["data"][0]["task_id"])
```

```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": "gpt-image-2.6-flare",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result.data[0].task_id);
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

## 认证

**Authorization** `string` *required*

使用 Bearer Token 认证，在 [API Key 管理页面](https://apimart.ai/keys) 获取密钥。

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## 模型选择

| 模型 | 适用场景 |
| - | - |
| `gpt-image-2.6-flare` | 速度优先，适合快速迭代，建议作为默认选择。 |
| `gpt-image-2.6-sunburst` | 细节与编辑一致性优先，尤其适合 `medium` / `high` 下的多轮编辑。 |

两者的 token 单价与相同参数下的消耗一致，按速度和细节需求选择。

## 请求参数

**model** `string` *required*

模型名称：`gpt-image-2.6-flare` 或 `gpt-image-2.6-sunburst`。

**prompt** `string` *required*

生成或编辑描述，最多 32,000 字符。说明主体、构图，以及需要修改和保留的内容。

**size** `string` (default: auto)

静态图片与 SVG 支持 15 种比例、精确像素（如 `1600x1200`）或 `auto`。显式传 `auto` 时由上游决定尺寸；图生图省略此字段时，根据第一张输入图的比例与 `resolution` 选尺寸。GIF 的尺寸规则见下文。

**resolution** `string` (default: 1k)

`1k` / `2k` / `4k`，使用小写。与比例形式的 `size` 配合决定像素；传精确像素尺寸时忽略此字段。

**quality** `string` (default: auto)

`low` / `medium` / `high` / `xhigh` / `max` / `auto`。其他值会在提交时直接返回 HTTP 400。省略或传 `auto` 时，由模型自动选择质量档位，实际档位可能变化，并不固定为 `low`；需要固定档位时请显式指定。

省略或传 `auto` 时，费用按 `max` 档预留，最终按实际选中的质量档位结算。

**n** `integer` (default: 1)

整数 `1`–`4`；GIF 表示动图数量。SVG 只能为 `1`。显式传 `0`、负数或大于 `4` 的值会直接返回 HTTP 400，不会替换为默认值。

**output\_format** `string` (default: png)

`png` / `jpeg` / `webp` / `gif` / `svg`。GIF 和 SVG 只支持文生图。其他值会在提交时直接返回 HTTP 400。

**output\_compression** `integer`

整数 `0`–`100`，仅适用于 `jpeg` / `webp`。超出范围，或搭配 `png` / `gif` / `svg`，会在提交时直接返回 HTTP 400。

**background** `string`

`transparent` / `opaque` / `auto`；省略使用上游默认值。显式传 `transparent` 只能搭配 `png` / `webp`。SVG 默认背景透明，无需传此字段。

**moderation** `string` (default: low)

内容审核强度：`auto` / `low`。其他值会在提交时直接返回 HTTP 400。

**image\_urls** `string[]`

最多 16 张参考图，传入后进入图生图模式。使用公网可访问的 HTTP(S) 图片直链；本地文件可先调用 [图片上传接口](https://docs.apimart.ai/cn/api-reference/uploads/images.md)，再传返回的 `url`。

**mask\_url** `string`

局部重绘蒙版，需要同时传 `image_urls`。使用带 Alpha 通道的 PNG，宽高与第一张输入图一致；完全透明区域表示需要修改。支持图片直链或 PNG Data URL。不能与标注层同时使用，模型不保证蒙版外像素完全不变。

**complexity** `string`

规划强度：`low` / `medium` / `high`，上游默认 `high`，独立于渲染质量 `quality`。局部小改动可用 `low`；密集文字、复杂版式或物体关系可用 `high`，但可能更慢或引入额外改动。此参数不单独收费，仅 2.6 支持。

**safety\_identifier** `string`

可选的终端用户稳定标识，最多 128 字符，建议使用用户名或邮箱的哈希。APIMart 默认不向上游转发，仅在渠道允许时转发；省略不影响使用。

## 静态图片与 SVG 尺寸

精确像素尺寸必须满足：宽高均为 16 的倍数、单边不超过 3840、长短边之比不超过 3:1、总像素为 655,360–8,294,400。高于 2560×1440 属实验性范围。以下映射与 GPT-Image-2.5 相同；这些静态图片限制不能直接套用到 GIF 的单帧尺寸。

| `size` | `1k` | `2k` | `4k` |
| - | - | - | - |
| `1:1` | 1024×1024 | 2048×2048 | 2880×2880 |
| `3:2` | 1536×1024 | 2048×1360 | 3520×2336 |
| `2:3` | 1024×1536 | 1360×2048 | 2336×3520 |
| `4:3` | 1024×768 | 2048×1536 | 3312×2480 |
| `3:4` | 768×1024 | 1536×2048 | 2480×3312 |
| `5:4` | 1280×1024 | 2560×2048 | 3216×2576 |
| `4:5` | 1024×1280 | 2048×2560 | 2576×3216 |
| `16:9` | 1536×864 | 2048×1152 | 3840×2160 |
| `9:16` | 864×1536 | 1152×2048 | 2160×3840 |
| `2:1` | 2048×1024 | 2688×1344 | 3840×1920 |
| `1:2` | 1024×2048 | 1344×2688 | 1920×3840 |
| `21:9` | 2016×864 | 2688×1152 | 3840×1648 |
| `9:21` | 864×2016 | 1152×2688 | 1648×3840 |
| `3:1` | 1536×512 | 3072×1024 | 3840×1280 |
| `1:3` | 512×1536 | 1024×3072 | 1280×3840 |

## 图生图与蒙版

以下请求对第一张图进行局部编辑。省略 `mask_url` 可按提示词编辑整张图；省略 `size` 则根据首张图比例和 `resolution` 选择输出尺寸。示例中的图片链接需替换为可访问的实际文件。

```json theme={null}
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "Replace the fully transparent masked area with a gold ribbon. Preserve the product and the rest of the background.",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "resolution": "2k",
  "quality": "high",
  "complexity": "low"
}
```

## 标注引导编辑

传 `markup_url`（HTTPS 或 Base64 Data URL），也可用别名 `markup`：字符串或 `{"image_url":"..."}` 对象。不支持 `file_id`。

* 必须同时传 `image_urls`；标注作用于第一张图，其余图片作为参考。
* 标注必须是单独的透明 PNG 图层，宽高与第一张图完全一致，不要将标注合并到原图。
* 第一张图与标注层各自不超过 16,777,216 像素，标注文件不超过 50 MB。
* 不能与 `mask_url` 同时传。标注层不计图片 token，但请求仍可能产生额外文本 token。

```json theme={null}
{
  "model": "gpt-image-2.6-flare",
  "prompt": "Recolor the striped vase inside the red circle to solid cobalt blue ceramic. Keep everything else unchanged. Remove the red circle.",
  "image_urls": [
    "https://example.com/kitchen.webp"
  ],
  "markup_url": "https://example.com/vase-circle-overlay.png",
  "quality": "medium"
}
```

## GIF 动图

设置 `output_format: "gif"`，仅支持文生图。不要传 `image_urls`、`mask_url`、`markup_url`、`markup` 或 `output_compression`。

| 参数 | 默认 | 说明 |
| - | - | - |
| `frame_count` | `9` | 整数 **2–16**。APIMart 当前以 16 为上限，不适用上游指南中的 64 帧上限。 |
| `frame_duration_ms` | `200` | 每帧时长，整数毫秒，最小 20，按 10 ms 取整。 |
| `size` | `auto` | **单帧**像素尺寸，宽高为 16 的倍数；省略或传 `auto` 时当前为 512×512。不能传 `1:1` 等比例名。 |

上游先将帧排入一张拼图：2–8 帧使用 4×2，9 帧使用 3×3，10–12 帧使用 4×3，13–16 帧使用 4×4；行列可互换，取更接近方形的布局。整张拼图必须满足单边不超过 3840、总像素不超过 8,294,400、长短边之比不超过 3:1，否则提交返回 400。

> [!WARNING]
>
> `512x512` 可用于全部 2–16 帧；`768x768` 最多 12 帧。`1024x1024` 即使只有 2 帧也会超出拼图单边上限。每段动图按整张拼图计费，`n > 1` 会生成并计费多段动图。

```json theme={null}
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A paper lantern swaying gently in the night breeze, seamless loop",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "quality": "low"
}
```

## SVG 矢量图

**svg** `object`

设置 `output_format: "svg"`。图像模型先生成参考图，再由 `svg.model` 指定的文本模型编写 SVG。

**svg**

**model** `string` *required*

必填；选择平台有文本 token 定价的模型，例如 `gpt-5.4-mini` 或 `gpt-5.6-sol`。

**reasoning** `object`

**reasoning**

**effort** `string`

可选：`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`。具体支持的值取决于文本模型，建议省略以使用该模型默认值。

* 仅文生图且 `n` 必须为 1；不能传参考图、蒙版、标注层或 `output_compression`。
* `quality` 和 `complexity` 作用于中间参考图。结果为静态 `.svg`，不含脚本、外部资源或内嵌位图。
* 除了图片生成费用，还会按 `svg.model` 的文本用量计费。按张固定价合约账号暂不支持 SVG，提交会返回 400。

```json theme={null}
{
  "model": "gpt-image-2.6-flare",
  "prompt": "A minimalist bakery logo with a wheat stalk, flat colors",
  "output_format": "svg",
  "svg": {
    "model": "gpt-5.4-mini"
  },
  "size": "1:1",
  "quality": "low",
  "n": 1
}
```

## 查询任务结果

使用 [任务查询接口](https://docs.apimart.ai/cn/api-reference/tasks/status.md)，建议每 2–5 秒查询一次，直到 `completed` 或 `failed`。不要重复提交生成请求来等待结果。

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

完成后从 `data.result.images[].url[]` 读取文件链接，及时下载保存。下面仅展示主要响应字段；`failed` 时查看 `data.error.message`。多个任务可使用 `POST /v1/tasks/batch` 批量查询。

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example.png"
          ]
        }
      ]
    }
  }
}
```

### SVG 用量与响应示例

任务查询响应中的 `data.usage.svg_usage` 是编写 SVG 的文本模型用量；`data.usage` 中其余 token 字段是生成参考图的图片模型用量。两部分应分别按对应模型的计费规则统计。

| 字段 | 类型 | 说明 |
| - | - | - |
| `model` | string | 实际用于编写 SVG 的文本模型。 |
| `input_tokens` | integer | 文本模型的输入 token 数。 |
| `output_tokens` | integer | 文本模型的输出 token 数，已包含推理 token。 |
| `reasoning_tokens` | integer | 输出 token 中用于推理的部分，不能再次加到 `output_tokens` 上。 |

以下仅展示 SVG 任务响应的主要字段。token 数值用于说明字段关系，不代表固定消耗。

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example.svg"
          ]
        }
      ]
    },
    "usage": {
      "input_tokens": 40,
      "output_tokens": 1800,
      "total_tokens": 1840,
      "svg_usage": {
        "model": "gpt-5.4-mini",
        "input_tokens": 1200,
        "output_tokens": 800,
        "reasoning_tokens": 200
      }
    }
  }
}
```

## 常见参数错误

以下参数校验错误会在提交时同步返回 HTTP 400，不创建任务、不扣费。请修正参数后再提交。

| 报错 | 处理方式 |
| - | - |
| `quality "ultra" is not supported by gpt-image-2.6-flare` | 使用 `low` / `medium` / `high` / `xhigh` / `max` / `auto`，不支持 `ultra` 等其他值。 |
| `` `n` must be an integer from 1 to 4 `` | 将 `n` 设为 1–4 的整数；`0`、负数和大于 4 的值均不合法。 |
| `output_compression must be an integer from 0 to 100` | 将 `output_compression` 设为 0–100 的整数。 |
| `output_compression is only supported with output_format jpeg or webp` | 仅在 JPEG / WebP 请求中使用压缩参数；PNG / GIF / SVG 请求应移除此参数。 |
| `moderation "xxx" is not supported` | 将 `moderation` 设为 `low` 或 `auto`。 |
| `markup requires image_urls` | 补充 `image_urls`，并确保标注对应第一张图。 |
| `markup cannot be combined with mask` | 标注层与蒙版二选一。 |
| `frame_count must be an integer from 2 to 16` | 将 `frame_count` 改为 2–16 的整数。 |
| `no supported sheet fits N GIF frames at size WxH` | 缩小单帧尺寸或减少帧数；不要使用比例名。 |
| `output_format=svg requires svg.model` | 补充 `svg` 对象和受支持的文本模型。 |
| `output_format=svg requires n=1` | SVG 请求设置 `n: 1`。 |
| `background=transparent requires an alpha-capable output_format` | 显式透明背景仅搭配 PNG / WebP；SVG 无需传该字段。 |

## 不支持的参数与计费

不要传 `stream`、`partial_images`、`input_fidelity`、`prompt_rewriter` 或 `response_format`。本接口返回异步任务和 CDN 文件链接，不返回流式部分图片或 Base64 图片响应。`frame_count` / `frame_duration_ms` 仅用于 GIF，`svg` 配置仅用于 SVG。

Flare 与 Sunburst 采用相同计费标准。GPT-Image-2.6 的 `low` / `medium` token 消耗高于 2.5，不应直接沿用旧模型的费用估算。实际价格以 [APIMart 价格页面](https://apimart.ai/pricing) 或 `/api/pricing` 为准，本页不列固定价格。

新增能力的上游说明见 [OpenAI 图像生成指南](https://developers.openai.com/api/docs/guides/image-generation)。调用 APIMart 时，端点、异步响应和参数限制以本页为准。


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