博客

教程

如何通过 HiAPI API 调用 gpt-image-2.6-flare/text-to-image:curl、Python 及可运行的请求

2026年11月10日
抽象封面艺术:多片半透明玻璃交叠,将浅色区域渐变为冷蓝色条带,磨砂质感,建筑风格,无文字。
本页内容

本教程构建的内容

大多数文生图教程止步于一张成功响应的截图。这不足以让任何东西上线。本教程带你从零开始,通过 HiAPI 统一 API 与 gpt-image-2.6-flare/text-to-image 模型建立一套可复用、可运行的集成。

到结束时你将拥有三样东西:

  • 一个经过确认可正常工作的请求,先以 curl 命令形式呈现,再以等价的 Python 脚本呈现。
  • 对 HiAPI 如何组织文生图调用有清晰的心智模型——端点路径、认证头、提示词载荷和响应体——这样你就能把示例改编成自己的提示词,而不是死记硬背。
  • 将该单次调用扩展为批处理的模式,以及判断哪些失败应重试、哪些应修复的方法。

我们会让代码保持精简、依赖最少。Python 示例只使用标准库,因此你可以在任何安装了 Python 的环境中运行;等你熟悉请求结构后,再改编为 requests 或异步客户端。如果你想直接跳到可运行的调用,请跳到 curl 部分,之后再回来阅读解释。

前置条件与凭据

在第一次调用之前,确认你已具备以下条件:

  1. 一个 HiAPI 账户。 登录仪表盘,以便生成和管理凭据。
  2. 一个 API 密钥。 在仪表盘的 API 密钥区域创建一个。请像对待密码一样对待它:它授权每一个计费到你账户的请求。
  3. 一种发送 HTTP 请求的方式。 要么是安装了 curl 的 shell,要么是带标准库的 Python 3(urllib 和 json 都随 Python 一起提供)。

通过环境变量处理密钥

永远不要把密钥直接粘贴到会被提交的源文件中。改为在 shell 中导出它:

export HIAPI_API_KEY="your-api-key-here"

在 Windows PowerShell 中,使用 $env:HIAPI_API_KEY = "your-api-key-here"。在 CI 中,将其作为密钥注入。在长时间运行的服务中,启动时从密钥管理器加载。

了解基础 URL 所在位置

HiAPI 提供单一的统一 API 表面,因此基础 URL 在各模型之间保持稳定。将其保存在一个配置值中——环境变量就很合适——而不是散布在代码各处。这样在预发布和生产之间切换,或让测试指向 mock 服务器,都只需改一行。

你将调用的模型标识符是 gpt-image-2.6-flare/text-to-image。注意它包含一个斜杠;保持标识符完整,并让它位于请求构建器所期望的路径位置,完全如下面的示例所示。

密钥已导出、基础 URL 已记录,你就可以查看请求本身了。

文生图请求的剖析

每次 HiAPI 文生图调用都有相同的四个组成部分。一旦理解它们,切换模型或提示词就变得机械化了。

1. 端点路径

请求将模型标识符作为路径的一部分:gpt-image-2.6-flare/text-to-image,附加到你的基础 URL 之后。这是将你的调用路由到统一接口背后正确模型的地址。

2. 认证头

认证是 Authorization 头中的 bearer 令牌:

Authorization: Bearer $HIAPI_API_KEY

每个请求都必须包含此头。缺失或格式错误是首次调用失败最常见的原因。

3. 请求体

文生图调用是一个带 JSON 体的 POST。核心是提示词——你想要图像的自然语言描述。请求体还携带生成设置。由于 HiAPI 在模型之间规范化请求结构,你可以复用请求构建器,并在想比较输出时更改模型标识符。

4. 响应体

成功的响应返回生成的图像(或其引用)以及关于生成的元数据。你的客户端应在尝试解析图像之前检查 HTTP 状态。将响应视为数据,而不是用来肉眼查看的东西——对于自动化,你需要图像字节或 URL,并且需要将任何请求标识符与它们一起存储,以便将文件关联回产生它的调用。

这就是整个模型。此后的一切都是这四个部分的具体实例化。

用 curl 发出可运行的请求

这是完整调用。将提示词替换为你自己的文本并运行:

curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
  }' \
  --output response.json

逐行解释:

  • -X POST——生成是改变状态的调用,因此使用 POST。
  • URL——来自环境变量的基础 URL,后跟模型标识符和 /text-to-image。加引号可防止 shell 误读特殊字符。
  • Authorization: Bearer ...——凭据。$HIAPI_API_KEY 形式可让字面密钥不出现在 shell 历史中。
  • Content-Type: application/json——告诉服务器将请求体解析为 JSON。省略它是导致令人困惑的 4xx 错误的常见原因。
  • -d '{...}'——JSON 载荷。prompt 字段是你最常更改的字段;在优化输出时,在此添加生成设置。
  • --output response.json——将响应体写入文件,这样二进制图像载荷不会淹没终端。打开它,或者如果响应是 JSON 编码的,用 jq 管道处理。

快速健全性检查

如果命令迅速返回且 response.json 非空,你就拥有了一个可工作的集成。如果反而得到 4xx,请检查响应体——HiAPI 返回描述性错误,下面的错误处理部分涵盖了常见嫌疑对象。

