Grok Image 2.0 图生图 API 怎么用？一张参考图一句话改图

Grok Image 2.0 图生图 API 怎么用？传一张公开可访问的参考图加一句编辑指令，POST /v1/tasks 提交，轮询拿到 data.output[0].url 就是改好的图。每张固定 $0.065，1K 和 2K 同价，不用蒙版、不用图层。

Grok Image 2.0 已在 HiAPI 上线，打开图生图模型页 上传一张图就能改，新用户注册送 200 积分，够出 1 张图生图（130 积分）。

TL;DR

• 它是什么： grok-imagine-image-2.0/image-to-image，xAI 出品，单张参考图加自然语言指令改图，换背景、加小物件、改材质颜色都行。
• 多少钱： 每张 $0.065，1K / 2K、low / medium 价格相同；按成功出图计费，失败自动退款。$10 约出 153 张。
• 最快怎么调： 必填只有 prompt 和 image 两项；image 是一个 URL 字符串，不是数组。

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

每次只能改一张参考图，一个任务出一张图；多张就提交多个任务并发执行。字段名和取值不在上表内的请求会返回 400。

在线试用和 API 两条路线

在线试用（1 分钟）

1. 打开图生图模型页，登录并上传参考图。
2. 输入编辑指令，选清晰度。
3. 点「运行」，任务成功后对比参考图与成图。

API 接入（5 分钟）

1. 在控制台创建 API Key。
2. 把参考图放到公网可访问的地址（自己的 CDN 或对象存储）。
3. POST /v1/tasks 提交任务，轮询或设置回调。
4. 成功后立刻下载 data.output[0].url。

Keep the elderly luthier exactly as he is: his face, expression, hands, seated pose, and the checked flannel shirt he's wearing, completely unchanged. Replace only the background environment: move him from the wood-shaving workshop into a sunlit outdoor market stall with hanging string instruments and warm afternoon light, matching the new environment's light direction so it falls naturally across his face and hands.

直接试一条改图提示词：把老琴师从木屑作坊换到阳光市集，人物不动。用这个提示词生成 →（链接只预填提示词，参考图在模型页自行上传，清晰度选 2K）

curl 和 Python：跑通第一次改图

先设置 API Key：

export HIAPI_API_KEY="sk-..."

所有请求都带 Authorization: Bearer sk-<key>。图片编辑是异步的，和 HiAPI 其他模型共用同一个任务接口。参考图由服务端抓取，本地文件路径不行，必须是公网可访问的 URL。

第 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/image-to-image",
    "input": {
      "prompt": "Change the mug on the table to matte black ceramic, keep everything else in the scene identical",
      "image": "https://your-cdn.example.com/source-photo.jpg",
      "resolution": "2k"
    }
  }'

立刻返回 taskId：

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

第 2 步，轮询到终态：

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

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

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

storage: "temp" 和 expireAt 要留意：成图地址是临时的，任务完成后马上下载，或转存到自己的对象存储。输出画幅跟随参考图，示例省略不生效的 aspect_ratio。

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 edit_image(prompt: str, image_url: str, resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/image-to-image",
            "input": {
                "prompt": prompt,
                "image": image_url,
                "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 = edit_image(
        "Change the mug on the table to matte black ceramic, keep everything else identical",
        "https://your-cdn.example.com/source-photo.jpg",
        resolution="2k",
    )
    print(url)

上线前要注意什么？

• 参考图先放到公网。 用户上传的图如果在私有桶或 localhost，平台抓不到，任务会异步失败；提交前先确认链接能公开访问，并用长期有效的地址（不要用会过期的签名链接）。

• 指令写成"保持什么、只改什么"。 先写必须不变的部分，再写要改的部分，改动范围越窄越稳。更多写法见图生图提示词模板。

• 批量用回调，不要紧循环轮询。

  {
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": { "prompt": "...", "image": "https://your-cdn.example.com/source-photo.jpg" },
    "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 同价（$0.065），成稿直接传 "2k"。

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

相关阅读

• Grok Image 2.0 文生图模型页：同系列，只用文字生成新图。
• Grok Image 2.0 API 多少钱？
• Grok Image 2.0 文生图 API 接入
• Grok Image 2.0 图生图提示词模板
• 鉴权与快速开始

常见问题

image 传一个 URL 还是数组？ 一个字符串 URL。传数组会报类型错误。需要多图融合时请换用支持多张参考图的模型。

报 "additional properties not allowed" 怎么办？ input 只接受 prompt、image、aspect_ratio、resolution、quality。其他编辑模型常见的 image_urls、strength、mask、seed、negative_prompt 在这里不可用，删掉即可。

浏览器能打开参考图，为什么任务仍可能失败？ 平台在服务端抓图，参考图应无需登录且可从公网访问；签名链接须在抓取完成前保持有效。检查访问权限、格式和链接有效期后再提交。

一次能改多张图吗？ 不能，一张图进、一张图出。批量就提交多个任务并发执行。

图生图为什么比文生图贵？ 图生图 $0.065，文生图 $0.052，多出 25%，对应"带一张参考图改图"的能力。

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

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

现在就改第一张图

先设置 HIAPI_API_KEY，再把 curl 和 Python 示例中的 image 地址换成自己的公网图片 URL。想先看效果，打开图生图模型页，上传图片后粘贴上面的提示词。