> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Imagine Image API：2.0 生图、三图编辑与价格

> 用老张API调用 grok-imagine-image-2.0：每张 0.055 美元，支持 1K/2K、15 种宽高比、批量生图和最多三张参考图的编辑。

用老张API调用 xAI 当前的图像模型 `grok-imagine-image-2.0` 文生图，或上传 1–3 张参考图编辑，每张 \$0.055。计费按成功输出的图片张数，批量请求按实际返回张数扣费。

## 当前接入范围

| 项目 | 内容 |
| - | - |
| 模型 ID | `grok-imagine-image-2.0`，末尾的 `.0` 不能省略 |
| 旧模型 | `grok-imagine-image`、`grok-imagine-image-quality` 仍可使用；三个模型 ID 相互独立，不要混用 |
| 价格 | **\$0.055/张**，按成功输出的图片张数计费（2026 年 9 月 24 日公开价格配置，见[模型与价格总表](/models)） |
| 文生图 | `POST /v1/images/generations`，JSON |
| 参考图编辑 | `POST /v1/images/edits`（OpenAI 兼容），`multipart/form-data` |
| 参考图数量 | 1–3 张；第四张起不要发送 |
| 分辨率 | `1k`、`2k` |
| 质量 | 建议显式使用 `low` 或 `medium` |
| 宽高比 | 15 个固定值；也可省略并由模型选择 |
| 单次输出 | `n=1–10` |
| 返回形式 | `url` 或 `b64_json` |
| 令牌分组与计费模式 | `default`；按量优先（推荐）或按次计费 |

<Warning>
  老张API当前的编辑接口采用 OpenAI 兼容的文件上传格式，不接受 xAI 文档中的 JSON 图片对象。四张或五张参考图会失败；请在客户端把数量限制为最多三张，不要对相同的超限请求自动重试。
</Warning>

## 价格与能力一览

| 分辨率 × 质量 | 生成 | 编辑 |
| - | - | - |
| `1k`，`low` 或 `medium` | \$0.055/张 | \$0.055/张 |
| `2k`，`low` 或 `medium` | \$0.055/张 | \$0.055/张 |

价格为 2026 年 9 月 24 日公开价格配置，核对日期 2026 年 10 月 10 日；按成功输出的图片张数计费，分辨率和质量不改变单价。模型来自 xAI 官方渠道，按张固定计费。

| 能力 | 支持情况 |
| - | - |
| 需要 xAI 账号 | 不需要，只用老张API密钥 |
| 文生图与参考图编辑 | 都支持，同价；编辑最多 3 张参考图，multipart 上传 |
| 一次出图 | `n` 为 1–10，按返回张数计费 |
| 分辨率与比例 | `1k`、`2k`；15 种固定宽高比 |
| 协议 | OpenAI Images API：`/v1/images/generations`、`/v1/images/edits` |
| 并发 | 平台不限制，`429` 来自上游容量，见[并发与 429](/faq/api-concurrency) |
| 失败扣费 | 返回错误、没有图片不按张计费；超时先查调用日志，见[扣费与失败规则](/api-capabilities/image-billing-and-failures) |

## 三个模型怎样选择

| 模型 ID | 特点 | 适合任务 |
| - | - | - |
| `grok-imagine-image-2.0` | 1K/2K、Low/Medium、15 种固定比例、最多三图编辑 | 当前 Grok 生图、精细生成与多参考图编辑 |
| `grok-imagine-image` | 旧型号，单价较低，支持多参考图编辑 | 草稿、批量候选与成本优先任务 |
| `grok-imagine-image-quality` | 旧型号，偏重画质，可用的参考图较少 | 已有兼容工作流与小规模成片任务 |

2026 年 9 月 24 日公开价格配置中，旧型号 `grok-imagine-image` 为 \$0.025/张，`grok-imagine-image-quality` 为 \$0.045/张，与 2.0 一样按成功输出的图片张数计费。

新接入优先测试 `grok-imagine-image-2.0`。现有旧模型调用无需立即迁移；可以先用相同的提示词、比例和分辨率各生成一张，再按结果与成本选择。

