博客

教程

如何通过 HiAPI API 使用 grok-imagine/text-to-image:curl 与 Python 指南

2026年11月12日
奶油色与石墨色的层叠纸质封面艺术,单张陶土色纸张层叠出浅浅的深度感。
本页内容

grok-imagine/text-to-image 能为你提供什么

grok-imagine/text-to-image 是通过 HiAPI 提供的文生图端点:你以 JSON 形式通过 HTTP 发送一个提示词和少量生成参数,然后收到一张图片。这就是全部约定。无需安装 SDK,无需初始化会话,也无需轮询后台任务就能看到第一张图。

它在开发者工作流中的定位:

  • 原型验证。 你可以在一条终端命令内从想法变成渲染出的图像,这让你能快速测试提示词创意。
  • 内容管线。 由于它只是普通 HTTP 调用,你可以像调用任何其他 API 一样,从后端服务、队列 worker 或构建脚本中调用它。
  • 产品功能。 面向用户的图像生成通常意味着你需要可预测的请求/响应处理、结构化错误和重试。无状态端点非常适合这三点。

这个端点不是什么:它不会替你存储提示词,不会管理生成图像的库,也不会替代你自己的编排。请求由你负责,输出由你负责,字节去向也由你决定。

本指南侧重于先让请求跑通,再让它可靠。无论你用 curl 还是 Python 调用,模式完全相同,因为两者都是同一个带认证的 HTTP 请求。从最小可用开始,确认往返成功,然后再叠加复杂度。

前置条件与认证

在首次调用前,请确认你具备以下条件:

  1. 一个 HiAPI 账户和 API 密钥。 把密钥当作机密:从环境变量加载,绝不要硬编码进可能被提交的脚本。
  2. 一个发起 HTTP 请求的工具。 首次测试用 curl 就够了。对于 Python,请使用 requests 或 httpx;两者后文都会涉及。
  3. 访问 HiAPI API 主机的网络。 如果你在公司代理后面,请确保为你的 shell 设置了 HTTPS_PROXY,以便 curl 和 Python 都能读取到。

密钥以 bearer token 的形式通过 Authorization 头传递:

export HIAPI_API_KEY="your-key-here"

然后每个请求都携带:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

值得立即养成的两个习惯:

  • 不要让密钥出现在 URL 中。 请求中任何部分都不应把凭据放进查询字符串,因为那里最终会进入日志和 shell 历史记录。
  • 每个环境使用一把密钥。 开发密钥和生产密钥应是不同的值,这样你可以轮换其中一个而不影响另一个。

如果你还没有生成密钥,请在 HiAPI 仪表板中创建一个,并将其存入你的机密管理器或排除在版本控制之外的本地 .env 文件。一旦 echo $HIAPI_API_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": "grok-imagine/text-to-image",
    "prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light"
  }'

各部分的作用:

  • -X POST 搭配 JSON 请求体是生成端点的标准形式。
  • model 显式选择 grok-imagine/text-to-image。在脚本中固定模型名称,而不要依赖默认值,这样默认值的变化就不会悄悄改变你的输出。
  • prompt 是唯一的内容输入。首次测试时,保持它是一句清晰的话。

成功响应会返回包含生成图像的 JSON,通常是一个 URL 或 base64 载荷,具体取决于你请求的响应格式。在编写任何解析代码之前,先用 JSON 格式化工具读取响应。如果你在终端中查看输出,通过 python -m json.tool 管道处理可以让结构更易读。

跑通之后,将原始响应保存到文件,这样你就有了一个已知良好的基线:

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

将请求体放入 request.json 后,你就能编辑提示词而无需与 shell 引号搏斗,这一点在提示词变长或包含标点时尤其重要。

Python 中的同一请求

Python 版本是同一个 HTTP 调用,只是使用体验更好:用字典代替嵌套引号,并能直接处理图像字节。

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "grok-imagine/text-to-image",
    "prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light",
}

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()
print(data)

有两个细节值得特别说明。第一,timeout=120——图像生成不是瞬时的,没有超时的请求会在上游卡住时让 worker 无限挂起。第二,在解析之前调用 raise_for_status(),这样错误响应体就不会被误认为成功的图像响应。

要保存图像,请处理两种响应形态:

item = data["data"][0]

if item.get("b64_json"):
    import base64
    image_bytes = base64.b64decode(item["b64_json"])
else:
    image_bytes = requests.get(item["url"], timeout=60).content

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

如果你偏好单一依赖集,httpx 的用法相同,使用 httpx.post(..., json=payload)。关键在于请求体和请求头与 curl 示例完全一致——正是这种一致性让两个示例可以互换,也让调试可预测。

为宽高比组织提示词

