教程

如何通过 hiapi API 使用 grok-imagine 图生图：curl、Python 与一个可用的请求

2026年11月3日

grok-imagine/image-to-image 接收一张或多张参考图像以及一段文本提示词，返回一张编辑后的图像——可以给产品照片换风格、替换背景，或最多将三张参考图融合为一个输出。在 hiapi 上，它通过统一的任务 API 运行：创建任务、轮询（或接收回调）、下载结果。本指南将带你走一遍准确的请求结构，并提供可直接复制粘贴、开箱即用的 curl 和 Python 示例。

你将构建什么 + 前置条件

目标：提交一张参考图像和一段提示词，拿回一张编辑后图像的 URL，并下载它——先通过轮询进行交互式操作，再使用回调的生产版本。

你只需要一样东西：一个 hiapi API 密钥。从你的仪表盘获取——它看起来像 sk-...，并在每次调用时放入 Authorization: Bearer 请求头中。

你的参考图像必须是可公开访问的 URL（模型会在服务端获取它们），因此请先将它们托管在你的 CDN 或对象存储上。

最小可运行示例（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/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.com/product.jpg"]
    }
  }'

有两个必填字段——prompt 和 image_urls——这就是一个完整请求。响应中会在 data.taskId 下包含任务 ID：

{
  "data": {
    "taskId": "<task-id>"
  }
}

轮询结果：

curl https://api.hiapi.ai/v1/tasks/<task-id> \
  -H "Authorization: Bearer sk-<your-key>"

任务运行期间，data.status 会报告进度。当它变为 success 时，图像 URL 位于 data.output[0].url。如果是 fail，data.error 中有错误码和消息。

一个重要细节：输出 URL 是带签名的且会过期（载荷中带有 expireAt）。任务成功后应立即下载文件——绝不要存储或热链原始输出 URL。

curl -o result.png "<data.output[0].url>"

Python 中的相同示例

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-<your-key>"}

payload = {
    "model": "grok-imagine/image-to-image",
    "input": {
        "prompt": (
            "Turn this product photo into a clean studio shot "
            "on a seamless white background with soft shadows"
        ),
        "image_urls": ["https://your-cdn.com/product.jpg"],
        "aspect_ratio": "auto",
        "resolution": "1k",
        "output_format": "png",
    },
}

# 1. Create the task
resp = requests.post(API, json=payload, headers=HEADERS, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll until it reaches a terminal state
while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task failed: {task.get('error')}")
    time.sleep(5)

# 3. Download immediately — output URLs expire
with open("result.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved result.png")

完整的输入 schema

字段	必填	类型	说明
`prompt`	✅	string	要改什么 / 目标外观
`image_urls`	✅	URL 数组	1–3 张参考图像，必须可公开访问
`aspect_ratio`	可选	enum	`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`	可选	enum	`1k` 或 `2k`——小写
`output_format`	可选	enum	`jpeg`、`png` 或 `webp`

该 schema 是严格的：任何它不认识的字段都会被以 400 拒绝。没有 size，没有 seed，没有 n——如果你正在移植使用像素尺寸的模型代码（例如 size: "1024x1024"），请在这里改用 aspect_ratio + resolution。每个任务返回一张图像；要获得变体，请提交多个任务。

多参考图：最多 3 张输入图像

image_urls 最多接受三张参考图，模型会将它们融合——例如一张产品图加一张背景板再加一张风格参考图。如果发送超过三张，API 会直接拒绝该请求：

invalid input: image_urls: maxItems: got 4, want 3

把最重要的图像（通常是主体）放在第一位，并在提示词中说明每张参考图分别贡献什么。

自动宽高比

aspect_ratio: "auto" 让模型从你的参考图像推导输出比例，而不是强制使用固定画幅——对于产品照片以及希望保留构图的编辑来说，这是合适的默认值。仅在目标场景有明确要求时才设置显式比例（例如用于故事版位的 9:16、用于主视觉横幅的 16:9）。

生产环境注意事项

用回调代替轮询

对于批处理或服务端工作负载，跳过轮询循环——在创建任务时注册回调，hiapi 会将最终结果 POST 到你的端点：

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "...",
    "image_urls": ["https://your-cdn.com/product.jpg"]
  },
  "callback": {
    "url": "https://your-server.com/hooks/hiapi",
    "when": "final"
  }
}