## 调用前准备

<Steps>
  <Step title="创建并保护令牌">
    在[令牌管理](https://api.laozhang.ai/token)创建 `default` 分组的令牌，计费模式选择「按量优先」（推荐）或「按次计费」。按量优先的令牌可以同时调用按量和按次计费的模型，按次计费的令牌只能调用按次计费的模型。

    令牌只保存在服务端环境变量中，不要写入浏览器代码、公开仓库或日志。
  </Step>

  <Step title="确认模型与价格">
    在[模型价格页面](https://api.laozhang.ai/account/pricing)确认当前令牌可以看到 `grok-imagine-image-2.0`，并核对当前单价。
  </Step>

  <Step title="配置环境">
    设置密钥环境变量，并安装 Python 示例与保存脚本用到的依赖。
  </Step>
</Steps>

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
python -m pip install openai pillow
```

cURL 示例把响应写入 JSON 文件，再用 [Images API 参考中的保存脚本](/api-reference/images#保存返回图片) `save_images.py` 保存图片；它同时处理 `url` 与 `b64_json` 两种返回。Python 示例直接在代码里保存图片。

## 文生图快速开始

下面的请求生成一张 2K、16:9、Medium 图片：

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A cinematic lighthouse at sunrise, detailed ocean reflections, no text",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "quality": "medium",
    "response_format": "url"
  }' \
  -o grok-generation.json

python save_images.py grok-generation.json grok-generation
```

成功响应为 HTTP 200，`data` 中有一张图片：

```json theme={null}
{
  "data": [
    {
      "url": "https://..."
    }
  ]
}
```

URL 是临时地址，请求成功后应尽快下载到本地或自己的对象存储。需要在响应里直接拿到图片内容时，把 `response_format` 改为 `b64_json`。

### Python SDK

```python theme={null}
import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=180,
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A premium mechanical watch on dark slate, macro product photography",
    n=1,
    response_format="b64_json",
    extra_body={
        "aspect_ratio": "1:1",
        "resolution": "2k",
        "quality": "medium",
    },
)

value = response.data[0].b64_json
if value.startswith("data:"):
    value = value.split(",", 1)[1]  # 去掉可能存在的 data:image/...;base64, 前缀
value += "=" * (-len(value) % 4)    # 补齐缺失的 = 填充
image_bytes = base64.b64decode(value)

suffix = ".png" if image_bytes.startswith(b"\x89PNG") else ".jpg"
output = Path("grok-watch" + suffix)
output.write_bytes(image_bytes)
print(f"已保存 {output}")
```

<Tip>
  OpenAI Python SDK 没有把全部 Grok 图像字段做成顶层参数。将 `aspect_ratio`、`resolution` 与 `quality` 放入 `extra_body`。
</Tip>

## 宽高比、分辨率与质量

`grok-imagine-image-2.0` 支持以下 15 个固定宽高比：

| 方向 | 支持值 |
| - | - |
| 方形 | `1:1` |
| 横向 | `16:9`、`4:3`、`3:2`、`2:1`、`19.5:9`、`20:9`、`21:9`、`5:2` |
| 纵向 | `9:16`、`3:4`、`2:3`、`1:2`、`9:19.5`、`9:20` |

省略 `aspect_ratio` 时由模型自动选择。需要稳定布局时应显式传值。

* `resolution="1k"`：更快，适合草稿、缩略图和批量候选；
* `resolution="2k"`：文件更大、延迟更高，适合成片与裁切；
* `quality="low"`：速度优先；
* `quality="medium"`：细节优先；
* 不要发送 `quality="high"`，也不要发送 `resolution="4k"`。

<Warning>
  成功响应不会明确返回最终采用的质量档。生产请求建议显式使用 `low` 或 `medium`，不要依赖 `auto` 推断成本、延迟或画质。
</Warning>

## 单张参考图编辑

编辑必须使用文件上传，不要把参考图 JSON 放进请求体：

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=Change the mug to matte black. Preserve the composition, lighting, and background." \
  -F "image=@product-photo.png" \
  -F "response_format=url" \
  -o grok-edit.json

python save_images.py grok-edit.json grok-edit
```

HTTP 200 之后仍要打开保存的图片，检查主体、颜色、文字和构图。参考图编辑会重新生成整个画面，不是像素级的 mask 局部重绘。

## 两张或三张参考图编辑

多图编辑时重复提交 `image[]`。下面的三图请求分别提供主体、场景和风格：

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=Place the product from image 1 in the scene from image 2, and apply the visual style from image 3. Preserve the product colors." \
  -F "image[]=@product.png" \
  -F "image[]=@scene.jpg" \
  -F "image[]=@style.jpg" \
  -F "aspect_ratio=3:2" \
  -F "response_format=url" \
  -o grok-multi-edit.json

python save_images.py grok-multi-edit.json grok-multi-edit
```

上传顺序对应提示词中的 image 1、image 2、image 3。这个三图请求设置了 `aspect_ratio=3:2`，预期返回一张 1248×832 的 JPEG 图片。

### Python SDK 编辑

```python theme={null}
import os
import urllib.request
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=180,
)

with open("product.png", "rb") as image:
    response = client.images.edit(
        model="grok-imagine-image-2.0",
        image=image,
        prompt="Keep the product and change the background to a rainy neon street.",
        response_format="url",
    )

# URL 是临时地址，拿到后立即下载
with urllib.request.urlopen(response.data[0].url, timeout=60) as download:
    image_bytes = download.read()

suffix = ".png" if image_bytes.startswith(b"\x89PNG") else ".jpg"
output = Path("grok-edit" + suffix)
output.write_bytes(image_bytes)
print(f"已保存 {output}")
```

OpenAI SDK 可以直接用于单图编辑。多图上传建议先使用上面的 curl 形式，确认文件数组和服务端框架的 multipart 行为。

## 参数表

| 参数 | 类型 | 必填 | 当前行为 |
| - | - | - | - |
| `model` | string | 是 | 新模型使用 `grok-imagine-image-2.0` |
| `prompt` | string | 是 | 描述内容、构图、风格和必须保留的特征 |
| `n` | integer | 否 | 文生图为 1–10；按实际输出张数计费 |
| `aspect_ratio` | string | 否 | 使用上表列出的 15 个固定值；省略时自动选择 |
| `resolution` | string | 否 | 文生图使用小写 `1k` 或 `2k` |
| `quality` | string | 否 | 文生图建议 `low` 或 `medium`；不要使用 `high` |
| `response_format` | string | 否 | `url` 或 `b64_json` |
| `image` | file | 单图编辑时是 | 单张本地图片 |
| `image[]` | file\[] | 多图编辑时是 | 重复字段，最多三张 |

## 价格与计费

`grok-imagine-image-2.0` 按成功输出的图片张数计费，1K/2K、Low/Medium 使用同一单价（见[当前接入范围](#当前接入范围)）。例如：

* `n=4` 成功返回四张时计 \$0.22；
* `n=10` 成功返回十张时计 \$0.55；
* 三张参考图编辑并返回一张结果时，只按一张计费。

老张API售价与 [xAI 官方价格](https://docs.x.ai/developers/pricing)分别计算，不能直接对照。大批量任务开始前请到[控制台](https://api.laozhang.ai/account/pricing)复核，并以调用记录作为最终账单依据。

## 错误处理

| 情况 | 可能结果 | 客户端处理 |
| - | - | - |
| API Key 无效 | 401 | 更换正确令牌，不要用同一个密钥重试 |
| 缺少 `prompt` | 400 | 补全请求 |
| `n` 超过 10 | 可能返回 429 | 客户端提前限制为 1–10 |
| 未支持的宽高比 | 可能返回 429 | 只使用本页列出的宽高比 |
| `resolution="4k"` | 可能返回 503 | 改为 `1k` 或 `2k`，不要按故障重试 |
| `quality="high"` | 可能仍返回图片 | 客户端提前拒绝，避免静默降级与计费 |
| 四张或五张参考图 | 500 | 减为最多三张，不要重试原请求 |

正常请求遇到 429、网络错误或临时 5xx 时，使用带抖动的指数退避重试。客户端超时后先检查调用记录，再决定是否重新提交，避免重复生成和重复计费。

## 上线前检查

1. 先用 1K、Low、`n=1` 生成一张图，保存后检查真实格式和像素；
2. 再测试生产需要的 2K、Medium、画幅和 `n`；
3. 编辑时使用互不重复的参考图，逐个确认主体进入了输出；
4. 在客户端把参考图数量上限设为三张；
5. 1K Low 请求的超时至少设为 60 秒，Medium 与 2K 建议 120–180 秒；
6. 扩大并发前核对成功率、延迟、图片张数和调用记录。

## 常见问题

### 新模型的正确 ID 是什么？

使用 `grok-imagine-image-2.0`，包括末尾的 `.0`。旧模型 `grok-imagine-image` 与 `grok-imagine-image-quality` 是独立的模型 ID。

### 按请求还是按张计费？分辨率和质量影响价格吗？

按成功输出的图片张数计费，1K、2K 与 Low、Medium 当前使用同一单价，举例见[价格与计费](#价格与计费)。

请求返回错误、没有生成图片时不按张计费；但客户端超时不等于失败，服务端可能已经出图并扣费，重新提交前先查调用记录。实际扣费以调用记录为准。

### 编辑能用 JSON 格式或四五张参考图吗？

都不能。编辑只接受 multipart 文件上传，最多三张参考图（见[当前接入范围](#当前接入范围)）；发送 xAI 官方的 JSON 图片对象会返回 400。

xAI 文档说 OpenAI SDK 的 `images.edit()` 不能用于 Grok 编辑，那是针对 xAI 官方的 JSON 接口。

在老张API上，`images.edit()` 可以直接做单图编辑，写法见 [Python SDK 编辑](#python-sdk-编辑)；多图编辑建议先用 cURL 的 `image[]` 写法。

### 编辑结果的宽高比由什么决定？

xAI 官方说明：不传 `aspect_ratio` 时，输出比例跟随第一张参考图。需要固定画幅时，在编辑请求里加上 `aspect_ratio`，例如三图示例中的 `aspect_ratio=3:2` 会返回 1248×832 的图片。

### 能在上一次的结果上继续编辑吗？

可以。先把上一次返回的图片下载到本地，再作为 `image` 上传，并在提示词里只写这一轮要改的内容，例如「保持画面不变，只加一个金色边框」。每一轮都是一次新的编辑请求，按返回的图片张数单独计费。

### 生成结果应该怎样保存？

返回 URL 时尽快下载到自己的存储；xAI 官方也说明返回的 URL 是临时地址，不要当作长期链接。需要响应里直接携带图片时使用 `b64_json`。本页的 cURL 示例用 `save_images.py` 保存，Python 示例在代码里直接保存。

## 来源与相关文档

* [Grok Imagine Image 2.0 上线公告](/announcements/grok-imagine-image-2-0-2026-09)：开放范围与三图编辑说明
* [xAI Grok Imagine Image 2.0 模型](https://docs.x.ai/developers/models/grok-imagine-image-2.0)：官方模型 ID、分辨率与质量价格
* [xAI 图像生成文档](https://docs.x.ai/developers/model-capabilities/images/generation)：官方画幅、分辨率、质量、批量与返回形式
* [xAI 图像编辑文档](https://docs.x.ai/developers/model-capabilities/images/editing)：官方 JSON 编辑格式，与老张API当前的 multipart 方式不同
* [xAI 多图编辑文档](https://docs.x.ai/developers/model-capabilities/images/multi-image-editing)：上游最多五图的能力，不等同于老张API当前的三图上限
* [Images API 参考](/api-reference/images)：通用 Images API 请求、响应与保存脚本
* [图像生成 API 选型与价格](/api-capabilities/image-generation-guide)：与其他图像模型对比
* [模型与价格总表](/models)与[控制台模型价格](https://api.laozhang.ai/account/pricing)：当前模型、分组、售价与调用记录入口


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.