教程

如何使用 GPT Image 2 API：文生图与图生图指南

2026年11月3日

GPT Image 2 API 为开发者提供了什么

GPT Image 2 API 为你提供一个统一、一致的接口，用于根据提示词生成图像。你无需拼凑多个供应商或维护多个 SDK，只需向 HiAPI.ai 发送一个 HTTP 请求，即可拿回图像数据。当你构建营销素材生成器、应用引导插图或面向用户的创意工具这类功能时，这一点很重要，因为延迟、正常运行时间和可预测的请求结构都很关键。

你会用到两种生成模式：

文生图：你提供提示词和目标尺寸，模型从零开始生成图像。
图生图：你提供提示词外加一张或多张参考图，模型在这些参考图的引导下生成图像。

两种模式共享相同的身份验证和响应结构，因此一旦你有一个可用的调用，第二种只算是少量改动，而不是一次全新的集成。本指南将依次介绍如何在两个变体之间做选择、一个最小的 curl 请求、参考图处理、请求 4K 输出、Python 移植，以及能让生产图像流水线避免静默失败的错误处理模式。

如果你要构建任何需要以稳定 API 契约承载图像生成的功能，那么本文余下内容就是从零到可运行请求的最短路径。

文生图与图生图：选择变体

在写代码之前，先确定你的产品实际需要哪个变体。这个选择主要取决于你想要对输出有多大的控制，以及预期用户需要提供多少内容。

何时使用文生图

在以下情况下，文生图是合适的默认选择：

用户用文字描述他们想要什么，且没有源素材。
你要生成占位图、主视觉图，或基于固定提示词模板生成变体。
你想要尽可能简单的请求体——一个提示词和一个尺寸——以保持请求体积小、延迟可预测。

何时使用图生图

当输出必须贴近已经存在的内容时，图生图是正确选择：

对上传的产品照片进行风格重绘或重新渲染。
在一组参考素材上应用一致的视觉处理。
引导构图、配色或主体，使结果匹配现有品牌或场景。

实用规则

如果仅凭提示词就能完全决定输出，就使用文生图。如果部分意图存在于图像而非文字中——而且用提示词描述会有损、冗长或不可靠——就使用图生图并传入参考图。

一个常见错误是，在更好的提示词就能解决问题时却去使用图生图。参考图会增加上传开销，也会带来更多请求校验失败的可能。先从文生图开始，只有当你能指出某个具体视觉属性是提示词无法捕捉的时候，再转向参考图变体。

用 curl 发出你的第一个文生图请求

从 curl 开始。它排除了 SDK 行为这一变量，因此当某处失败时，你能确定问题出在身份验证或请求体结构上，而不是客户端库。

先把 API 密钥设置为环境变量，这样它就不会进入 shell 历史记录或源代码管理：

export HIAPI_API_KEY="your_api_key_here"

然后发送一个最小请求：

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024"
  }'

响应中需要检查的内容：

HTTP 状态码。200 表示请求已被接受并处理。其他任何状态码，先阅读错误响应体再改动任何内容。
身份验证。401 几乎总是表示密钥缺失、格式错误或已过期——确认 Authorization 头的格式是 Bearer 后跟密钥。
请求体。400 通常指向某个字段：参数拼写错误、模型不接受的尺寸字符串，或未通过校验的提示词。
图像载荷。取决于响应模式，你会拿到可抓取的 URL 或 base64 图像数据。两种都要处理，这样你的客户端以后才不会措手不及。

这个调用成功后，你就同时验证了三件事：密钥有效、端点路径正确、JSON 结构可接受。本指南后续的每次修改都从这个已知良好的基线开始。

用参考图引导输出

图生图请求保持与文生图相同的请求外壳，并增加一个参考图输入。提示词仍然承载指令——参考图承载视觉上下文。

请求体的变化在于，你现在要在提示词之外提供图像数据。在实际操作中，这意味着要么提供服务可抓取的 URL，要么提供内联的 base64 编码图像，具体取决于你的集成支持哪种形式。请记住以下规则：

提示词与参考图必须一致。如果提示词描述的是红色产品，而参考图是蓝色的，模型就会收到冲突信号。把提示词写成关于参考图的指令（“把这个场景重新绘成水彩风格”），而不是与参考图相矛盾的描述。
只发送你需要的。一张强参考图通常比多张弱参考图更好。多张参考图会增加上传体积，也会让你更难判断是哪一个驱动了输出。
注意请求体积。base64 编码的图像会显著膨胀请求载荷。如果你上传的是大照片，那么当请求变慢或被拒绝时，这里就是首先要检查的地方。
发送前先校验。检查图像是否为受支持的格式，以及能否干净地解码。格式错误的 base64 字符串会产生难以理解的失败，诊断起来很耗时。

