教程

如何通过 HiAPI API 调用 gpt-image-2/text-to-image@ext：curl 与 Python

面向集成文本生成图像功能的开发者的实战请求演练

2026年10月31日

gpt-image-2/text-to-image@ext 能为你提供什么

gpt-image-2/text-to-image@ext 是通过 HiAPI 统一接口对外提供的文本生成图像模型。你只需向同一个端点发送提示词及可选的生成参数，即可获取生成的图像数据。无需安装任何模型专属组件，无需按厂商分别接入 SDK，也无需管理独立账户——同一把 API key 和相同的请求结构即可覆盖平台其余能力。

当你的产品需要把文字描述转化为崭新的图像时，就选这个模型：营销文案转主视觉图、用户提示词转缩略图、按需渲染概念图的设计工具。由于调用就是一次普通的 HTTP 请求，它可以轻松嵌入后端服务、队列 worker 或脚本中，无需引入任何客户端库。

当输入是文本、输出是你打算自行存储和分发的位图时，它正是合适之选。如果日后你需要在平台上切换到其他图像路线，集成逻辑——鉴权、请求信封、输出处理——都保持不变；只需更改模型标识符和参数块。

如何阅读本指南

本演练逐层展开。首先是一个返回图像的最小请求，然后是 Python 版本，接着是在单次调用与异步轮询之间的结构决策，最后是输出处理。每一层都可独立测试，因此当出问题时，你能明确知道是哪次改动引入的。

前置条件与鉴权

在发出第一个请求之前，你需要两样东西：一个 HiAPI 账户和一把与之绑定的 API key。在账户仪表盘中创建 key，并按保管任何密钥的方式存储它——本地用环境变量，生产环境用 secrets manager。不要提交到代码仓库，也不要粘贴到会发送到浏览器的客户端代码中。

鉴权通过请求头中的 bearer token 完成。格式始终相同：

Authorization: Bearer $HIAPI_API_KEY

在 shell 中设置一次该变量，下面的示例即可引用它而无需回显密钥：

export HIAPI_API_KEY="your-key-here"

开始前需要确认的事项

该 key 处于激活状态且具备图像生成访问权限。
你的环境能够向 HiAPI 端点发起出站 HTTPS 请求。
你清楚生成文件将写入何处——测试用本地目录，生产用对象存储。

如果 key 缺失或格式不正确，问题会在首次调用时立即以鉴权错误的形式暴露，这是发现问题的最早、最清晰时机。

一个可运行的最小 curl 请求

从能产生图像的最小请求开始。除提示词外的一切都是可选的，而保持首次调用精简意味着任何错误几乎肯定与鉴权或请求结构有关，而非参数冲突。

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image@ext",
    "prompt": "一枚斑驳的黄铜指南针放在折叠的纸质地图上，柔和的窗光，浅景深",
    "size": "1024x1024",
    "n": 1
  }'

逐字段说明

model——模型标识符。这是将请求绑定到 gpt-image-2/text-to-image@ext 的唯一值；必须精确无误。
prompt——描述内容。对主体、风格和光照要具体；模糊的提示词会产生模糊的图像，且比参数错误更难调试。
size——输出尺寸。在验证流水线阶段可省略，接受默认值。
n——每次调用生成的图像数量。集成期间保持为 1，以便失败精确对应一个输出。

将响应写入文件，这样你可以检查它而不会被终端弄乱二进制数据：

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json -o response.json

一旦它返回图像，你就拥有了一个已知可用的基线。之后每次变更都应是相对它的一次可回滚的单一编辑。

将请求移植到 Python

Python 版本是同一请求，只是传输方式不同。使用 requests——它是最不易出意外的选择，且与你已验证过的 curl 字段一一对应。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-image-2/text-to-image@ext",
    "prompt": "一枚斑驳的黄铜指南针放在折叠的纸质地图上，柔和的窗光",
    "size": "1024x1024",
    "n": 1,
}

response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
data = response.json()

关键要点的解读

json=payload 一步设置内容类型并序列化请求体——无需手工拼接字符串，没有转义 bug。
实践中 timeout 不是可选项。图像生成比典型 JSON API 调用更慢；缺少超时意味着上游变慢时 worker 会挂起。
raise_for_status() 将 HTTP 失败转化为你可捕获并分类的异常，而不是让畸形响应体流向下游。

