通过 APIMart 使用 GPT-Image-2.5 生成和编辑图像

image2.5 APIMart 网关的作用

image2.5 网关通过 APIMart API 提供 GPT Image 2.5 生成与编辑系列的访问能力。你无需为每个图像模型分别集成凭据和请求格式，只需使用一个基础 URL、一个 bearer 令牌，以及 OpenAI 风格的 /v1/images/generations 端点。

该 API 采用异步处理。生成请求返回的是任务 ID，而不是直接返回图像。随后，你的应用需要轮询任务端点，直到处理完成或失败。成功的任务会包含临时输出 URL，应在其过期前下载。

APIMart 是仓库文档中记录的服务。gpt-image-2.5-ext 端点是第三方中继路由，而 gpt-image-2.5-flare 和 gpt-image-2.5-sunburst 是按令牌计费的路由。在生产运行前，请确认当前限制和价格。

主要功能

• 统一的 API 基础 URL：请求使用 https://api.apimart.ai/v1。
• 两种模型变体：选择 Flare 进行日常生成和批量草稿，或选择 Sunburst 以获得更精准的编辑效果和面向生产的素材。
• 两种计费方式：中继路由按交付的图像计费，而官方路由采用基于令牌的计费。
• 异步处理：提交请求后，轮询 GET /v1/tasks/{task_id} 查看进度。
• 多种输出规格：中继路由支持 1K、2K 和 4K。
• 灵活的构图：可从十种宽高比中选择，也可以使用 auto。
• 基于参考图的生成：在 image_urls 中最多提供 16 个条目，用于图生图或编辑任务。
• 小批量生成：在中继路由中通过 n 请求交付一至四张图像。

选择正确的模型路由

按图像计费的中继路由

如果你需要按每张交付图像统一计费，请使用 model: "gpt-image-2.5-ext"。通过 version: "flare" 或 version: "sunburst" 选择底层变体。

• flare 适用于高容量生成、日常图像和草稿。
• sunburst 适用于编辑和基于参考图的生产工作。

仓库记录显示，2026 年 9 月 16 日，两种变体交付 1K 图像的价格均为每张 $0.0085。记录还显示 2K 为 $0.014，4K Flare 为 $0.021，并建议查询 4K Sunburst 的实时价格。这些是截至记录日期观察到的数值，并非永久保证。

官方按令牌计费的路由

直接使用 gpt-image-2.5-flare 或 gpt-image-2.5-sunburst，即可采用基于令牌的计费。这些路由不使用 version 字段，并支持 low、medium、high、xhigh 和 max 质量等级。官方路由还支持精确的像素尺寸。

一个实用原则是：当可预测的单图成本很重要时使用中继路由；当你需要官方路由的质量控制或精确尺寸时，可以考虑使用官方路由。

示例输出范围

仓库展示了适用于产品摄影、人像、建筑、UI 素材、插画、游戏美术、食物摄影和微距图像的提示词。以下提供的图像展示了该项目包含的视觉输出类型。

安装与设置

1. 创建 API 密钥

从 APIMart API 密钥页面获取密钥。请将其存储在环境变量中，而不是直接写入源代码。

export APIMART_API_KEY="your-api-key"

2. 选择客户端

cURL 除了标准的命令行安装外不需要项目依赖。对于 Python 示例，请安装 requests 包：

python -m pip install requests

仓库还包含一个 JavaScript 示例，适用于 Node.js 18 或更高版本，因为此版本已全局提供 fetch。

3. 了解请求标头

在 Authorization 标头中发送 API 密钥。中继路由示例还使用响应版本标头和唯一的幂等键。

• Authorization: Bearer $APIMART_API_KEY
• Content-Type: application/json
• X-APIMart-Response-Version: 2026-07-27
• Idempotency-Key: unique-request-value

重试同一提交时，请重复使用相同的幂等键。当你确实需要创建新的图像任务时，请生成新的密钥。

基本用法：使用 cURL 生成图像

以下请求使用按图像计费的路由，选择 Flare，并请求一张方形 1K 图像：

IDEMPOTENCY_KEY="$(uuidgen)"

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-APIMart-Response-Version: 2026-07-27" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "model": "gpt-image-2.5-ext",
    "version": "flare",
    "prompt": "A cozy reading nook beside a window on a rainy day, warm table lamp, cinematic lighting",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

提交成功后会返回 HTTP 202。从 data.id 读取任务标识符，或使用返回的 data.poll_url。

轮询任务

将 task_01EXAMPLE 替换为返回的任务 ID：

curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01EXAMPLE \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "X-APIMart-Response-Version: 2026-07-27"

任务状态会依次经过 pending 和 processing，最终变为 completed 或 failed。响应还可能报告 progress、cost 和 credits_cost。任务完成后，从 result.images[].url 获取图像 URL，并检查 expires_at。

端到端 Python 示例

此示例提交一张图像，并每隔五秒检查一次任务，直到任务进入终止状态：

import os
import time
import uuid
import requests

