AI教程

通过 APIMart API 使用 GPT Image 2.5 生成图像

了解如何通过 APIMart 的异步图像 API 调用 GPT Image 2.5。本教程涵盖模型选择、API 设置、curl 和 Python 示例、任务轮询、提示词构建、参考图像、价格检查、重试机制，以及临时输出 URL 的生产环境处理。

AI我搜编辑部2026年9月20日阅读约 15 分钟

本项目提供什么

image2.5 提示词图库是一个实用集合，包含 12 个通过 GPT Image 2.5 运行并与生成图像一同发布的提示词。每个配方都会记录提示词、模型版本、宽高比和输出结果，便于你在将提示词调整为自己的应用方案前进行评估。

示例使用 APIMart 的 OpenAI 兼容端点 https://api.apimart.ai/v1。中继路由是异步的：你的应用提交图像请求，接收任务 ID，轮询任务端点，并在处理完成后下载图像。

主要功能

OpenAI 兼容的生成路径：请求发送至 POST /v1/images/generations。
两种中继变体：日常生成使用 version: "flare"，编辑和参考图驱动的工作使用 version: "sunburst"。
多种输出档位：可选择 1K、2K 或 4K。
灵活构图：使用 auto 或十种受支持的宽高比之一，包括 1:1、16:9、9:16 和 4:3。
批量输出：通过 n 请求生成一至四张图像。
支持参考图像：可在 image_urls 中提供最多 16 个 URL 或数据 URL。
按调用报告费用：已完成的任务数据包含 cost 和 credits_cost。
幂等重试：API 接受 Idempotency-Key 请求头，在重试相同提交时帮助避免重复处理。

选择正确的模型路由

APIMart 同时提供中继路由和官方 GPT Image 2.5 路由。两者的请求字段和计费方式不同，因此应在编写集成代码前选择路由。

中继按图像计费路由

将 model 设置为 gpt-image-2.5-ext，并加入 version: "flare" 或 version: "sunburst"。图库示例使用的就是此路由，按交付的图像数量计费。

flare：适合日常生成和批量草稿。
sunburst：适合精确编辑，以及必须保留参考内容、对象、徽标或产品标签的工作。

官方按令牌计费路由

直接使用 gpt-image-2.5-flare 或 gpt-image-2.5-sunburst。使用这些模型 ID 时不要发送 version 字段。官方路由按令牌计费，支持从 low 到 max 的质量档位，以及精确的像素尺寸。

不要混用路由格式。gpt-image-2.5-ext 别名需要版本选择器，而官方模型 ID 不得包含版本选择器。

安装与设置

1. 创建并充值账户

从 APIMart 密钥页面获取 API 密钥。根据代码仓库信息，该服务没有免费配额，支持最低 $1 起的充值。

2. 将密钥存储在环境变量中

export APIMART_API_KEY="your-api-key"

避免将密钥直接放入应用源代码，或将其提交到版本控制系统。

3. 安装 Python 依赖

Python 示例使用第三方 requests 软件包。

python -m pip install requests

如果更喜欢使用 curl，请确保 shell 中提供了 curl 以及 uuidgen 等 UUID 生成器。

使用 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": "雨天窗边舒适的阅读角，温暖的台灯，电影感灯光",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

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

轮询任务

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

任务通常会从 pending 变为 processing，然后以 completed 或 failed 结束。任务完成后，从 result.images[].url 获取生成图像的 URL。

生成的图像 URL 包含 expires_at 时间戳。请在 URL 过期前下载并存储每个文件。

构建端到端 Python 客户端

此示例提交一个请求，检查 HTTP 错误，每五秒轮询一次，并返回已完成的任务记录。每次开始新的生成时，它都会创建一个新的幂等键。

import os
import time
import uuid
import requests

BASE_URL = "https://api.apimart.ai/v1"
API_KEY = os.environ["APIMART_API_KEY"]

COMMON_HEADERS = {
    "Authorization": f"Bearer {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,
        timeout=60,
        json={
            "model": "gpt-image-2.5-ext",
            "version": version,
            "prompt": prompt,
            "size": size,
            "resolution": resolution,
            "n": 1,
        },
    )
    response.raise_for_status()
    task_id = response.json()["data"]["id"]

    while True:
        poll_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=COMMON_HEADERS,
            timeout=60,
        )
        poll_response.raise_for_status()
        task = poll_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(
    "Studio product hero of a matte ceramic espresso cup on a warm stone pedestal, soft window light, 85mm lens look, minimal beige backdrop, crisp shadow"
)

