Grok Image 2.0 文生图 API 怎么用？5 分钟跑通第一张图

Grok Image 2.0 文生图 API 怎么用？三步：POST /v1/tasks 创建任务，拿到 taskId 后轮询（或设回调），从 data.output[0].url 下载成图。一张 $0.052，1K 和 2K 同价。

Grok Image 2.0 已在 HiAPI 上线，打开模型页 直接生成，新用户注册送 200 积分，够先出 1 张看效果。

TL;DR

• 它是什么： grok-imagine-image-2.0/text-to-image，xAI 出品的文生图模型，走 HiAPI 统一的异步任务接口。
• 多少钱： 每张 $0.052，1K / 2K、low / medium、任意画幅都是这个价；按成功出图计费，失败自动退款。$10 约出 192 张。
• 最快怎么调： 一个 prompt 就能出图；可选 aspect_ratio、resolution、quality 三个参数。

Grok Image 2.0 文生图有哪些参数？

input 里只有四个字段：

每个任务出 1 张图，要批量就并发提交多个任务。超出上表的字段或取值会返回 400，错误信息会指出具体字段。

在线试用和 API 两条路线

在线试用（1 分钟）

1. 打开文生图模型页，登录。
2. 输入提示词，选画幅和清晰度。
3. 点「运行」，任务成功后查看并下载成图。

API 接入（5 分钟）

1. 在控制台创建 API Key。
2. POST /v1/tasks 提交任务。
3. 轮询 GET /v1/tasks/<taskId>，或设置回调。
4. 成功后立刻下载 data.output[0].url。

Product photography of a matte black ceramic coffee mug filled with steaming black coffee, thin wisps of steam curling upward, mug placed on a warm honey-toned wooden table near a bright window with sheer curtains, soft natural window light from the left creating gentle highlights on the mug's curved surface, shallow depth of field with the background softly blurred, plenty of empty negative space to the right of the mug for text overlay, warm cozy morning color grade, realistic commercial photography style, 3:2 aspect ratio

先拿到一条能跑通的提示词：下面这条是一张 3:2 的产品图，用这个提示词生成 →（比例选 3:2，清晰度选 2K）

curl 和 Python：跑通第一张图

先设置 API Key：

export HIAPI_API_KEY="sk-..."

所有请求都带 Authorization: Bearer sk-<key>。图片生成是异步的，和 HiAPI 其他模型共用同一个任务接口。

第 1 步，创建任务：

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": {
      "prompt": "A red apple on a wooden table, studio lighting, shallow depth of field",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

立刻返回 taskId：

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67" }
}

第 2 步，轮询到终态：

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JGSGB818MX59GVZZCVH67 \
  -H "Authorization: Bearer $HIAPI_API_KEY"

查询 data.status：success 表示成功，fail 表示失败；其他状态继续等待。成功响应示例：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JGSGB818MX59GVZZCVH67-0.jpg",
        "artifactId": "76710",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

storage: "temp" 和 expireAt 要留意：成图地址是临时的，任务完成后马上下载，或转存到自己的对象存储。

Python 版本：

先安装 requests（python3 -m pip install requests）并设置上面的 HIAPI_API_KEY。脚本最多轮询 10 分钟；超时后保留 taskId 继续查询。

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def generate_image(prompt: str, aspect_ratio: str = "1:1", resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = generate_image("A red apple on a wooden table, studio lighting", resolution="2k")
    print(url)

上线前要注意什么？

• 批量用回调，不要紧循环轮询。 创建任务时带上 callback，任务结束后 HiAPI 推送到你的地址：

  {
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": { "prompt": "..." },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final" 在任务到达成功或失败终态时通知，接收端按 taskId 去重。交互式页面用轮询，批处理用回调。

• 成图立刻转存。 data.output[0].url 是临时地址，按 expireAt 过期。

• 一个任务只提交一次。 拿到响应后保存 taskId 与业务任务的对应关系；重复提交可能创建多个任务并分别计费。创建请求超时而没有收到 ID 时，先核对任务记录，再决定是否重新提交。

• 显式写 resolution。 默认是 1k；1K 和 2K 同价，成稿直接传 "resolution": "2k"。

• 调提示词用 quality: low。 同价、返回更快，定稿再切 medium。

• 错误处理。 先检查 HTTP 状态和响应中的 code、message，再读取 data。参数或鉴权错误应修正后再提交；任务返回 fail 时记录错误并停止轮询。

相关阅读

• Grok Image 2.0 API 多少钱？文生图 $0.052 一张，2K 不加价
• Grok Image 2.0 文生图提示词：5 个场景直接复制出图
• Grok Image 2.0 图生图 API 接入：单张参考图改图
• Grok Image 2.0 vs GPT Image 2：同提示词对照
• 鉴权与快速开始

常见问题

模型 ID 怎么写？ 写完整的 grok-imagine-image-2.0/text-to-image，保留版本号 2.0 和 /text-to-image。

报 "additional properties not allowed" 怎么办？ input 只接受 prompt、aspect_ratio、resolution、quality 四个字段，其他模型常见的 size、n、seed、negative_prompt、output_format 在这里不可用，删掉即可。

一次能出多张吗？ 不能，每个任务出 1 张。需要多张就提交多个任务并发执行。

输出地址有效多久？ 临时存储，响应里的 expireAt 是 Unix 时间戳。任务成功后马上下载或转存。

要同步等结果吗？ 不用。创建接口在任务入队后立即返回；短脚本轮询 GET /v1/tasks/<taskId>，生产环境设置 callback。

失败的任务会扣钱吗？ 不会，按成功出图计费，失败自动退款。data.status 为 fail 时停止轮询。

现在就出第一张图

先设置 HIAPI_API_KEY，用上面的 curl 创建任务，再用返回的 data.taskId 查询；任务成功后从 data.output[0].url 下载。想先看效果，打开文生图模型页，注册送的 200 积分够出 1 张。