BASE_URL = "https://api.apimart.ai/v1"
COMMON_HEADERS = {
    "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
    "Content-Type": "application/json",
    "X-APIMart-Response-Version": "2026-07-27",
}

def generate_image(prompt, version="flare", resolution="1K", size="1:1"):
    submit_headers = {
        **COMMON_HEADERS,
        "Idempotency-Key": str(uuid.uuid4()),
    }

    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=submit_headers,
        json={
            "model": "gpt-image-2.5-ext",
            "version": version,
            "prompt": prompt,
            "size": size,
            "resolution": resolution,
            "n": 1,
        },
        timeout=60,
    )
    response.raise_for_status()
    task_id = response.json()["data"]["id"]

    while True:
        task_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=COMMON_HEADERS,
            timeout=60,
        )
        task_response.raise_for_status()
        task = task_response.json()["data"]

        if task["status"] == "completed":
            return task
        if task["status"] == "failed":
            raise RuntimeError(f"Generation failed: {task}")

        time.sleep(5)

result = generate_image(
    "A sky garden at dawn, architectural photography",
    version="flare",
    resolution="1K",
    size="16:9",
)

for image in result["result"]["images"]:
    print(image["url"], image.get("expires_at"))

对于生产环境中的客户端，请返回或存储完整的任务对象，以便保留费用、进度、过期时间和错误信息，而不是只返回 URL。

使用参考图像进行编辑

要在中继路由上执行图生图或图像编辑，请添加 image_urls 数组。该数组最多可包含 16 个 URL 或数据 URL。仓库说明，在此路由上，参考图像不会产生额外费用。

{
  "model": "gpt-image-2.5-ext",
  "version": "sunburst",
  "prompt": "Preserve the product label, replace the background with soft off-white, and add a natural cast shadow",
  "image_urls": [
    "https://example.com/source-product.jpg"
  ],
  "size": "1:1",
  "resolution": "2K",
  "n": 1
}

仓库建议使用 Sunburst，以获得更高的编辑精度并处理参考图像驱动的任务。请使用可访问的 URL 或有效的数据 URL，并将列表保持在文档规定的限制之内。

中继路由的请求字段参考

• model：必填。设置为 gpt-image-2.5-ext。
• version：接受 flare 或 sunburst；默认值为 Flare。
• prompt：必填，去除首尾空格后不得为空。
• resolution：接受 1K、2K 或 4K；默认值为 1K。
• size：接受 auto、1:1、16:9、9:16、4:3、3:4、3:2、2:3、5:4、4:5 或 21:9。
• n：接受 1 到 4 之间的整数。
• image_urls：可选数组，最多包含 16 个参考 URL 或数据 URL。

调用按令牌计费的路由

官方路由使用相同的生成路径，但会更改模型 ID、移除 version，并添加质量设置。此示例选择高质量的 Sunburst：

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Preserve the product label, replace the background with soft off-white, add a natural cast shadow",
    "size": "1:1",
    "resolution": "1k",
    "quality": "high",
    "n": 1
  }'

请参阅官方路由参考和中继路由参考，了解当前字段定义。

实现可靠集成的高级技巧

1. 确保重试具备幂等性。如果提交超时且无法确定任务是否已创建，请保留原始幂等键。使用新键可能会创建另一个计费生成任务。
2. 将轮询视为正常工作流。同时处理 completed 和 failed 状态。避免快速轮询；仓库示例会在每次检查之间等待五秒。
3. 使用返回的轮询 URL。响应包含 data.poll_url，无需手动重新构造任务端点。
4. 及时下载输出结果。生成的图像 URL 是临时的。请在 expires_at 时间之前，将每个输出复制到自己的存储中。
5. 记录实际费用。从任务响应中持久化保存 cost 和 credits_cost。这样可以比较实际账单与公布的价格。
6. 通过一次付费请求验证费用。价格和促销路由可能会变化，因此在启动大批量任务前，请先运行小规模测试。
7. 使用合适的路由。如果需要可预测的单图计费以及最多四张图的批量处理，请选择中继路由。如果质量梯度或精确像素控制很重要，请选择官方模型 ID。
8. 无需重写客户端即可切换变体。在中继路由上，只需在 flare 和 sunburst 之间修改 version。
9. 保护凭据。将 API 密钥保存在环境变量或密钥管理器中，绝不要在浏览器端代码中暴露。

结论

APIMart 的 image2.5 网关提供了一种一致的方式，用于访问 GPT Image 2.5 的生成和编辑功能。对于可预测的高容量生成，可以从 gpt-image-2.5-ext 和 Flare 开始；编辑或基于参考图的任务则切换到 Sunburst；当按令牌计费和更丰富的质量控制更适合任务时，使用官方模型 ID。

基本集成模式很简单：提交图像请求，保存返回的任务 ID，轮询直到完成，查看报告的费用，并在每个临时 URL 过期前下载所有结果。扩展规模前，请查看当前 APIMart 价格，并通过一次小额付费请求验证所选路由。