教程
如何通过 HiAPI API 使用 grok-imagine/text-to-image:curl 与 Python 指南
本页内容
grok-imagine/text-to-image 能为你提供什么
grok-imagine/text-to-image 是通过 HiAPI 提供的文生图端点:你以 JSON 形式通过 HTTP 发送一个提示词和少量生成参数,然后收到一张图片。这就是全部约定。无需安装 SDK,无需初始化会话,也无需轮询后台任务就能看到第一张图。
它在开发者工作流中的定位:
- 原型验证。 你可以在一条终端命令内从想法变成渲染出的图像,这让你能快速测试提示词创意。
- 内容管线。 由于它只是普通 HTTP 调用,你可以像调用任何其他 API 一样,从后端服务、队列 worker 或构建脚本中调用它。
- 产品功能。 面向用户的图像生成通常意味着你需要可预测的请求/响应处理、结构化错误和重试。无状态端点非常适合这三点。
这个端点不是什么:它不会替你存储提示词,不会管理生成图像的库,也不会替代你自己的编排。请求由你负责,输出由你负责,字节去向也由你决定。
本指南侧重于先让请求跑通,再让它可靠。无论你用 curl 还是 Python 调用,模式完全相同,因为两者都是同一个带认证的 HTTP 请求。从最小可用开始,确认往返成功,然后再叠加复杂度。
前置条件与认证
在首次调用前,请确认你具备以下条件:
- 一个 HiAPI 账户和 API 密钥。 把密钥当作机密:从环境变量加载,绝不要硬编码进可能被提交的脚本。
- 一个发起 HTTP 请求的工具。 首次测试用
curl就够了。对于 Python,请使用requests或httpx;两者后文都会涉及。 - 访问 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 示例完全一致——正是这种一致性让两个示例可以互换,也让调试可预测。
为宽高比组织提示词
宽幅输出会以特定方式失败:模型有大量水平空间需要填充,因此它要么重复元素,要么把一个很小的主体漂浮在空荡荡的画面中。你要用提示词结构来解决,而不是堆砌更多形容词。
使用三部分骨架:
- 主体——图像关于什么,先说明且要具体。“一艘驶入港口的货船”比“一艘船”更好。
- 风格——渲染语言:摄影、扁平矢量、水彩、电影剧照。一两个词就够了。
- 构图——画面如何组织,宽幅比的成败就在这里。
对于构图,要明确命名水平结构:
- 指定从左到右或全景式的阅读顺序:“宽幅远景,主体在右三分之一处,左侧是开阔天空。”
- 将前景、中景和背景描述为分离的带状区域,因为宽幅画面自然会按层次被阅读。
- 明确填充边缘的内容:“最左侧是港口起重机,最右侧是开阔水域。” 边缘是宽幅图像最先变空的地方。
- 避免暗示肖像或方形构图的提示词——特写面部、单个居中物体——并预期它们会被拉伸或加黑边。
当你为全景格式设置宽高比参数时,要同时修改提示词。为方形画面写的提示词会在宽画布中产生方形概念。将其改写为包含水平距离的场景:地平线、街道、成排物体、散布在房间里的群体。
一次只迭代一个变量。固定宽高比并改变措辞;然后固定措辞并改变比例。将两者与输出一起记录,这样你就能判断哪个改动真正有帮助。
处理错误与响应码
先读状态码,再读响应体。每种常见失败都指向不同的修复方法,混淆它们会浪费时间。
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。
测量你自己的延迟和成功率,而不是假设它们;这两个数字告诉你需要更多并行还是更多退避。从本指南的最小请求开始,用上面的辅助函数包装它,然后从那里迭代。