教程

Grok Imagine 图像 API：文生图、图生图与 Quality

一篇指南带你了解全部四个 Grok Imagine 图像端点：价格、同一提示词下标准版与 Quality 的对比测试、合成技巧，以及可运行的 curl 和 Python 示例。

2026年11月3日

核心要点

HiAPI 上的 Grok Imagine 图像 API 共有四个端点：标准版和 Quality，每个版本都提供文生图与图生图。四者的请求结构完全相同，只有模型 id 不同。
标准版在 1K 或 2K 分辨率下均为每张图像 $0.03。Quality 在 1K 下为 $0.07，在 2K 下为 $0.10。图生图会按每张参考图像（1–3 张参考）额外收取少量费用。
使用相同提示词时，标准版画出了一个没有把手也没有导流筋的普通锥体；Quality 则画出了一个可辨认的手冲滤杯。可以用标准版做草稿、处理大批量任务，用 Quality 产出最终成品。打开文生图模型页试试看；新账户可获得 200 免费积分。

该用哪个端点

模型 id	输入	每张图像价格	适用场景
`grok-imagine/text-to-image`	提示词	$0.03（1K 和 2K）	草稿、批量生成、超宽横幅
`grok-imagine-quality/text-to-image`	提示词	$0.07（1K）/ $0.10（2K）	最终产品图、细节与材质
`grok-imagine/image-to-image`	提示词 + 1–3 张图像	$0.03 + 每张参考图 $0.003	把产品合成到场景中、批量修图
`grok-imagine-quality/image-to-image`	提示词 + 1–3 张图像	$0.08（1K）/ $0.10（2K）+ 每张参考图 $0.015	在保持主体完全一致的前提下重新打光与换风格

HiAPI 实时价格，查询于 2026 年 10 月 19 日。失败的任务不收费。

单张参考图编辑在标准版下为 $0.033，在 Quality 1K 下为 $0.095。如需了解包括视频和 Grok Imagine Image 2.0 在内的完整系列，请参阅 Grok Imagine API 定价。

同一提示词，标准版 vs Quality

1:1、2K、PNG，各运行一次：

matte ceramic pour-over coffee dripper on a pure white seamless background, studio softbox lighting, centered, no shadow gradient beyond a soft contact shadow, no text, no watermark, no props, e-commerce product photography, sharp focus

标准版：

grok-imagine/text-to-image，1:1，2K，2048×2048，$0.03，约 80 秒。

Quality：

在 Quality 上生成此提示词 →

grok-imagine-quality/text-to-image，1:1，2K，2048×2048，$0.10，约 78 秒。

差异之处：

物体本身：标准版渲染出了一个干净但通用的锥体，更像碗而不是滤杯。Quality 画出了让它成为手冲滤杯的各个部件：内侧螺旋导流筋、把手，以及带排水孔的底座。
两者都遵循了背景要求：纯白、居中、只有一处柔和的接触阴影，没有道具或文字。
尺寸与速度相同：两者都在约 80 秒内返回 2048×2048 的图像。档位改变的是细节，不是输出尺寸。

对于已知产品，Quality 值得多花 $0.07。对于情绪板或版式设计这类物体本身是通用的场景，标准版就足够了。

图生图：把你的产品放进场景

在 image_urls 中传入 1–3 个公开图像 URL，并描述需要做的改动。当 aspect_ratio 设为 auto（图生图的默认值）时，输出会采用列表中第一张图像的形状。相同提示词、相同两张图像，仅调换顺序，就得到了两种不同的裁剪：

grok-imagine/image-to-image，产品图在前，返回 1248×832（3:2）。

同一请求，场景图在前，返回 1024×1024（1:1）。

要控制裁剪，请把你想要的形状的图像放在第一位，或明确设置 aspect_ratio。

在 Quality 上，它的强项是改变某一件事，同时保持其他一切不变。这次重打光保留了面部、夹克、杯子和构图：

Relight this photo as late golden hour: warm low sun coming from the left,
long soft shadows across the table, amber rim light on her hair and jacket.
Keep her face, expression, pose, the corduroy jacket, the marble table, the
coffee cup and the entire composition exactly the same. Photorealistic, same
camera angle, same framing.

grok-imagine-quality/image-to-image，1K，auto（输入 3:2，输出 1248×832），一张参考图，$0.095，39 秒。

行之有效的模式：一句话说明要改变什么，然后列出所有必须保持不变的内容。更多配方请参阅 Grok Imagine Quality 图生图提示词。

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "A lighthouse on a rocky cliff at golden hour, waves crashing below, photorealistic",
      "aspect_ratio": "2:1",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

你会收到一个 taskId。轮询 GET https://api.hiapi.ai/v1/tasks/{taskId}，直到 data.status 为 success，然后下载 data.output[0].url。该链接会过期，请立即保存文件。

Python：全部四个端点

# pip install requests; export HIAPI_KEY=your-key first
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, prompt, image_urls=None, timeout_s=300, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    if image_urls:
        body["input"]["image_urls"] = image_urls
    # Reuse the same Idempotency-Key if you retry a submit, so a retry never bills twice
    r = requests.post(API, json=body, headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)  # 400s list every invalid field
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

# Draft on standard, then re-run the keeper on Quality
draft = generate("grok-imagine/text-to-image", "matte ceramic pour-over dripper, white background",
                 aspect_ratio="1:1", resolution="1k")
final = generate("grok-imagine-quality/text-to-image", "matte ceramic pour-over dripper, white background",
                 aspect_ratio="1:1", resolution="2k")

# Composite a product into a scene; the first image sets the shape
edit = generate("grok-imagine/image-to-image",
                "Place the product from the first image on the desk in the second image, matching its light",
                image_urls=["https://your-cdn.example.com/product.jpg",
                            "https://your-cdn.example.com/scene.jpg"])

参数

字段	是否必填	取值	说明
`prompt`	是	文本	你想要或想避免的一切都写在这里
`image_urls`	仅图生图	1–3 个 URL	jpeg、png 或 webp；不支持 SVG；每张参考图都会增加价格
`aspect_ratio`	否	`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`；图生图还接受 `auto`	`auto` 会跟随第一张图像
`resolution`	否	`1k`（默认）、`2k`	小写；仅在 Quality 下影响价格
`output_format`	否	`jpeg`（默认）、`png`、`webp`

超宽的 2:1 和 20:9 适合横幅。没有 21:9；请使用 20:9。

你会遇到的错误

以下所有错误在提交时都会返回 HTTP 400，因此不会创建任务，也不会产生费用：

resolution: value must be one of '1k', '2k'：你发送了 2K。请使用小写。
aspect_ratio: value must be one of ...：通常是 21:9。请使用 20:9。
additional properties 'n' not allowed（或 seed、negative_prompt、size）：这些字段不存在。一个任务生成一张图像；如需多张图像，请发送多个任务。
image_urls: missing required field：图生图至少需要一张图像。