教程
如何通过 hiapi API 使用 grok-imagine-quality/image-to-image：curl、Python 和可用的请求
本指南向你展示如何通过 hiapi 统一任务 API，使用 grok-imagine-quality/image-to-image（Grok Imagine 系列中更高保真度的层级）转换现有图像。你将提交源图像和文本提示词，轮询获取结果，并下载生成的图像。下方的每个请求和响应结构都已对照实时 API 验证。
你需要准备
- 一个 hiapi API 密钥 — 在仪表盘中创建一个。
- 一到三个可公开访问的图像 URL用作源。平台会在服务端获取并规范化你的输入媒体，因此本地文件路径和 base64 载荷无法使用 — 请先将图像托管在 API 可访问的位置。
就这些。无需 SDK；任务 API 就是普通的 HTTPS + JSON。
请求模式
grok-imagine-quality/image-to-image 运行在异步任务端点上：你通过 POST /v1/tasks 创建任务，然后轮询 GET /v1/tasks/<taskId>（或注册回调）直到完成。
输入模式是严格的 — 未知字段会以 400 拒绝：
| 字段 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
prompt |
string | ✅ | 要对源图像做什么 |
image_urls |
string[] | ✅ | 1–3 个源/参考图像的公开 URL |
aspect_ratio |
string | – | 以下之一：auto、2:1、20:9、19.5:9、16:9、4:3、3:2、1:1、2:3、3:4、9:16、9:19.5、9:20、1:2 |
resolution |
string | – | 1k 或 2k — 小写（1K 会返回 400） |
output_format |
string | – | jpeg、png 或 webp |
注意没有什么：没有 size、没有 n、没有 seed、没有 strength 或 consistency 旋钮。输出跟随源图像的程度由你的提示词和你传入的参考图像控制 — 请参见下方 FAQ。
最小可用示例（curl）
创建任务：
curl -X POST https://api.hiapi.ai/v1/tasks \
-H "Authorization: Bearer sk-<your-key>" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-quality/image-to-image",
"input": {
"prompt": "Turn this product photo into a clean studio shot on a light gray background with soft shadows",
"image_urls": ["https://your-cdn.example.com/source.jpg"],
"aspect_ratio": "1:1",
"resolution": "2k",
"output_format": "png"
}
}'
成功创建会返回任务 ID：
{
"code": 200,
"data": {
"taskId": "task_xxxxxxxxxxxx"
}
}
轮询直到任务达到终态：
curl https://api.hiapi.ai/v1/tasks/task_xxxxxxxxxxxx \
-H "Authorization: Bearer sk-<your-key>"
运行期间，data.status 为进行中；完成后变为 success，图像位于 data.output：
{
"code": 200,
"data": {
"taskId": "task_xxxxxxxxxxxx",
"status": "success",
"output": [
{
"url": "https://.../result.png?...&expireAt=...",
"expireAt": 1760000000
}
]
}
}
⚠️ 输出 URL 是临时的（注意 expireAt）。任务成功后立即下载字节并存储到你自己的存储中 — 不要热链结果 URL。
如果任务失败，data.status 为 fail，data.error 携带 code 和 message。
Python：创建、轮询、下载
一个只使用 requests 的完整脚本：
import time
import requests
API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def create_task(prompt: str, image_urls: list[str]) -> str:
payload = {
"model": "grok-imagine-quality/image-to-image",
"input": {
"prompt": prompt,
"image_urls": image_urls, # 1-3 public URLs
"aspect_ratio": "1:1",
"resolution": "2k", # lowercase: "1k" or "2k"
"output_format": "png",
},
}
r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
data = r.json()
task_id = (data.get("data") or {}).get("taskId")
if not task_id:
raise RuntimeError(f"create failed: {data}")
return task_id
def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
deadline = time.time() + timeout_s
while time.time() < deadline:
r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
task = r.json().get("data") or {}
status = task.get("status")
if status == "success":
return task
if status == "fail":
err = task.get("error") or {}
raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
time.sleep(poll_interval)
raise TimeoutError(f"task {task_id} still running after {timeout_s}s")
if __name__ == "__main__":
task_id = create_task(
prompt="Turn this product photo into a clean studio shot on a light gray background",
image_urls=["https://your-cdn.example.com/source.jpg"],
)
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]
# The output URL expires -- download immediately and persist yourself
img = requests.get(url, timeout=120).content
with open("result.png", "wb") as f:
f.write(img)
print(f"saved result.png ({len(img)} bytes)")
生产环境注意事项
使用回调代替轮询
对于一次性脚本之外的任何场景，注册回调并跳过轮询循环。添加一个顶层 callback 对象（与 model 和 input 同级）：
{
"model": "grok-imagine-quality/image-to-image",
"input": { "...": "..." },
"callback": {
"url": "https://your-app.example.com/hooks/hiapi",
"when": "final"
}
}
when 仅支持 "final" — 当任务达到终态（success 或 fail）时你会收到恰好一次 POST。经验法则：
- 轮询适用于 CLI、笔记本和批处理作业，这些场景进程本来就会保持存活。每 3–5 秒轮询一次；不要用亚秒级间隔猛击。
- 回调更适合 Web 后端：没有挂起的连接，没有工作线程在生成期间被占用。在服务端重新获取
GET /v1/tasks/<taskId>来验证载荷，而不是盲目信任 webhook 正文。
幂等性
任务创建本身不是幂等的 — 如果你的进程在 POST /v1/tasks 之后、持久化 taskId 之前崩溃，重试会创建（并计费）第二个任务。在开始等待之前，将 taskId 以你的内部作业 ID 为键持久化到你自己的存储中，重启时通过轮询存储的 taskId 来恢复，而不是重新创建。
错误处理
你实际会遇到的错误：
401permission_denied— API 密钥无效或无权访问此模型。响应体包含一个request_id，你可以发送给支持团队：{ "error": { "code": "permission_denied", "message": "This API key cannot use the selected model. ...", "request_id": "2026...", "type": "hiapi_error" } }400INVALID_REQUEST— 模式违规，带有精确的消息。此模型的真实示例：prompt: missing required field "prompt"— 你忘记了一个必需字段。image_urls: maxItems: got 12, want 3— 参考图像太多（最多 3 个）。resolution: value must be one of '1k', '2k'— 你发送了1K/4K。additional properties 'seed' not allowed— 你传入了此模型不接受的字段。
终态
fail状态 — 任务被接受但生成失败（例如源 URL 无法获取）。检查data.error.message，修复输入，然后创建新任务。
对 5xx 和网络错误使用退避重试；不要重试 400 — 在修复载荷之前它们会以相同方式失败。
选择质量层级（以及“一致性”怎么办？）
hiapi 上的 Grok Imagine 系列按层级和模态分为单独的模型 ID。对于图像到图像，你可以选择：
grok-imagine-quality/image-to-image— 本文介绍的高保真层级；较慢，细节保留更好。grok-imagine/image-to-image— 标准层级；相同的请求模式，每张图像更快且更便宜。
层级就是模型 ID — input 内没有 quality 参数（发送它会返回 400 additional properties 'quality' not allowed）。两个层级的每图像定价在定价页面上。
相关阅读
- grok-imagine-quality/image-to-image 模型页面 — 游乐场和定价
- 如何使用 grok-imagine/text-to-image — 先从头生成源图像
- 如何使用 grok-imagine/image-to-video — 让你的结果动起来
- hiapi 文档 — 认证、任务 API 以及平台其余部分
常见问题
有一致性或强度参数吗？
没有。输入模式仅接受 prompt、image_urls、aspect_ratio、resolution 和 output_format；其他任何内容都会以 400 拒绝。要控制输出跟随源图像的程度，请在提示词中明确说明必须保留什么（“保持产品和标签完全相同，只改变背景”），并通过 image_urls 传入最多 3 张参考图像。
我可以上传本地文件或发送 base64 吗？
不能直接这样做 — image_urls 接受 URL，平台会在服务端获取它们。将文件上传到任何可公开访问的存储（S3、R2、CDN）并传入该 URL。
我可以传入多少张源图像？
1 到 3 张。空数组会失败并显示 minItems: got 0, want 1；超过 3 张会失败并显示 maxItems。
支持哪些分辨率和宽高比？
resolution 为 1k 或 2k（仅小写）。aspect_ratio 支持从 2:1 到 1:2 的 14 个值，包括 auto、16:9、1:1、9:16 以及适合手机的 9:19.5/9:20。
输出 URL 有效期多长？
每个输出都带有 expireAt 时间戳。将结果视为短暂的：任务成功后立即下载字节并自行存储。
如何生成多个变体？
没有 n 参数 — 每个变体创建一个任务。任务独立运行，因此你可以并行提交多个。
如果我的密钥正确，401 permission_denied 是什么意思？
密钥存在但无法使用此模型（计划或权限范围）。在仪表盘中检查密钥的模型权限，或使用错误响应体中的 request_id 联系支持。