print("Cost:", result.get("cost"))
for image in result["result"]["images"]:
    print("Image URL:", image["url"])
    print("Expires at:", image.get("expires_at"))

安全重试

如果提交超时或收到可重试的响应，请使用相同的 Idempotency-Key 重新发送同一个逻辑请求。只有在有意创建新图像时才使用新密钥。如果由于源内容或参考图发生变化而必须重新创建已完成的任务，也请使用新密钥。

了解主要请求字段

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：图像数量；对于中继路由，范围为一到四张。
image_urls：可选数组，最多包含 16 个图像 URL 或数据 URL。

编写更可靠的提示词

图库将提示词视为一份精简的制作简报，而不是一串模糊的形容词。实用的结构包括主体、材质、光线、构图或镜头，以及成品效果。

明确主体：确定主要物体、人物、场景或环境。
指定实体材质：使用 matte ceramic（哑光陶瓷）、frosted glass（磨砂玻璃）或 clay render（黏土渲染）等短语。
设定光线：描述柔和的窗光、自然侧光、高调影棚灯光或戏剧性逆光。
确定构图：说明居中构图、俯拍平铺、宽幅电影感构图或其他预期布局。
加入镜头语言：85mm、24mm、macro（微距）和 focus stacked（焦点堆栈）等术语可以引导透视和细节表现。
选择成品效果：绘画感细节、商业产品摄影或清晰矢量边缘等短语可以控制视觉处理方式。

例如：

Cosmetics packshot of a frosted glass bottle with amber serum,
water droplets on the surface, seamless pale pink backdrop,
high detail commercial product photography

使用参考图像

对于图生图或参考图驱动的创作，请在中继请求中加入 image_urls 数组。该路由最多接受 16 张参考图。

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

请使用稳定且可访问的参考图 URL。如果任务因参考图 URL 过期而失败，请重新托管图像，并使用新的幂等密钥提交新任务。

调用官方路由

官方路由使用直接的模型 ID，并使用 quality 设置，而不是中继路由的 version 选择器。

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
  }'

请查阅官方路由文档和中继路由文档，了解当前字段详情。

高级生产技巧

将提交与处理分离

将返回的任务 ID 存储在队列或数据库中，不要让 Web 请求一直保持打开状态。后台工作进程可以轮询未完成的任务，并持久化已完成的结果。

使用适中的轮询间隔

仓库示例每五秒轮询一次。避免创建不必要流量的紧密循环。对于更大的工作负载，可在任务保持待处理或处理状态时加入退避机制。

记录实际成本

保存每个已完成任务的 cost 或 credits_cost。这样可以获得逐次调用的支出记录，而不只是依赖估算值。

README 报告的中继路由观测价格为：每张已交付的 1K 图像 $0.0085，2K 为 $0.014，4K flare 为 $0.021。表格中未确定 4K sunburst 的价格。这些数据的观测日期为 2026 年 9 月，因此在制定预算或扩展规模前，请查看实时价格。

立即下载结果

不要将 result.images[].url 视为永久存储。在 expires_at 之前下载文件，然后将其移动到由你的应用控制的存储空间。

扩展规模前从小规模开始

使用 1K 和 n: 1 验证提示词。只有在主体、构图和风格稳定后，才提高分辨率或请求多个输出。

让宽高比匹配使用场景

1:1：适用于图标、商品卡片和方形社交媒体素材。
16:9：适用于电影感场景、仪表板和演示文稿页眉。
9:16：适用于竖屏移动端和社交媒体布局。
4:3：适用于编辑插图和美食摄影。
3:4：适用于人像和时尚构图。

故障排查

401 或 API 密钥无效：重新复制密钥，并检查其中是否包含空格或换行符。请求头必须使用 Authorization: Bearer $APIMART_API_KEY。
余额或额度错误：向账户充值；仓库说明没有免费的备用额度。
429 响应：降低并发数，进行退避，并使用相同的幂等键重试相同的提交。
400 或找不到模型：确认 gpt-image-2.5-ext 包含版本号，而直接官方模型 ID 不包含版本号。
任务状态为 failed：检查提示词是否被拒绝，或引用 URL 是否已过期。修正输入后，使用新的密钥提交新任务。
输出 URL 不再有效：临时 URL 可能已经过期。今后应及时下载已完成的输出。

结语

image2.5 Prompt Gallery 展示了使用 GPT Image 2.5 生成素材的可重复工作流程：选择正确的路由，编写生产级提示词，提交异步请求，轮询任务 ID，记录报告的成本，并在结果过期前下载。先从单张 1K 图像开始，验证质量和计费情况，然后再扩展到更高分辨率、批量生成或基于引用的 sunburst 工作流。