教程
如何通过 HiAPI API 调用 gpt-image-2.6-flare/image-to-image:curl 与 Python
参考图片上传、同步与异步请求,以及调试一个可用的调用
本页内容
该端点做什么,以及何时使用 image-to-image
文生图模型擅长从零开始创造场景,但许多生产任务是从一张已有的图片开始的。gpt-image-2.6-flare/image-to-image 正是 HiAPI 为这类任务提供的端点:你发送一张参考图片和一段提示词,模型会返回一张遵循你指令、同时牢牢锚定参考图的转换后图像。
典型用例包括:
- 风格迁移与重绘——将产品图变成风格化插画,或以另一种视觉语言重绘照片。
- 编辑与修饰——无需重新拍摄,即可调整现有素材的光照、背景或构图。
- 变体生成——为基础设计生成多个视觉变体,用于 A/B 测试或创意探索。
- 素材适配——为不同渠道调整参考图的尺寸或重新构图,同时保留其核心主体。
如果你的任务是“描述某样东西然后得到一张图”,文生图是更简单的选择。当输出必须明显源自某张特定输入图时,才应使用 image-to-image——那张参考图正是这次调用的全部意义所在。在本文余下部分,我们将端到端地搭建一个真实请求:先用 curl 证明它能跑通,再用 Python 编写,以便你将其接入服务。
前置条件与请求结构
在调用该端点之前,请确保以下条件已就绪:
- 一个 HiAPI 账户和 API key。 key 以 bearer token 的形式放在
Authorization请求头中发送。请勿将其提交到源码仓库,而应从环境变量(例如HIAPI_API_KEY)加载。 - 模型 id。 请严格使用
gpt-image-2.6-flare/image-to-image——模型 id 区分大小写,斜杠也是标识符的一部分。 - 端点路径。 图像生成位于 HiAPI API 主机上的图像生成路由下。请查看模型页面获取当前的基础 URL 和路径,而不是硬编码你在旧代码片段里看到的某个主机。
- 一个参考图片文件,使用常见格式(PNG 或 JPEG 是稳妥的默认选择)。将其大小保持在合理范围内;过大的文件会拖慢上传速度,还可能触发请求限制。
一个 gpt-image-2.6-flare/image-to-image 请求包含三个关键部分:
- 模型选择器——告诉 HiAPI 将请求路由到哪个模型。
- 提示词(prompt)——描述你想要的转换效果的文本指令。它不是可选的;提示词正是引导编辑的关键。
- 参考图片——模型应基于其进行处理的输入图。如何传递它取决于请求方式(见下一节)。
除此之外,只应传入该模型在其 HiAPI 模型页面上有文档说明的参数。如果你发现自己因为某个字段名“看起来对”而臆造它,请停下来查阅文档——未知参数是导致令人困惑的 4xx 错误的常见原因。
如何传递参考图片
从概念上讲,参考图片只是请求体中的另一个输入字段——但它的体积使其变得特殊。把字节传给 API 有两种实用方式,而这一选择对你的客户端代码的影响远大于对 API 本身的影响。
方式 A:内联在请求体中
小图片可以直接嵌入 JSON 载荷中,通常以 base64 编码字符串的形式。你读取文件、进行编码,然后把字符串放入请求的 image 字段。这样所有内容都在一个请求中,非常适合缩略图、图标和测试夹具。
代价是:base64 会使载荷膨胀约三分之一,JSON 编码器可能无法处理超长字符串,而且在日志中调试数兆字节的请求体非常痛苦。内联是为了方便,不适用于大型素材。
方式 B:先上传,再通过 URL 引用
对于小图以外的任何内容,先将文件上传到你控制的存储,然后将其 URL 作为参考传入。你的请求体会保持很小,重试的成本很低,而且同一张图片可以在多次调用中重复使用,无需每次重新上传。
使用 URL 时需注意几点:
- URL 必须能被 API 公开访问——不能位于鉴权之后,不能是 localhost,也不能是会在请求中途失效的过期签名链接。
- 使用模型接受的内容类型;如果 URL 返回的是 HTML 而不是图片,校验会失败。
- 优先使用稳定的文件名,以便在你的存储和 HiAPI 请求之间关联日志。
无论选择哪种方式,参考图片和提示词都在同一个请求中传递。API 并不要求单独的“先上传再生成”握手——模型调用是一个单一的逻辑操作。
同步调用与异步调用
图像生成需要时间,这就是为什么许多图像 API 在提供同步方式的同时也提供异步任务方式。这里同样适用这一权衡。
同步
你发送请求并保持连接打开,直到图片返回。你的代码是一条直线:构建请求、POST、读取响应、完成。
在以下情况下使用同步调用:
- 你正在做原型开发或调试,希望一步看到完整结果。
- 请求运行在可以接受阻塞一段时间的环境中(CLI 工具、后台 worker)。
- 你想要尽可能简单的客户端,不需要轮询逻辑。
缺点是长时间生成意味着长时间保持连接,而你和 API 之间的任何代理或负载均衡器都可能施加自己的超时。
异步
你将请求作为任务提交,立即获得一个任务标识符,然后轮询(或接收回调)直到任务完成。你的客户端需要一个小型状态机:提交、等待、获取结果、处理失败。
在以下情况下使用异步调用:
- 你正在服务面向用户的流量,无法承受阻塞请求线程。
- 你正在批量生成许多图片,希望并行分发并收集结果。
- 你的基础设施有你不控制的短请求超时。
如何选择:如果有人在 Web 请求中等待结果,请使用异步。如果脚本或 worker 在离线等待,同步更简单也没问题。不要过度设计:先同步,当真实的超时或并发限制迫使你这样做时再转向异步。
本文余下部分使用同步方式,因为它让每个步骤都清晰可见,但你构建的请求体在两种模式下是相同的——只有外围的管道不同。
一个可用的 curl 请求
让我们从终端构建这次调用。先设置你的 key:
export HIAPI_API_KEY="your-api-key-here"
第 1 步:准备参考图片
从一张小而确认无误的图片开始,这样失败时原因不会有歧义:
ls -lh reference.png
file reference.png
file 应报告 PNG image data 或 JPEG image data。如果报告的是其他内容,请先修正再继续。
第 2 步:发送请求
请求是向图像生成端点发送的 POST,JSON 请求体包含模型、你的提示词和参考图片。根据你选择的上传方式,image 字段要么是 URL,要么是 base64 字符串。
curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png"
}'
关于这些参数:
-sS隐藏进度条但仍显示错误——适合脚本。Authorization: Bearer $HIAPI_API_KEY使密钥不出现在命令本身中。$HIAPI_BASE_URL从模型页面设置;不要猜测主机。- 这里的
image字段使用 URL 方式;对于内联图片,请替换为 base64 字符串。
第 3 步:读取响应
添加 -i 以包含响应头,添加 -w '\nHTTP %{http_code}\n' 以打印状态码。成功的调用会返回图片(或指向图片的链接,取决于响应格式)以及元数据。失败时会得到 4xx 或 5xx 状态码和一个 JSON 错误体——在改动其他任何东西之前,先阅读 message 字段。
第 4 步:将输出管道到文件
为了得到干净的文件,将 stdout 重定向到文件,并再次用 file 检查它。如果响应是包含 URL 的 JSON,请提取该 URL 并用第二个 curl 下载它。在将其接入任何自动化流程之前,务必验证下载的字节确实是图片。
同样请求的 Python 版本
curl 基线可以直接翻译成 Python。此示例只使用标准库加上 requests:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-image-2.6-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png",
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
处理响应
响应格式有所不同——它可能直接包含图片,也可能包含一个 URL。写一个小辅助函数来统一这两种情况,这样下游代码就不必关心是哪种:
def extract_image(data):
if "url" in data:
return requests.get(data["url"], timeout=60).content
if "image" in data:
import base64
return base64.b64decode(data["image"])
raise ValueError(f"Unexpected response shape: {list(data)}")
处理错误
不要让 raise_for_status() 成为你唯一的错误路径。包装调用并暴露 API 的错误消息:
try:
response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
image_bytes = extract_image(response.json())
except requests.HTTPError as e:
print("HTTP", e.response.status_code, e.response.text)
raise
except requests.Timeout:
print("Request timed out; consider the async job route instead")
raise
异步变体
对于异步方式,用相同的载荷提交任务,从响应中读取任务 id,然后在两次尝试之间短暂休眠以轮询任务状态端点。为轮询次数设置上限,并将预算耗尽视为失败——绝不要在请求处理器中无限轮询。
排查常见错误
大多数失败都归于几类。按顺序检查此清单;每一步隔离一个变量。
鉴权错误(401 / 403)
HIAPI_API_KEY是否确实在 shell 或进程中设置?echo $HIAPI_API_KEY应打印出它。- 请求头是否恰好为
Authorization: Bearer <key>——大写 A、大写 B、一个空格? - key 是否已被撤销或轮换?重新生成它,并用最小请求重试。
无效的参考图片载荷
这是最常见的失败,而且通常不是模型的错:
- URL 不可达:在不同网络的浏览器中打开图片 URL。如果它 404 或重定向到登录页,API 也无法访问它。
- 内容类型错误:返回 HTML 或 JSON 的 URL 会被拒绝。用
curl -I <url>确认响应是Content-Type: image/...。 - 文件损坏或无法读取:在本地运行
file reference.png。验证 base64 字符串解码后字节与原文件一致。 - 文件过大:查看模型页面上记录的尺寸限制;重试前先缩小尺寸。
参数格式错误
- 模型 id 拼写错误:
gpt-image-2.6-flare/image-to-image必须完全匹配,包括斜杠。 - 缺少提示词:文本指令是必需的,不可省略。
- 多余字段:移除任何你在文档中找不到的参数。未知键常常触发 4xx。
- JSON 语法:发送前用
jq . <<< "$BODY"校验你的请求体。
超时
如果请求在图片返回之前就中断,说明连接保持得太久。缩短提示词、缩小参考图、提高客户端超时;如果问题仍然存在,改用异步任务方式——长时间生成正是异步的用武之地。
调试策略
每次尝试只改变一个变量。从一张很小且确认无误的参考图和一句提示词开始,证明管道能跑通,然后再逐步引入真实输入。每次失败时记录完整的响应体;message 字段通常会直接指出请求中出错的部分。
接入你的流水线
一旦基线跑通,养成几个习惯可以让 gpt-image-2.6-flare/image-to-image 在生产环境中保持可靠。
调用前校验输入。检查参考图片是否为受支持的格式、在大小限制内,如果它是 URL,还要检查是否可达。在自己的边界处拒绝不良输入,而不是为一次失败的往返付费。
调用后校验输出。确认响应包含真实的图片字节(检查魔数),而不是混入的 HTML 错误页。一次廉价的头部检查能为下游节省大量令人困惑的调试。
使用退避重试,但只针对正确的错误。瞬时的 5xx 和网络超时值得用指数退避加抖动重试;由不良参数引起的 4xx 错误每次都会以完全相同的方式失败,因此应修正请求而非重试它。
面向用户的工作优先使用异步。如果有人在页面上等待,提交任务并从客户端轮询——不要为长时间生成保持 Web 请求打开。
将模型 id 保存在配置中。模型 id 会随时间变化。从单一的配置点读取它们,这样更换模型只需改动一行,而不是全局搜索替换。
与其他 HiAPI 模型组合使用。该端点与文生图天然搭配,可组成混合流程(先生成基础图,再编辑它);如果你的流水线需要,还可与放大或去背景步骤搭配。由于一切都通过相同的 HiAPI 接口和鉴权,增加一个步骤只是用同样的 key 再发起一次调用。
从 curl 基线开始,移植到 Python,并在流量需要时转向异步。模型页面提供了当前的请求参数和限制——在假定某个字段名或尺寸上限之前,请先查阅那里。