when 仅支持 "final"——当任务到达 success 或 fail 时你会收到一次调用，而不是中间进度事件。

经验法则：交互式工具用轮询（有用户在观看；5 秒的 sleep 循环没问题），流水线用回调（有数十个任务在运行；你不会想为每个任务配一个轮询器）。你的回调处理器仍应立即下载输出——它收到的 URL 和其他 URL 一样会过期。

幂等性与重试

任务 API 将“提交”与“结果”分离，这使得安全重试变得简单直接：

在 create 返回的那一刻持久化 taskId。如果你的进程之后崩溃，通过轮询已存储的 ID 恢复——不要重新创建。
仅在 create 调用失败且未返回 taskId 时重试（网络错误、5xx）。重新提交一个已经返回 ID 的请求会产生第二个单独计费的任务。
将 status: "fail" 视为终态。修正输入（或路由到备用方案）并提交新任务；失败的任务不会重新启动。

常见错误

你看到的	含义	修复方法
`401`——`permission_denied`	密钥错误，或密钥无权访问此模型	在仪表盘中检查密钥
`400 INVALID_REQUEST`——`missing required field "prompt"` / `"image_urls"`	缺少必填输入	两个字段都是必填的
`400 INVALID_REQUEST`——`additional properties '...' not allowed`	未知字段（例如 `size`、`seed`、`n`）	严格 schema——仅使用上表中的字段
`400 INVALID_REQUEST`——`image_urls: maxItems`	参考图超过 3 张	裁剪到 3 张
`404`——`task not found`	GET 时 `taskId` 错误或属于其他账户	检查存储的 ID
轮询时 `status: "fail"`	已接受但生成失败	读取 `data.error`，调整输入，重新提交

注意认证失败是 401，错误体中带有 "code": "permission_denied"——值得显式匹配它，因为它也涵盖密钥存在但无权访问此模型的情况。

下一步

模型详情和在线体验：grok-imagine/image-to-image
需要更高保真度？质量档使用相同的请求结构：grok-imagine-quality/image-to-image
仅从提示词开始（没有参考图像）：grok-imagine 文生图
两个档位的单图费用：定价
完整任务 API 参考：文档

常见问题

我可以传入多少张参考图像？ image_urls 中最多 3 张。API 会硬性拒绝更多（maxItems: got N, want 3）。

我可以用像素设置输出尺寸吗？ 不能。没有 size 字段——你用 aspect_ratio（14 个枚举值）控制形状，用 resolution（1k 或 2k，小写）控制清晰度。其他任何内容都会返回 400。

aspect_ratio: "auto" 做什么？ 它让模型遵循参考图像的比例，而不是强制固定画幅——这是需要保留构图的编辑的常用选择。

结果 URL 有效期多长？ 它们是带签名的 URL 且有有效期（输出载荷中的 expireAt）。任务成功后应尽快下载字节；不要热链它们。

我应该轮询还是使用回调？ 交互式使用每约 5 秒轮询一次即可。对于批处理流水线，传入 callback: {"url": ..., "when": "final"} 并为每个任务处理一次 POST——"final" 是唯一支持的触发条件。

我能在一次调用中获得多个变体吗？ 不能——没有 n 参数。每个变体提交一个任务；它们反正会并行运行。

与 grok-imagine-quality/image-to-image 有什么区别？ 请求结构相同，保真度更高（成本也更高）的渲染档位。在标准档原型验证，再把保留项放到质量档重跑；在定价页比较单图成本。

标签Image API Tutorial

查看全部文章 →