GPT Image 2 全球镜像与代理：为国际团队降低访问延迟

目标模型: gpt-image-2
推理端点: https://api.toapis.com/v1/images/generations
相关阅读: GPT Image 2 API 指南 · GPT Image 2 定价 · GPT-Image-2.6 API 指南

1. 核心摘要与性能速览 (TL;DR)

• 任务：让国际团队的客户端统一指向 ToAPIs 图像网关，而不是每次调用 gpt-image-2 都向厂商源站新建一条长距离连接。
• 约定：在 POST /v1/images/generations 上使用模型 ID gpt-image-2。当前文档中的字段包括：prompt（最长 32,000 字符）、作为宽高比的 size（如 1:1 或 16:9，不是 1024x1024 这种像素字符串），以及作为档位的 resolution（1k、2k 或 4k）。
• 区域：ToAPIs 官方文档要求中国大陆用户使用基址 https://toapis.cn。本系列国际示例使用 https://api.toapis.com。路径、模型 ID 和 Bearer 头保持不变，只换源站。
• 异步协议：图像生成返回任务 id。轮询 GET /v1/images/generations/{task_id}（或 GET /v1/tasks/{task_id}），直到 completed 或 failed。客户端墙上的等待时间不等于生成时间，超时也不等于任务失败。
• 本文不声称的内容：不会给出未经核实的接入点名单、握手耗时或端到端延迟目标。这些数字请在你自己的链路上测量。参数细节和 SKU 对比见 API 指南 与 2.6 指南。

2. 通过 ToAPIs 网关为国际团队就近接入

远距离团队感受到的往往是两段不同的耗时：建立连接的时间，以及模型真正渲染的时间。把它们混成一句“接口很慢”，优化对象就会找错。前者是网络问题，可以用文档中更近的 ToAPIs 源站，并复用已建立的 HTTP 会话来处理；后者是生成时间，要在任务被接受之后再观察。

ToAPIs 提供统一的图像生成路径。官方文档当前写的是 https://toapis.com，并提醒中国大陆用户把源站换成 https://toapis.cn。本系列包括 GPT Image 2 API 指南 在内的文章，则把同样的路径发到 https://api.toapis.com。每个环境只选一个基址，写成配置，不要在同一服务里混用多个源站。

图 1：让客户端停留在同一个已文档化的 ToAPIs 源站上，复用会话，并把图像生成当作异步任务，而不是一次超长的同步往返。

这些路由习惯不依赖未公布的延迟数字：

• 每个环境一个源站。 新加坡和法兰克福的服务可以共用同一模型 ID 和请求体，但不应各自发明厂商 URL。
• 复用连接。 打开 HTTP keep-alive（若客户端已支持 HTTP/2 也可启用），避免每次提交或轮询都重新做 TLS。
• 把提交和等待拆开。 立即持久化任务 id。按有上限的间隔轮询，或优先使用 任务 Webhook，把轮询留作兜底。
• 不要把“相同提示词走边缘缓存”当成省钱手段。 ToAPIs 并未文档保证重复提示词会由边缘缓存免费返回。只要提交了两次任务，就要按两次计费来规划，除非你的账户条款另有说明。

请求约定也容易过时。较旧的示例有时把 size 写成 1024x1024，并带上 quality: "standard"。当前的 gpt-image-2 API 参考和 ToAPIs 前端约定里，size 表示宽高比（1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、21:9、9:21 或 auto），resolution 表示档位（1k、2k、4k）。当前 Playground 约定里，精确的 gpt-image-2 不暴露 quality 字段；quality 出现在 gpt-image-2-vip 等 ID 上。请确认你实际调用的 ID。

参考图放在 reference_images 中（仅限公开 URL，最多 14 张）。image_urls 是向后兼容的别名，会被规范成 reference_images。不要传 base64，请先上传。自定义比例、更多质量档位或官方 SKU 行为，见 API 指南 和 模型指南。

3. 生产级实现：cURL 与 Python

步骤 1：用 cURL 提交

curl -X POST "https://api.toapis.com/v1/images/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography",
    "size": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url"
  }'

步骤 2：Python 提交与轮询

字段名和响应包络请以你账户的 API 参考为准。示例使用文档中的图像状态路径以及 completed / failed 状态。只有在应当使用中国大陆源站的环境里，才把 BASE 换成 https://toapis.cn。

import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/images/generations"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def dispatch_image(
    prompt: str,
    size: str = "1:1",
    resolution: str = "1k",
    model: str = "gpt-image-2",
    reference_images: list[str] | None = None,
) -> str:
    payload = {
        "model": model,
        "prompt": prompt,
        "size": size,
        "resolution": resolution,
        "n": 1,
        "response_format": "url",
    }
    if reference_images:
        payload["reference_images"] = reference_images
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_image_task(task_id: str, deadline_s: int = 180) -> str:
    poll_url = f"{BASE}/v1/images/generations/{task_id}"
    interval = 2.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")


if __name__ == "__main__":
    task_id = dispatch_image(
        "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography"
    )
    print("Task:", task_id)
    print("Image:", poll_image_task(task_id))

把基址、模型 ID、size 和 resolution 与任务记录放在一起。若以后把客户端从 gpt-image-2 换到 gpt-image-2-vip 或 2.6 的 SKU，一次只改一个变量，并重读对应指南——计费单位并不自动相同。

4. 错误处理与状态码对照

下表只是排查起点，并不保证与 ToAPIs 的精确错误码一一对应。HTTP 查询成功后，仍然要读取任务 status。

$\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)$

5. 定价与 FinOps ROI

$\text{Estimated cost} = \text{successful billable images} \times \text{current account rate for that model, size, and resolution}$

• 不要沿用策划稿或旧文章里的单价。 目录价格、分辨率倍率和失败任务的处理方式会随 SKU 和账户变化。部分 GPT Image 2.x ID 按张计费；2.6 指南 说明该世代按 token 计费。请确认你实际调用的模型 ID 对应的费率。
• 换线路本身不会自动改变模型单价。 使用 api.toapis.com 还是 toapis.cn 只是基址选择，文档并未把它写成折扣。FinOps 收益来自避免客户端超时后重复提交、先用 1k 打样，以及选对 SKU。
• 厂商直签合同 常带区域结算限制、年框或预付门槛。ToAPIs 计费通常是按量付费，请以账户当前条款为准。
• 更细的费率讨论可以把 GPT Image 2 定价文章 当作背景，但写入预测之前，请用实时目录核对每一个数字。

6. 常见问题

结构化问答见文章 frontmatter 中的 FAQ。摘要：更换 ToAPIs 源站不会改变模型 ID 或文档中的请求形态；中国大陆用户应遵循官方文档中的 toapis.cn 说明；图像任务是异步的；size 是宽高比，resolution 是档位；文档并未保证重复提示词可走免费边缘缓存。

7. 行动清单

• 在 ToAPIs 开发者门户 创建密钥。
• 为每个环境设置一个基址（https://api.toapis.com，或在需要时使用 https://toapis.cn），并用 gpt-image-2、size: "1:1"、resolution: "1k" 冒烟测试上面的 cURL。
• 持久化任务 id，对 GET /v1/images/generations/{id} 做有截止时间的轮询，并在 429 时遵守 Retry-After。
• 接下来：参数细节看 GPT Image 2 API 指南；若要换 SKU，看 2.6 指南；新账户可参考 免费额度说明。