可用的请求结构如下：

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Restyle this scene as a soft watercolor painting, keep composition intact",
    "image": "https://example.com/reference.jpg",
    "size": "1024x1024"
  }'

由于请求外壳没有变化，你之前验证过的 curl 调用仍然是调试工具：替换请求体，保留请求头，逐字段比较响应。

请求 4K 输出

输出分辨率在请求中指定，而不是由模型自行假定。如果你需要高分辨率输出，就要用 size 参数明确指定——不要指望默认值会很大。

{
  "model": "gpt-image-2",
  "prompt": "A detailed isometric illustration of a city block, warm evening light",
  "size": "3840x2160"
}

在转向更高分辨率时，需要验证以下几件事：

支持的尺寸字符串。尺寸值会根据模型接受的范围进行校验。被拒绝的尺寸会返回 400，而不是静默降级——因此要确认请求所需的确切尺寸字符串，而不是猜测一个接近但错误的值。
响应体积。4K 图像数据比 1K 结果大得多。如果你的响应携带 base64 或一个你会立即下载的 URL，就要在内存和超时设置中为此留出预算。
延迟。更高分辨率生成耗时更长。请慷慨地设置客户端超时，而不是让一个虽然慢但会成功的请求在你这侧超时。
成本模型。计费取决于你请求的输出尺寸和数量，因此要有意识地做选择：按功能实际需要的分辨率生成，如果 UI 不需要完整分辨率，就在你自己的流水线中降采样。当前价格见网站的价格面板。
谨慎放大。如果你需要比模型产出更大的输出，那么在生成后进行放大是一个独立步骤，有其自身的质量权衡。要有意识地决定你想走哪条路径。

在把 4K 接入批量任务之前，先用一个已知良好的提示词测试 4K，这样与分辨率相关的失败就不会和身份验证或请求体问题混淆。

把请求移植到 Python

不要在 Python 中从头重写请求。移植你已经在 curl 中验证过的确切请求体，然后单独确认响应处理。

import os
import base64
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()

item = data["data"][0]
if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
    with open("output.png", "wb") as f:
        f.write(image_bytes)
else:
    image_url = item["url"]
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)

关于移植的说明：

把密钥保留在环境变量中，与 curl 完全一样。绝不要内联它。
设置明确的超时。图像生成比典型的 JSON API 调用更慢；使用默认的短超时是导致虚假失败的常见原因。
处理两种响应模式。根据 b64_json 与 url 分支处理，可让代码无论响应如何配置都能工作。
复用函数。把这部分封装成一个小的 generate_image(prompt, size) 辅助函数，让文生图和图生图只在 payload 中可选的 image 字段上有所不同。

由于 payload 字典就是你在 curl 中测试过的同一个对象，你在 Python 中观察到的任何行为变化几乎都来自客户端侧——请求头、编码或超时——这大大缩小了调试范围。

处理错误与校验响应

图像生成本质上是一个容易失败的调用：它比大多数 API 端点更慢，携带大载荷，并依赖模型可用性。请把它视为偶尔会失败并需要重试的操作，而不是一次性操作。

响应检查清单

解析前先检查状态。调用 raise_for_status() 或检查状态码，并阅读错误响应体——它通常会指明有问题的字段。
校验结构。在索引之前确认 data 存在且非空。不要假定 data[0] 一定存在。
验证图像字节。解码后，检查输出非空且以有效的图像签名开头。零字节文件是一种静默失败，会在很久之后才暴露出来。
记录请求 ID。把响应的请求标识符保留在日志中，这样失败的生成无需复现就能追踪。

重试策略

只重试临时性失败。超时、连接重置和 5xx 响应值得重试。401 或 400 每次都会以相同方式失败——应修复请求，而不是重试它。
使用带抖动的指数退避。从较短的延迟开始并逐步增加；抖动可以避免一组工作进程同步重试。
限制尝试次数。通常重试两到三次就足够了。再往后，就把错误暴露给用户，或将任务转入死信路径。
使其幂等。由于重试可能产生重复生成，应把结果关联到原始任务 ID 存储，这样重试绝不会对用户可见操作重复计费。

使其适配异步

高分辨率生成耗时较长，因此如果你的架构允许，不要一直占着请求线程。把任务放入队列，向调用方返回任务 ID，让工作进程使用上述重试策略执行调用。这样你的 Web 层可以保持响应性，并把缓慢、易失败的工作限制在重试成本很低的地方。

从第一个可工作的调用开始就把这些检查接进去，而不是等第一次生产事故之后——一个小型校验辅助函数的成本，远低于三周后调试一个空图像文件。当身份验证、请求体结构、分辨率和重试都确认无误后，GPT Image 2 API 就会成为可靠的构建模块，而不是仅能用于演示的集成。

查看全部文章 →