将 payload 保持为 dict，而非内联字符串。日后添加参数时，你只需加键——请求结构不变，你永远不必重新调试传输层。

如果你偏好 SDK 风格的客户端，相同的端点和请求头依然适用；只是调用语法不同。先用 curl 验证，再采用你应用已标准化的客户端。

在单次调用与异步轮询之间选择

这是设计决策而非语法决策，它对重试和存储逻辑的影响比集成中任何其他选择都大。

单次调用

在以下情况下使用单次请求-响应周期：

你按需生成，且有用户在等待。
你的 HTTP 层能容忍较长的连接。
你一次生成一张图像而非批量生成。

相对于你观察到的最慢生成时间，将超时设得宽裕一些，并把超时视为可重试的失败，而非硬错误。

异步轮询

在批量处理、请求来自队列 worker、或调用方不得阻塞时，选择异步。模式是：提交，获得句柄，然后轮询完成状态。

import time

def poll_until_done(fetch_status, handle, interval=2, max_wait=300):
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        status = fetch_status(handle)
        if status["state"] == "succeeded":
            return status
        if status["state"] == "failed":
            raise RuntimeError(status.get("error", "generation failed"))
        time.sleep(interval)
    raise TimeoutError("generation did not finish in time")

行为可靠的轮询循环规则

退避。 从较短的间隔开始并逐步增加；恒定紧凑轮询会浪费配额和速率预算。
限制等待。 max_wait 截止时间防止孤儿任务永久占用 worker。
持久化句柄。 如果 worker 重启，你必须能够恢复轮询，而不是重新提交并支付一次重复生成。
将失败视为每个任务的终态。 failed 状态应被记录，而不是在紧凑循环中默默重试。

尽早决定。事后将异步语义改造到同步代码路径上，意味着同时重写调用方、存储和错误处理。

处理图像输出

响应包含你生成的图像，但它是 JSON 信封内的数据——不是可热链的 URL。把它当作你拥有的二进制输出处理。

解码并持久化

import base64

item = data["data"][0]
image_bytes = base64.b64decode(item["b64_json"])

with open("out.png", "wb") as f:
    f.write(image_bytes)

如果响应携带的是 URL 而非内联数据，立即抓取并将字节写入你自己的存储。生成的 URL 是临时的；任何你提供给用户的内容都应位于你自己的基础设施之后。

分发前先验证

检查魔数。 PNG 以 \x89PNG 开头；HTML 错误页面则不是。几个字节的校验即可捕获那些返回 HTTP 200 但响应体错误的代理问题。
记录大小。 记录字节长度，使被截断的下载能在监控中显现。
确定性存储。 按生成 ID 而非提示词文本命名文件，并将提示词、参数和响应元数据与图像一并保存。这个组合让你日后能复现或审计任何输出。
正确设置内容类型——从实际文件推导，而非凭假设。

将元数据与产物一同保留

写一个小型伴随记录：模型标识符、完整提示词、尺寸与数量、时间戳，以及响应中的任何请求 ID。六个月后，当有人问这张图像为何如此呈现，这份记录将是你唯一的答案。

调试常见故障

大多数首次集成故障归为三类。按此顺序检查——诊断成本大致从低到高。

鉴权错误

401 或 403 意味着 key 错误、已被吊销或未被发送。在不含密钥的情况下回显请求头构造，确认 Bearer 前缀和空格完好，并确认发起请求的进程中环境变量确实已填充——常见陷阱是在 shell 中设置了，但在 worker 或容器中没有。

畸形请求体

400 通常指向请求体。回退到 curl 部分的最小请求，然后逐个加回字段。常见元凶：

model 字符串与 gpt-image-2/text-to-image@ext 不完全匹配。
请求体不是有效 JSON——多余逗号或未转义引号。
参数类型错误；n 是数字，不是字符串。
缺少 Content-Type: application/json，服务器无法解析请求体。

超时与慢响应

如果连接在图像返回前断开，你很可能超出了客户端超时，而非遇到模型故障。对于单次调用设计，提高超时；对于任何批量形态，改用异步轮询。重试时，确保没有重复生成：如果某请求可能已成功，在重新提交前检查是否已有结果。

当以上都不是时

捕获失败请求的完整响应——状态码、响应头和响应体——并用最小 curl 命令复现。在最小请求下仍存在的故障是你环境的集成问题；消失的故障则指向你添加的参数。

查看全部文章 →