博客

教程

如何通过 HiAPI API 调用 gpt-image-2.6-flare/image-to-image:curl 与 Python

参考图片上传、同步与异步请求,以及调试一个可用的调用

2026年11月10日
封面图:错落的混凝土平面在斜射日光下交错,暖灰底上有一片深蓝灰阴影与细鼠尾草色接缝。
本页内容

该端点做什么,以及何时使用 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 请求包含三个关键部分:

  1. 模型选择器——告诉 HiAPI 将请求路由到哪个模型。
  2. 提示词(prompt)——描述你想要的转换效果的文本指令。它不是可选的;提示词正是引导编辑的关键。
  3. 参考图片——模型应基于其进行处理的输入图。如何传递它取决于请求方式(见下一节)。

除此之外,只应传入该模型在其 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,并在流量需要时转向异步。模型页面提供了当前的请求参数和限制——在假定某个字段名或尺寸上限之前,请先查阅那里。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档