教程
如何通过 HiAPI API 使用 gpt-image-2.6-sunburst/image-to-image:curl 与 Python 实战
提交参考图、轮询异步任务,并端到端调试请求
本页内容
gpt-image-2.6-sunburst/image-to-image 的适用场景
文生图会给你模型根据提示词自由发挥的结果。图生图则从你已有的素材出发:你向端点提供一张参考图和一条指令,模型据此生成一张由该参考图衍生而来的新图。在 HiAPI 上,gpt-image-2.6-sunburst/image-to-image 是专用于这第二种模式的端点。
当源图本身就是需求的一部分时选择它——例如对现有素材重新设计风格、调整光线或构图、为产品图应用某种视觉处理,或对某个设计生成受控的变体。参考图是锚点:它承载主体、色板和布局,你的提示词描述的是变换,而不是从头描述场景。如果你没有源素材、只想根据描述得到一张图,文生图端点更简单,也能给模型更大的自由度。
两个实际影响决定了下文的一切。第一,请求携带的是近似二进制的输入(图像引用),这会影响你如何构建请求体。第二,图像生成不是即时的,因此该端点以异步任务方式运行,而不是内联返回图像。要为“提交”和“获取”两步做规划,而不是一次阻塞调用。
前置条件与鉴权设置
在发出第一个请求之前,你需要三样东西:一个 HiAPI 账户、一个 API 密钥,以及一种端点接受的引用源图的方式。在 HiAPI 控制台中创建密钥,并像对待密码一样对待它——它为每一次计入你账户的调用授权。
在 Authorization 请求头中以 bearer 令牌形式传入密钥。切勿把它硬编码在源文件、笔记本或提交历史中。将其导出为环境变量以便 shell 测试,并在应用代码中从环境(或密钥管理器)读取:
export HIAPI_API_KEY="your_api_key_here"
提前决定如何提供参考图。通常你可以把素材上传到临时位置并传入 URL,或者在请求体中以 base64 编码数据发送图像。URL 让请求更小、更易记录;base64 免去额外托管,但会膨胀请求体。无论选哪种,都要保持文件为端点支持的格式,并在发送前检查大小限制。还要记下你账户对应的 HiAPI API 基础 URL——下文每个路径都要以它作为前缀。
用 curl 提交参考图
先在 shell 中开始,这样你能准确看到实际发出的内容。调用的形态是向图生图端点发 POST,JSON 请求体包含参考图和指令。
curl -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1
}'
逐字段说明:model 选择端点;image 携带参考图(此处是 URL,如果不托管文件则是 base64 数据字符串);prompt 是编辑指令,应描述变更,而不是重新描述主体;n 是你想要的输出数量。让 prompt 具体且有范围——与参考图相矛盾的指令容易产生混乱的结果。
发送请求并检查响应体。对于异步端点,你不会收到完成的图像;你会收到任务标识符或状态对象。继续之前先保存该响应——它是后续一切操作的句柄。用 curl -i 快速检查还能看到 HTTP 状态码,这是区分鉴权问题(提交时的 4xx)与内容问题的最快方式。
用 Python 执行同样的调用
shell 调用成功后,把它移植到 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-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1,
}
resp = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)
与 curl 的差异是机械性的:密钥来自 os.environ,请求体是序列化为 JSON 的 dict,raise_for_status() 把失败的提交变成异常而不是静默错误。最后一行很重要——大多数调试痛苦都源于把 4xx 响应当成成功,然后去轮询一个从未存在的任务 ID。
对于二进制输入,读取文件、进行 base64 编码,然后把字符串放在 image 中而不是 URL。请求体的其他部分保持不变,因此你无需改动请求逻辑即可切换方式。
处理异步任务生命周期
图像生成需要时间,因此端点遵循“先提交后轮询”的模式。理解三种状态,其余就是记录工作。
1. 提交并捕获任务
你的 POST 会返回一个任务标识符。立即提取它并持久化到某处——数据库行、队列消息、可查询的日志行。如果你的进程在提交与轮询之间崩溃,该标识符是恢复你已付费工作的唯一途径。
2. 轮询直到任务完成
以固定间隔用任务 ID 轮询状态端点。从保守开始——每次检查间隔几秒——对较长任务逐步退避,以免猛击 API。在终态停止:成功、失败,或你自己设定的超时。切勿在紧密循环中轮询。
import time
def wait_for_job(job_id, base_url, api_key, timeout=300, interval=2):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(
f"{base_url}/v1/images/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
if data["status"] in ("succeeded", "failed"):
return data
time.sleep(interval)
interval = min(interval * 1.5, 15)
raise TimeoutError(f"job {job_id} not finished in time")
3. 获取并存储结果
成功时,响应会指向生成的图像。如果 URL 是临时的,请及时下载,并以你可控的名称写入自己的存储,这样下游消费者永远不依赖临时链接。把任务 ID 与存储的素材一起记录——这是你最廉价的调试辅助。
生产环境中,应由后台 worker 驱动轮询,而不是请求处理器。一个阻塞整个图像生成时长的 Web 请求既脆弱又无谓地占用连接。
常见错误及修复方法
调用失败时按此列表自上而下排查;第一项能捕获大多数问题。
提交时的 401 / 403
鉴权问题。检查密钥是否存在于 Authorization 请求头中、是否使用 Bearer 方案、是否因复制粘贴带有杂散空白或换行。确认运行请求的 shell 或进程中环境变量确实已设置。
请求体上的 400 / 422
请求体格式错误或某个字段有误。常见原因:手动 curl 字符串导致的 JSON 语法错误、image 值既不是可访问 URL 也不是有效 base64、缺少 prompt,或图像格式不受支持。在本地验证 JSON,并确认参考图确实能在浏览器中加载。
模型或路径上的 404
路径或模型名拼写错误。模型标识符是精确字符串——gpt-image-2.6-sunburst/image-to-image 与文生图变体不同,且大小写敏感。
超时与轮询挂起
区分慢任务与坏任务。为每次 HTTP 调用设置 timeout,设定你自己的总体截止时间,并在放弃时记录最后观察到的任务状态。如果任务经常超过你的截止时间,就提高它,而不是改用紧密重试循环。
输出为空或不可用
任务成功但图像不是你想要的。这通常是提示词问题:指令太模糊,或与参考图冲突。让编辑指令更具体地说明什么应改变、什么必须保持不变。
图生图管线的生产环境建议
原型跑通后,剩下的工作是可靠性与可预测性。
- 只重试可重试的错误。 对 5xx 和网络错误导致的提交失败使用指数退避重试;不要盲目重试 4xx,那只会再次失败。通过把任务键绑定到你自己的请求 ID 来自己跟踪幂等性,这样重试不会重复工作。
- 分离提交与轮询。 把提交和轮询放在不同的 worker 或阶段。这能让你的 API 延迟独立于生成时间,并让你独立扩展轮询。
- 掌控自己的存储。 任务完成后立即把结果下载到你自己的存储桶。把返回的 URL 视为临时链接。
- 将提示词纳入版本控制。 提示词是生产资产。把提示词、参考图和任务 ID 与每个输出一起存储,这样几个月后你能复现或解释某个结果。
- 关注延迟与花费。 图像任务按输出计费,因此要限制每用户并发数并按任务记录用量。监控从提交到素材存储的 p95 延迟——那是用户真正感受到的数字。
请求形态和生命周期确定后,剩下的就是常规工程。你可以在 HiAPI 文档中找到模型详情,并从那里把端点接入你的管线。