宽幅输出会以特定方式失败:模型有大量水平空间需要填充,因此它要么重复元素,要么把一个很小的主体漂浮在空荡荡的画面中。你要用提示词结构来解决,而不是堆砌更多形容词。

使用三部分骨架:

  1. 主体——图像关于什么,先说明且要具体。“一艘驶入港口的货船”比“一艘船”更好。
  2. 风格——渲染语言:摄影、扁平矢量、水彩、电影剧照。一两个词就够了。
  3. 构图——画面如何组织,宽幅比的成败就在这里。

对于构图,要明确命名水平结构:

  • 指定从左到右或全景式的阅读顺序:“宽幅远景,主体在右三分之一处,左侧是开阔天空。”
  • 将前景、中景和背景描述为分离的带状区域,因为宽幅画面自然会按层次被阅读。
  • 明确填充边缘的内容:“最左侧是港口起重机,最右侧是开阔水域。” 边缘是宽幅图像最先变空的地方。
  • 避免暗示肖像或方形构图的提示词——特写面部、单个居中物体——并预期它们会被拉伸或加黑边。

当你为全景格式设置宽高比参数时,要同时修改提示词。为方形画面写的提示词会在宽画布中产生方形概念。将其改写为包含水平距离的场景:地平线、街道、成排物体、散布在房间里的群体。

一次只迭代一个变量。固定宽高比并改变措辞;然后固定措辞并改变比例。将两者与输出一起记录,这样你就能判断哪个改动真正有帮助。

处理错误与响应码

先读状态码,再读响应体。每种常见失败都指向不同的修复方法,混淆它们会浪费时间。

401 Unauthorized

密钥缺失、格式错误或被撤销。检查请求头是否恰好是 Authorization: Bearer <key>,环境变量是否真的展开了(打印其长度,而非值),以及你是否误发了来自不同环境的密钥。

400 Bad Request

你的 JSON 是有效的 HTTP,但对该端点无效。常见嫌疑:

  • model 拼写错误或缺失。它必须是 grok-imagine/text-to-image。
  • prompt 为空或缺失。
  • 某个参数类型错误——该是数字的地方是字符串,或反之。
  • 请求体根本不是有效 JSON,通常源于 curl 中的 shell 引号问题。将请求体移入文件并使用 -d @request.json。

阅读错误消息体;它通常会指出有问题的字段。

429 Too Many Requests

你发送请求的速度超过了配额。修复在客户端:退避、排队、重试。不要因为收到 429 就收紧重试循环——那会让情况更糟。

5xx Server Errors

这些是瞬时或上游状况。延迟后重试,如果失败在多次尝试后仍持续,请捕获请求载荷和响应体用于诊断,而不是无限重试。

超时与连接错误

这些根本不是 HTTP 状态码,却是实践中最常见的失败。如果 requests 抛出连接超时,请求可能仍已被处理。在编写重试循环之前,先为你的用例决定超时意味着“重试”还是“放弃”。

生产环境中的调优与重试

基线请求跑通后,以小步调优:先改提示词措辞,再改宽高比,然后改其他参数,并排比较输出。将每个请求载荷与其输出一起保存,这样结果始终可复现。

生产包装器做三件事:只重试值得重试的失败,记录足够用于调试的日志,并在放弃时大声失败。

import time
import requests

def generate(payload, max_attempts=4):
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(
                f"{base_url}/v1/images/generations",
                headers=headers,
                json=payload,
                timeout=120,
            )
        except requests.RequestException as exc:
            log.warning("request failed attempt=%d err=%s", attempt, exc)
            time.sleep(2 ** attempt)
            continue

        if r.status_code == 429 or r.status_code >= 500:
            log.warning("retryable status=%d attempt=%d", r.status_code, attempt)
            time.sleep(2 ** attempt)
            continue

        if r.status_code >= 400:
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")

        return r.json()

    raise RuntimeError("exhausted retries")

关于该模式的说明:

  • 带上限的指数退避(2 ** attempt)可避免被限流的客户端反复冲击端点。如果你运行许多 worker,请加入抖动。
  • 只重试 429、5xx 和网络错误。 400 或 401 在每次尝试中都会以相同方式失败。
  • 记录尝试次数和状态,不要记录 API 密钥,并且如果提示词可能包含用户数据,绝不要记录完整提示词。
  • 限制总时间。 没有上限的重试循环会把一个慢请求变成一个卡住的 worker。

测量你自己的延迟和成功率,而不是假设它们;这两个数字告诉你需要更多并行还是更多退避。从本指南的最小请求开始,用上面的辅助函数包装它,然后从那里迭代。

立即开始构建持久 AI 产物

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

阅读 API 文档