> ## 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 2 API 图像生成与编辑 > 老张API Grok Imagine 2 中文指南：两款模型的价格、5 种宽高比、1K/2K、批量生图，以及按模型区分的单图与多参考图编辑边界。 老张API现已提供 `grok-imagine-image` 与 `grok-imagine-image-quality` 两条 Grok Imagine 图像路线，支持文生图、1K/2K、单次最多 10 张，以及通过参考图进行自然语言编辑。当前老张API按生成张数计费：标准模型 **\$0.02/张**，高质量模型 **\$0.045/张**；实际可用分组、价格与扣费结果以[控制台](https://api2.laozhang.ai/account/pricing)和调用日志为准。 “Grok Imagine 2”是本页用于描述当前一代 Grok Imagine 图像能力的产品名称。请求中的模型 ID **不含 `2`**，请使用 `grok-imagine-image` 或 `grok-imagine-image-quality`。 创建令牌并确认模型分组、余额与计费模式 查看发布日期、影响范围、价格与状态说明 ## 先选模型 | 模型 ID | 老张API当前价格 | 分辨率 | 参考图边界 | 适合任务 | | ---------------------------- | ------------: | ------- | -------------- | ------------------- | | `grok-imagine-image` | **\$0.02/张** | 1K / 2K | 老张API已实测 1–4 张 | 日常素材、批量草稿、快速迭代、多图组合 | | `grok-imagine-image-quality` | **\$0.045/张** | 1K / 2K | 老张API支持 1–2 张 | 成片、营销素材、细节与参考图编辑 | 老张API当前按返回图片张数计费，`n=4` 即按 4 张计算。1K 与 2K 当前同价；上游厂商价格表与老张API价格不是同一计费合同，不应混用。价格调整时以控制台展示和最新公告为准。 ## 当前接入范围 | 项目 | 老张API当前文档范围 | | ----------- | ------------------------------------- | | 文生图端点 | `POST /v1/images/generations` | | 参考图编辑端点 | `POST /v1/images/edits` | | 宽高比 | `1:1`、`16:9`、`9:16`、`4:3`、`3:4` | | 分辨率 | `1k`、`2k` | | 单次输出 | `n` 为 1–10 | | 标准模型参考图 | `grok-imagine-image` 支持 1–4 张 | | Quality 参考图 | `grok-imagine-image-quality` 支持 1–2 张 | | 返回格式 | `url` 或 `b64_json` | | 不在当前承诺范围 | 4K、mask 局部重绘、`seed` 可复现、自定义像素尺寸 | xAI 官方能力页列出了更多宽高比；老张API本页只承诺上表中的 5 个值。不要据此推断其他比例已通过当前网关验证。若控制台或后续公告扩大范围，本页会同步更新。 `n=10` 表示一次请求最多生成 10 张**输出图片**，不是最多上传 10 张参考图。参考图数量必须按模型和编辑路由单独判断。 ## 前置要求 在[令牌管理](https://api2.laozhang.ai/token)创建 API Key。不要把密钥写进浏览器前端、公开代码仓库或日志。 在[模型价格页面](https://api2.laozhang.ai/account/pricing)确认目标令牌分组已显示模型，并核对当前单价。公告价格不追溯修改历史订单。 使用生产同款令牌、提示词和参数生成 1 张图片，检查 HTTP 状态、`data` 数组、实际像素、下载结果和调用日志，再扩大 `n` 或并发。 ## 文生图快速开始 使用 OpenAI Images API 兼容端点： ```bash theme={null} curl https://api2.laozhang.ai/v1/images/generations \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine-image", "prompt": "一张极简科技产品海报，深蓝背景，清晰中文标题，棚拍光线", "n": 1, "aspect_ratio": "16:9", "resolution": "2k", "response_format": "url" }' ``` 预期成功结果是 HTTP 200，且 `data` 数组包含 1 个可读取的图片结果。`response_format: "url"` 时请及时下载，不要把临时 URL 当作永久素材地址。 ### Python SDK ```python theme={null} import os from openai import OpenAI client = OpenAI( api_key=os.environ["LAOZHANG_API_KEY"], base_url="https://api2.laozhang.ai/v1", ) response = client.images.generate( model="grok-imagine-image-quality", prompt="A premium skincare product on travertine, soft morning light", n=2, extra_body={ "aspect_ratio": "4:3", "resolution": "2k", "response_format": "url", }, ) for index, image in enumerate(response.data, start=1): print(index, image.url) ``` Python OpenAI SDK 没有为所有 xAI 扩展字段提供顶层参数，因此把 `aspect_ratio`、`resolution` 和 `response_format` 放进 `extra_body` 最稳妥。 ## 参考图编辑 只要任务依赖原图主体、构图、色彩或风格，就使用 `/v1/images/edits`。当前老张API兼容路由使用 `multipart/form-data` 文件上传；不要把参考图字段塞进 `/v1/images/generations` 后仅凭 HTTP 200 判断编辑成功。 ```bash theme={null} curl https://api2.laozhang.ai/v1/images/edits \ -H "Authorization: Bearer $API_KEY" \ -F "model=grok-imagine-image-quality" \ -F "prompt=把杯子改成哑光黑色，其余主体、构图、光线和背景保持不变" \ -F "image=@product-photo.png" \ -F "response_format=url" ``` 多图融合时重复提交 `image[]`，上传顺序就是提示词中的“图 1 / 图 2 / 图 3 / 图 4”。老张API当前按模型提供以下范围： | 模型 | 老张API支持的参考图数量 | 推荐用法 | | ---------------------------- | ------------- | -------------- | | `grok-imagine-image` | 1–4 张 | 三图、四图组合与日常多图任务 | | `grok-imagine-image-quality` | 1–2 张 | 单图精细编辑与双图融合 | 下面是标准模型四图融合的当前可运行写法： ```bash theme={null} curl https://api2.laozhang.ai/v1/images/edits \ -H "Authorization: Bearer $API_KEY" \ -F "model=grok-imagine-image" \ -F "prompt=把图1的产品放入图2的场景，采用图3的暖色胶片风格，并保留图4的品牌配色" \ -F "image[]=@product.png" \ -F "image[]=@scene.jpg" \ -F "image[]=@style.jpg" \ -F "image[]=@brand-reference.png" ``` 超过当前参考图上限会返回 HTTP 400。Quality 使用最多 2 张；需要三图或四图组合时改用 `grok-imagine-image`，不要对同一超限请求盲目重试。 多图编辑的输出宽高比会受第一张参考图影响。实测第一张为 1280×720 时输出为 1280×720；第一张换成 1200×1200 后输出为 1024×1024。可依赖“画幅跟随第一张”，但不要假设输出像素一定与第一张完全相同。 参考图编辑不是 mask 局部重绘。模型会根据自然语言重建结果，关键身份、商标、文字和精确几何位置仍需人工验收；不要把一次成功样例当作像素级保真保证。 ## 参数说明 | 参数 | 类型 | 必填 | 当前取值与行为 | | ------------------- | ------- | ---- | --------------------------------------------------------- | | `model` | string | 是 | `grok-imagine-image` 或 `grok-imagine-image-quality` | | `prompt` | string | 是 | 描述内容、构图、风格及需要保持不变的部分 | | `n` | integer | 否 | 1–10；这是输出图片数量，按实际生成张数计费，不是参考图数量 | | `aspect_ratio` | string | 否 | 文生图当前文档化 5 种：`1:1`、`16:9`、`9:16`、`4:3`、`3:4` | | `resolution` | string | 否 | 文生图使用小写 `1k` 或 `2k`；当前不支持 `4k` | | `response_format` | string | 否 | `url` 或 `b64_json` | | `image` / `image[]` | file | 编辑时是 | 单图可用 `image`；多图重复 `image[]`。标准模型支持 1–4 张，Quality 支持 1–2 张 | 下表可用于验收宽高比方向与分辨率档位；实际像素由当前模型实现决定，因此生产代码应读取输出文件尺寸，不要硬编码推断： | 宽高比 | 1K 方向 | 2K 方向 | 常见用途 | | ------ | ----- | ----- | ------------- | | `1:1` | 方形 | 方形 | 头像、商品主图、社媒卡片 | | `16:9` | 横向 | 横向 | 封面、演示文稿、视频缩略图 | | `9:16` | 纵向 | 纵向 | 短视频封面、移动端故事 | | `4:3` | 横向 | 横向 | 商品图、演示文稿 | | `3:4` | 纵向 | 纵向 | 人像、海报 | ## 从其他 Images API 迁移 如果现有代码使用 `size: "1536x1024"` 或 `quality: "high"`，不要只替换模型名。Grok Imagine 当前路线使用 `aspect_ratio` + `resolution` 控制画布，并用两个模型 ID 区分标准与高质量路线。 | 现有逻辑 | Grok Imagine 2 迁移动作 | | ------------------- | ---------------------------------------------------------------------- | | `size: "1536x1024"` | 改为 `aspect_ratio: "3:2"` 前先注意：`3:2` 不在老张API当前 5 个承诺值内；请选择已文档化比例或先小流量验证 | | `quality: "high"` | 改用 `grok-imagine-image-quality` | | 默认读取 `b64_json` | 显式设置 `response_format: "b64_json"`，或改为读取 `data[].url` | | 参考图仍发到 generations | 改用 `/v1/images/edits` 文件上传 | | 依赖 mask 或 `seed` | 保留原模型，或重构工作流；当前路线不承诺支持 | ## 生产验收与错误处理 1. 对每个模型分别生成 1 张 `1:1` 1K 图，确认令牌、分组、价格与解析逻辑。 2. 再测试目标比例与 2K，读取图片真实尺寸并保存原始响应。 3. 编辑任务使用特征互不重复的非敏感测试图，逐张确认主体和标志性特征确实进入输出；只收到 HTTP 200 不算多图生效。 4. 超过参考图上限时不应重试：Quality 减为最多 2 张；标准模型减为最多 4 张。 5. 当前 `resolution=4k` 可能返回 HTTP 503，但这是参数不支持，不是暂时性服务故障；改为 `1k` 或 `2k`。 6. 对 `429` 和网络层错误使用带抖动的指数退避；对其他 `400`、`401`、`403` 先修正请求或账户状态。 7. 客户端超时后先查调用日志，再决定是否重发，避免同一任务重复计费。 HTTP 200 只证明请求被处理，不证明比例、参考图或业务约束都已满足。上线验收必须检查输出像素、图片内容、返回数组长度和控制台扣费记录。 ## 常见问题 ### Grok Imagine 2 的模型 ID 是什么？ 使用 `grok-imagine-image` 或 `grok-imagine-image-quality`。不要添加 `2`，例如 `grok-imagine-2-image` 不是本页提供的模型 ID。 ### 两个模型如何选择？ 日常素材和批量草稿先用 \$0.02/张的 `grok-imagine-image`；需要成片细节或参考图编辑时，再用 \$0.045/张的 `grok-imagine-image-quality` 做小样对比。最终选择应基于同一提示词、比例和分辨率的实际结果。 ### 1K 和 2K 是否同价？ 按本次上线价格，两档在老张API中同价并按生成张数计费。价格可能调整，批量任务开始前请到控制台复核。 ### 为什么只写 5 种宽高比？ 这是老张API当前文档化并承诺的接入范围，不是对 xAI 上游全部能力的描述。上游官方资料列有更多比例，但未列入本页的值需要先在当前令牌分组中验证。 ### 参考图编辑最多支持几张？ 按模型区分：`grok-imagine-image` 支持 1–4 张，`grok-imagine-image-quality` 支持 1–2 张。需要三图或四图组合时使用标准模型；需要 mask 局部重绘或更精确控制时，请评估 [GPT-Image-2](/api-capabilities/gpt-image-2)。 ### 生成结果应该怎样保存？ 使用 `url` 时在请求完成后尽快下载到自己的对象存储；需要直接嵌入或离线保存时使用 `b64_json`。不要依赖临时 URL 长期有效。 ## 来源与相关文档 * [xAI 多图编辑文档](https://docs.x.ai/developers/model-capabilities/images/multi-image-editing) — 上游多图编辑工作流与输入顺序 * [xAI Grok Imagine Image 标准模型](https://docs.x.ai/developers/models/grok-imagine-image) — 标准模型的 Image → Image 输入能力 * [xAI 图像生成文档](https://docs.x.ai/developers/model-capabilities/images/generation) — 上游比例、分辨率、批量和响应格式 * [xAI 模型与价格](https://docs.x.ai/developers/pricing) — 上游模型 ID 与官方价格；不等同于老张API售价 * [老张API图像接口参考](/api-reference/images) — 通用 Images API 请求与响应结构 * [老张API图像生成选型指南](/api-capabilities/image-generation-guide) — 跨模型比较与选择 * [老张API模型与价格](https://api2.laozhang.ai/account/pricing) — 当前分组、售价与实际扣费依据