一旦这能运行,将命令保存在项目旁边的 shell 脚本中。这是测试凭据更改或确认故障是否在你这边的最快方式。

用 Python 发出同样的请求

curl 调用可以直接转换为 Python。此脚本只使用标准库,从环境变量读取密钥,并将图像响应写入磁盘:

import json
import os
import urllib.error
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"

def generate_image(prompt: str, settings: dict | None = None) -> bytes:
    payload = {"prompt": prompt}
    if settings:
        payload.update(settings)

    request = urllib.request.Request(
        f"{BASE_URL}/{MODEL}",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            return response.read()
    except urllib.error.HTTPError as exc:
        detail = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc

if __name__ == "__main__":
    body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
    with open("output.bin", "wb") as f:
        f.write(body)
    print(f"wrote {len(body)} bytes")

几个有意的选择:

  • 超时设置得较宽裕。 图像生成比文本补全慢;120 秒的上限可避免永远挂起,同时仍能容忍缓慢但成功的调用。
  • 函数返回字节,而不是路径。 这使其可复用——你可以将字节上传到对象存储,或从 Web 处理程序返回它们。
  • 错误被包装并附带响应体。 出错时,消息会告诉你服务器说了什么,而不仅仅是状态码。
  • 载荷构建器接受可选设置。 当你添加生成参数时,扩展 settings 字典,而不是硬编码到函数中。

导出两个环境变量后,用 python generate.py 运行它。如果你更喜欢 requests,将请求构建替换为 requests.post(url, json=payload, headers=headers);结构完全相同。

批处理与并发模式

一个提示词是演示;许多提示词是工作。这一转变引入两个问题:吞吐量和可调试性。

从文件迭代提示词

将提示词放入以换行分隔的文件或 JSON 数组中。为每个提示词分配一个 ID(slug、索引或哈希),并用该 ID 命名输出文件。当一批数百张图像完成时,你可以将每个文件映射回其提示词而无需猜测。

prompts = [
    ("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
    ("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
    body = generate_image(text)
    with open(f"out/{prompt_id}.bin", "wb") as f:
        f.write(body)

显式控制并发

生成调用是 I/O 密集型的,因此并发有助于吞吐量——但无界并发会触发速率限制并让你陷入错误泥潭。先串行,测量单次调用耗时,然后用有界工作池提高并发。一个简单线程池,使用少量固定工作线程(一开始四到八个)通常就足够了。

对于更大的任务,使用异步客户端或带工作线程队列的队列。关键纪律相同:有界并行、每个提示词 ID 一个输出文件、每个请求一行日志记录 ID、状态和耗时。

保留清单

在批处理运行时写一个小的 JSON 清单,记录每个提示词 ID 及其结果。如果进程中途死亡,清单会告诉你从何处恢复,而不是重新计费整批。这一实践比任何聪明的优化都节省更多时间。

处理错误与重试

失败分为两类:你修复的和重试的。混淆它们会浪费时间,在重试风暴中还会浪费金钱。

修复这些

  • 401 / 403——认证。 密钥缺失、过期或缺少访问权限。检查 HIAPI_API_KEY 是否确实在运行命令的 shell 中导出——常见陷阱是在一个终端导出,在另一个终端运行脚本。
  • 400——载荷格式错误。 无效 JSON、缺少 prompt 或意外的字段类型。错误体通常会指出有问题的字段。在 curl 调用中小心引用你的 JSON。
  • 404——路径错误。 验证模型标识符拼写与文档完全一致,并且你的基础 URL 没有重复或缺失的路径段。

重试这些,使用退避

  • 429——速率受限。 放慢速度。尊重响应中的任何 retry-after 提示,并使用带抖动的指数退避。长期来看,限制你的并发。
  • 5xx——服务器错误。 通常是暂时性的。重试有限次数(三次是合理默认值),延迟递增,然后大声失败。

一个最小重试包装器

import random, time

def with_retries(fn, attempts=3):
    for i in range(attempts):
        try:
            return fn()
        except RuntimeError as exc:
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.uniform(0, 0.5))

用它包装 generate_image。关键是从你这边使操作幂等:因为输出文件以提示词 ID 为键,重试会覆盖而不是重复。记录每次失败及提示词 ID 和服务器消息——当你确实需要升级时,该日志正是支持团队复现问题所需的。

后续步骤

你现在有了一个可工作的请求、一个值得保留的 Python 函数,以及大规模运行它的模式。要为生产加固,请添加带请求 ID 的结构化日志,将清单持久化到持久存储以便批处理作业在崩溃后恢复,并在发送前验证提示词,以便格式错误的输入快速且廉价地失败。

最有用的下一步是在 HiAPI API 上的其他模型上复用这个确切的客户端。由于端点路径、认证头和载荷结构是共享的,将脚本改编为新模型通常意味着更改模型标识符,偶尔更改一两个设置——小小的代码更改就能带来有意义的不同输出。

从一个提示词开始,确认文件生成,然后让批处理运行器处理其余部分。

立即开始构建持久 AI 产物

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

阅读 API 文档