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

> 使用 gpt-image-2.6-ext 按张生成图片，通过 version 选择 Flare 或 Sunburst，支持参考图、SVG 和 GIF。

> [!NOTE]
>
> 使用 `gpt-image-2.6-ext`，通过 `version` 选择 `flare` 或 `sunburst`，按张固定价计费。`resolution` 支持 **`1k` / `2k` / `4k`**，当前请使用 **`n: 1`**，所有质量档位及 PNG / JPEG / WebP / SVG / GIF 均可用。

本页是 Ext 接口，模型名与参数规则不同于 [GPT-Image-2.6 按 token 计费版本](https://docs.apimart.ai/cn/api-reference/images/gpt-image-2.6/generation.md)。

```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-ext",
  "version": "flare",
  "prompt": "An orange cat resting on a sunny windowsill, a city after the rain, warm cinematic lighting",
  "size": "16:9",
  "resolution": "1k",
  "quality": "high",
  "n": 1
}'
```

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

base_url = "https://api.apimart.ai"
headers = {"Authorization": "Bearer <token>"}
payload = {
    "model": "gpt-image-2.6-ext",
    "version": "flare",
    "prompt": "An orange cat resting on a sunny windowsill, a city after the rain, warm cinematic lighting",
    "size": "16:9",
    "resolution": "1k",
    "quality": "high",
    "n": 1
}
response = requests.post(
    f"{base_url}/v1/images/generations",
    headers=headers, json=payload, timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"][0]["task_id"]
print(task_id)

deadline = time.monotonic() + 300
while time.monotonic() < deadline:
    response = requests.get(
        f"{base_url}/v1/tasks/{task_id}", headers=headers, timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    task = body.get("data", body)
    if task["status"] == "completed":
        print(task["result"]["images"][0]["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(4)
else:
    raise TimeoutError(f"Continue polling task {task_id}")
```

```javascript JavaScript theme={null}
const baseUrl = "https://api.apimart.ai";
const headers = {
  Authorization: "Bearer <token>",
  "Content-Type": "application/json",
};
const response = await fetch(`${baseUrl}/v1/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    "model": "gpt-image-2.6-ext",
    "version": "flare",
    "prompt": "An orange cat resting on a sunny windowsill, a city after the rain, warm cinematic lighting",
    "size": "16:9",
    "resolution": "1k",
    "quality": "high",
    "n": 1
  }),
});
if (!response.ok) throw new Error(await response.text());
const taskId = (await response.json()).data[0].task_id;
console.log(taskId);

async function waitForTask(taskId) {
  const deadline = Date.now() + 300_000;
  while (Date.now() < deadline) {
    const response = await fetch(`${baseUrl}/v1/tasks/${taskId}`, { headers });
    if (!response.ok) throw new Error(await response.text());
    const body = await response.json();
    const task = body.data ?? body;
    if (task.status === "completed") return task.result.images[0].url;
    if (task.status === "failed") throw new Error(task.error.message);
    await new Promise(resolve => setTimeout(resolve, 4000));
  }
  throw new Error(`Continue polling task ${taskId}`);
}
console.log(await waitForTask(taskId));
```

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

```json 400 theme={null}
{
  "error": {
    "message": "quality \"ultra\" is not supported (supported: auto / low / medium / high / xhigh / max)",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_request_error"
  }
}
```

## 认证

**Authorization** `string` *required*

使用平台 API Key 进行 Bearer Token 认证，在 [API Key 管理页面](https://apimart.ai/keys) 获取密钥。提交请求使用 `Content-Type: application/json`。

## 版本选择

| 版本 | 适用场景 |
| - | - |
| `flare` | 默认版本，偏速度，适合日常出图、批量生成与快速迭代。 |
| `sunburst` | 偏构图与编辑精度，适合成品素材、图中文字和精细编辑。 |

## 请求参数

枚举值不区分大小写，首尾空格会被去掉；示例统一使用小写。

**model** `string` *required*

固定为 `gpt-image-2.6-ext`。

**prompt** `string` *required*

生成或编辑提示词，必填且不能为空。多图编辑时可用“第一张图”“第二张图”指代素材，并说明要修改和保留的内容。

**version** `string` (default: flare)

`flare` / `sunburst`；省略使用 `flare`。其他值返回 HTTP 400。两个版本的价格可能不同。

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

`1k` / `2k` / `4k`（也接受大写 `1K` / `2K` / `4K`）。与 `size` 比例配合决定输出像素，见下方「比例与像素」表。单张价格随档位变化；其他值如 `hd` / `8k` 返回 HTTP 400。

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

只接受 `auto` 或下表的 10 种比例，不接受 `1024x1024` 等像素值。`auto` 文生图为 1:1；图生图按第一张能读取宽高的参考图，匹配最接近的支持比例。GIF 请省略此字段或传 `auto`。

**aspect\_ratio** `string`

`size` 的同义字段，二选一即可。同时传入时必须相同，否则返回 HTTP 400。GIF 同样只能省略或传 `auto`。

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

当前请使用整数 `1`。

**quality** `string`

`auto` / `low` / `medium` / `high` / `xhigh` / `max`。省略时不下发，由上游自动选择；`auto` 也不固定为 `low`。质量不影响单张价格，高档位通常耗时更长。其他值返回 HTTP 400。

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

`png` / `jpeg` / `webp` / `svg` / `gif`；`jpg` 是 `jpeg` 的别名。SVG、GIF 仅支持文生图。其他格式返回 HTTP 400。

> [!WARNING]
>
> 暂不支持 SVG 输出。

**complexity** `string`

`low` / `medium` / `high`，省略时不下发，由上游决定。用于控制画面复杂度；`low` 适合简洁图标和扁平插画，`high` 适合丰富细节。不影响单张价格。

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

最多 16 张，每张不超过 20 MB，支持 PNG / JPEG / WebP / GIF / BMP。可传公网 HTTP(S) URL 或图片 Base64 Data URL，例如 `data:image/png;base64,...`。传入后为图生图；SVG、GIF 不能带参考图。

> [!WARNING]
>
> `resolution` 为 `2k` / `4k` 时，参考图不能是 GIF / BMP。

兼容字段名 `image_url`、`image`、`images`、`input_image`、`input_images`，建议统一使用 `image_urls`。URL 需要能从公网直接访问，无需登录。

## 比例与像素

| 比例 | `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 |
| `21:9` | 2016×864 | 2688×1152 | 3840×1648 |

`auto` 文生图为 1:1，即 `1k` 1024×1024、`2k` 2048×2048、`4k` 2880×2880；图生图匹配上表中的最接近比例，不保证与原图像素尺寸完全一致。

## 参考图编辑示例

参考图也通过 `POST /v1/images/generations` 提交。请将示例 URL 替换为真实可访问的图片链接。

```json theme={null}
{
  "model": "gpt-image-2.6-ext",
  "version": "sunburst",
  "prompt": "Place the product from the first image into the scene in the second image. Preserve the logo and packaging text, and match the lighting.",
  "image_urls": [
    "https://example.com/product.png",
    "https://example.com/scene.jpg"
  ],
  "size": "auto",
  "quality": "high",
  "n": 1
}
```

## SVG 矢量图

设置 `output_format: "svg"`，仅支持文生图且 `n=1`。`size` 可使用比例名；`complexity: "low"` 适合简洁矢量图形。

**svg** `object`

可选的 SVG 编写模型配置，仅能用于 SVG 输出。整个对象可以省略，编写 SVG 的文本模型不另收费。

**svg**

**model** `string` *required*

如果传入 `svg` 对象，此字段必填。例如 `gpt-4.1-mini`。

**reasoning** `object`

**reasoning**

**effort** `string`

可选：`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`。支持的档位取决于所选文本模型；不确定时省略。

```json theme={null}
{
  "model": "gpt-image-2.6-ext",
  "prompt": "A minimalist rocket icon in a single line color, flat vector style, no text",
  "size": "1:1",
  "output_format": "svg",
  "complexity": "low",
  "svg": {
    "model": "gpt-4.1-mini"
  },
  "n": 1
}
```

## GIF 动图

设置 `output_format: "gif"`，仅支持文生图。省略 `size` / `aspect_ratio` 或传 `auto`，传比例名或像素值会返回 HTTP 400。请在提示词中描述动作及循环方式。

```json theme={null}
{
  "model": "gpt-image-2.6-ext",
  "prompt": "A cartoon puppy raises one paw to wave, then returns to the starting pose. White background, fixed camera, seamless loop.",
  "output_format": "gif",
  "quality": "medium",
  "n": 1
}
```

## 不支持与不生效的参数

| 参数 | 行为 |
| - | - |
| `width` / `height` / `markup` / `markup_url` | 提交时返回 HTTP 400。尺寸请用比例名，本模型不支持标注引导编辑。 |
| `background` / `moderation` / `output_compression` / `seed` / `negative_prompt` / `style` | 传入不会报错，但不生效。 |
| `response_format` | 不改变输出方式，结果统一为文件 URL，不返回 Base64 图片。 |

## 提交与查询结果

提交成功为 HTTP 200，从 `data[0].task_id` 取任务号。通过 [任务查询接口](https://docs.apimart.ai/cn/api-reference/tasks/status.md) 每 3–5 秒查询一次，直到 `completed` 或 `failed`。客户端等待超时后继续查询已有任务，避免重复提交生成请求。

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

下面展示查询结果中的任务对象；若响应使用 `{code, data}` 包装，先读取 `data`。右侧 Python / JavaScript 示例兼容两种读取方式。

```json theme={null}
{
  "id": "task_01EXAMPLE",
  "status": "completed",
  "progress": 100,
  "result": {
    "images": [
      {
        "url": [
          "https://upload.apimart.ai/images/example.png"
        ],
        "expires_at": 1793923252
      }
    ]
  }
}
```

`result.images[0].url` 是链接数组，首个链接为 `result.images[0].url[0]`。请在 `expires_at` 指示的时间前下载保存；建议有效期为任务完成后 24 小时。`cost` / `credits_cost` 表示最终扣费。

| 状态 | 处理方式 |
| - | - |
| `pending` / `processing` | 继续轮询。 |
| `completed` | 读取文件链接并保存。 |
| `failed` | 读取 `error.message`；失败全额退款，`cost` 为 0。修改导致失败的参数后再提交。 |

批量查询使用 `POST /v1/tasks/batch`，请求体为 `{"task_ids":["task_xxx","task_yyy"]}`。

## 计费

单张价格只由 `version` × `resolution` 决定；`quality`、格式（包括 SVG / GIF）、`complexity`、比例、参考图数量及 `svg.model` 均不影响价格。当前使用 `n=1`，失败任务全额退款。实际价格以 [APIMart 价格页面](https://apimart.ai/pricing) 或 `/api/pricing` 为准。

## 错误处理

| 阶段 / 状态 | 原因与处理 |
| - | - |
| HTTP 400 | 参数不合法，建任务前拒绝且不扣费。检查枚举、比例、参考图限制，以及 SVG / GIF 专属字段是否用于正确格式。 |
| HTTP 401 | API Key 缺失或无效，检查 Authorization。 |
| HTTP 403 | `model_price_not_configured`：所选 `version` × `resolution` 未配置价格，请联系支持或更换档位。 |
| HTTP 429 | 请求过于频繁，降低并发后重试。 |
| `status: "failed"` | 任务执行失败，例如普通图片 / GIF 的 `n=2`–`4`、参考图无法下载或内容安全策略拦截。读取 `error.message` 并调整请求，费用全额退回。 |


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