Grok · xAI 官方生图协议

知梦 Grok 生图采用 xAI 官方图片生成与编辑协议。当前开放 grok-imagine-image 与 grok-imagine-image-2.0，所有请求使用知梦 API Key。

1. 接口与鉴权

REST Base URL：

text

https://api.zmoapi.cn

OpenAI SDK Base URL：

text

https://api.zmoapi.cn/v1

请求头：

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

接口：

http

POST /v1/images/generations
POST /v1/images/edits

2. 模型与价格

模型	模型 ID	分辨率	`quality`	单价
Grok Imagine Image	`grok-imagine-image`	`1k` / `2k`	不支持	¥0.1 / 张
Grok Imagine Image 2.0	`grok-imagine-image-2.0`	`1k` / `2k`	`auto` / `low` / `medium`	¥0.1 / 张

两个模型均不支持 4k。费用按实际生成的图片张数计算。例如 n: 4 表示一次请求生成 4 张图片，按 4 张计费。

3. 文生图

接口：

http

POST /v1/images/generations

cURL

bash

curl 'https://api.zmoapi.cn/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "model": "grok-imagine-image",
    "prompt": "极简产品摄影，一台透明外壳的复古收音机置于浅灰背景，柔和棚拍光",
    "aspect_ratio": "4:3",
    "resolution": "1k",
    "n": 1,
    "response_format": "url"
  }'

JavaScript · OpenAI SDK

文生图接口可以使用 OpenAI SDK：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZHM_API_KEY,
  baseURL: "https://api.zmoapi.cn/v1"
});

const result = await client.images.generate({
  model: "grok-imagine-image",
  prompt: "一座位于雪山脚下的玻璃图书馆，清晨，真实摄影风格",
  aspect_ratio: "16:9",
  resolution: "1k",
  n: 1,
  response_format: "url"
});

console.log(result.data[0].url);

Python · OpenAI SDK

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.zmoapi.cn/v1",
)

result = client.images.generate(
    model="grok-imagine-image",
    prompt="一座位于雪山脚下的玻璃图书馆，清晨，真实摄影风格",
    extra_body={
        "aspect_ratio": "16:9",
        "resolution": "1k",
    },
    n=1,
    response_format="url",
)

print(result.data[0].url)

如果当前 OpenAI SDK 的类型定义还没有包含 aspect_ratio 或 resolution，JavaScript 可使用类型扩展或直接 HTTP 请求，Python 可像上例一样放入 extra_body。

4. 文生图参数

字段	类型	必填	说明
`model`	string	是	使用 `grok-imagine-image` 或 `grok-imagine-image-2.0`
`prompt`	string	是	图片生成提示词
`n`	integer	否	生成数量，范围 1–10，默认 1
`aspect_ratio`	string	否	输出宽高比，默认 `auto`
`resolution`	string	否	`1k` 或 `2k`，默认 `1k`
`quality`	string	否	仅 `grok-imagine-image-2.0` 支持：`auto`、`low`、`medium`；默认 `auto`
`response_format`	string	否	`url` 或 `b64_json`，默认 `url`
`user`	string	否	调用方的终端用户标识，可用于风控追踪

`quality` 行为

quality 仅适用于 grok-imagine-image-2.0。省略或设置为 auto 时，当前文生图使用 low，图片编辑使用 medium，并按实际采用的质量处理。需要固定质量时显式传入 low 或 medium。调用 grok-imagine-image 时不要发送此字段。

json

{
  "model": "grok-imagine-image-2.0",
  "prompt": "一幅清晨海边灯塔的水彩画",
  "resolution": "2k",
  "quality": "medium"
}

5. 支持的宽高比

参数值	常见用途
`auto`	让模型根据提示词自动选择
`1:1`	头像、商品图、通用正方形图片
`16:9` / `9:16`	横屏、手机竖屏、故事封面
`4:3` / `3:4`	演示图、常规横版与竖版
`3:2` / `2:3`	摄影画幅
`2:1` / `1:2`	横幅与长竖图
`19.5:9` / `9:19.5`	现代手机画幅
`20:9` / `9:20`	现代手机画幅
`21:9`	电影宽屏
`5:2`	超宽横幅

不要使用 1024x1024 这类像素字符串代替 aspect_ratio。Grok 官方协议使用比例与分辨率两个独立字段。

6. 单图编辑

单张参考图使用 image。图片可以是公网 URL、Base64 Data URI，或者知梦接口实际支持的文件引用。

公网 URL

bash

curl 'https://api.zmoapi.cn/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "model": "grok-imagine-image",
    "prompt": "保留主体结构，将画面改成精细的铅笔素描",
    "image": {
      "type": "image_url",
      "url": "https://example.com/source.png"
    },
    "resolution": "1k",
    "n": 1,
    "response_format": "url"
  }'

单图编辑会自动使用输入图片的比例，不要发送 aspect_ratio。

Base64 Data URI

image.url 可以直接传完整 Data URI：

json

{
  "model": "grok-imagine-image",
  "prompt": "将背景替换为夜晚的城市天台",
  "image": {
    "type": "image_url",
    "url": "data:image/png;base64,iVBORw0KGgoAAA..."
  },
  "response_format": "url"
}

这里必须包含 data:image/...;base64, 前缀，不能只传裸 Base64。

7. 多图编辑

grok-imagine-image-2.0 支持多图编辑。多张参考图使用 images，最多 5 张。数组顺序就是参考图编号顺序，可在提示词中使用 <IMAGE_0>、<IMAGE_1> 等名称明确图片用途。

bash

curl 'https://api.zmoapi.cn/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "model": "grok-imagine-image-2.0",
    "prompt": "使用 <IMAGE_0> 的商品主体、<IMAGE_1> 的场景和 <IMAGE_2> 的配色，生成一张统一的16:9宣传图",
    "images": [
      { "type": "image_url", "url": "https://example.com/product.png" },
      { "type": "image_url", "url": "https://example.com/scene.jpg" },
      { "type": "image_url", "url": "https://example.com/colors.webp" }
    ],
    "aspect_ratio": "16:9",
    "resolution": "1k",
    "n": 1,
    "response_format": "url"
  }'

多图编辑默认跟随第一张图片的比例，也可以通过 aspect_ratio 覆盖。

8. 本地图片编辑

Grok 官方图片编辑接口不接收 multipart 文件。客户端应读取本地文件并转换为 Data URI，再作为 JSON 发送。

JavaScript

import { readFile } from "node:fs/promises";

const image = await readFile("./source.png");
const dataUri = `data:image/png;base64,${image.toString("base64")}`;

const response = await fetch("https://api.zmoapi.cn/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ZHM_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "grok-imagine-image",
    prompt: "保留人物姿态，将服装改成深蓝色西装",
    image: { type: "image_url", url: dataUri },
    resolution: "1k",
    response_format: "url"
  })
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message || `HTTP ${response.status}`);
console.log(result.data[0].url);

Python

python

import base64
import requests

with open("source.png", "rb") as file:
    encoded = base64.b64encode(file.read()).decode("ascii")

response = requests.post(
    "https://api.zmoapi.cn/v1/images/edits",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "grok-imagine-image",
        "prompt": "保留人物姿态，将服装改成深蓝色西装",
        "image": {"type": "image_url", "url": f"data:image/png;base64,{encoded}"},
        "resolution": "1k",
        "response_format": "url",
    },
    timeout=300,
)

payload = response.json()
response.raise_for_status()
print(payload["data"][0]["url"])

9. 参考图要求

支持 JPEG、PNG、WebP；
公网 URL 必须能由服务端直接访问并返回图片文件；
URL 不能依赖浏览器 Cookie、登录状态或防盗链请求头；
不要传网页分享地址或 Markdown 链接；
Base64 输入必须是完整 Data URI；
单张参考图使用 image，多张使用 images，两者不要同时出现；图片对象使用 type: "image_url" 并在 url 中传入公网地址或 Data URI；
grok-imagine-image 使用单张参考图；grok-imagine-image-2.0 多图编辑最多使用 5 张参考图。

10. URL 返回

默认或显式传入：

json

{
  "response_format": "url"
}

响应示例：

json

{
  "data": [
    {
      "url": "https://cdn.example.com/generated-image.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

读取：

text

data[].url

返回 URL 可能是临时地址。收到响应后应尽快下载或转存到自己的对象存储。

11. Base64 返回

请求：

json

{
  "response_format": "b64_json"
}

响应示例：

json

{
  "data": [
    {
      "b64_json": "BASE64_IMAGE_DATA",
      "mime_type": "image/jpeg"
    }
  ]
}

data[].b64_json 不包含 Data URI 前缀。展示图片时可以结合 mime_type 构造：

const src = `data:${item.mime_type || "image/jpeg"};base64,${item.b64_json}`;

12. 图片编辑参数

字段	类型	必填	说明
`model`	string	是	使用 `grok-imagine-image` 或 `grok-imagine-image-2.0`
`prompt`	string	是	描述需要执行的编辑
`image`	object	条件	单张参考图，与 `images` 二选一
`images`	object[]	条件	仅 `grok-imagine-image-2.0` 多图编辑使用；2–5 张，与 `image` 二选一
`aspect_ratio`	string	否	多图编辑输出比例；单图编辑请省略
`resolution`	string	否	`1k` 或 `2k`
`quality`	string	否	仅 `grok-imagine-image-2.0` 支持：`auto`、`low`、`medium`；默认 `auto`
`n`	integer	否	输出数量，范围 1–10
`response_format`	string	否	`url` 或 `b64_json`
`user`	string	否	调用方终端用户标识

13. 常见错误

HTTP	常见原因	处理方式
`400`	JSON、参数值、参考图结构或图片格式错误	检查请求体和服务端返回的错误消息
`401`	API Key 缺失或无效	检查 Bearer Token
`403`	当前密钥没有模型权限	联系知梦确认分组与模型权限
`404`	Base URL、路径或模型名错误	检查接口地址和所选 Grok 模型 ID
`422`	缺少必填字段或字段无法处理	检查 `prompt`、`image` / `images` 等字段
`429`	余额、并发或频率限制	降低并发并按服务端提示稍后重试
`500/502/503`	服务或上游暂时不可用	记录 Request ID 与错误原文后排查

调用失败时优先展示服务端返回的 error.message、message 和 Request ID，不要只显示固定文案。

14. 重要规则

模型名必须是 grok-imagine-image 或 grok-imagine-image-2.0。
两个模型的 resolution 只支持 1k 和 2k，不要发送 4k。
quality 只适用于 grok-imagine-image-2.0。
文生图使用 /v1/images/generations，图片编辑使用 /v1/images/edits。
两个接口都使用 JSON；图片编辑不要发送 multipart。
单图使用 image；grok-imagine-image-2.0 多图编辑使用 images，最多 5 张。
本地图片需要转换为完整 Base64 Data URI。
单图编辑省略 aspect_ratio；多图编辑可以显式指定。
response_format: "url" 读取 data[].url；b64_json 读取 data[].b64_json。
n 每增加 1 就会多生成并计费 1 张图片。
创建请求发生超时或断连时，不要无条件自动重试，以免重复生成和重复计费。
API Key 只放在服务端环境变量或安全配置中，不要提交到前端代码或公开仓库。

Grok · xAI 官方生图协议 ​

1. 接口与鉴权 ​

2. 模型与价格 ​

3. 文生图 ​

cURL ​

JavaScript · OpenAI SDK ​

Python · OpenAI SDK ​

4. 文生图参数 ​

quality 行为 ​

5. 支持的宽高比 ​

6. 单图编辑 ​

公网 URL ​

Base64 Data URI ​

7. 多图编辑 ​

8. 本地图片编辑 ​

JavaScript ​

Python ​

9. 参考图要求 ​

10. URL 返回 ​

11. Base64 返回 ​

12. 图片编辑参数 ​

13. 常见错误 ​

14. 重要规则 ​

15. 相关页面 ​

Grok · xAI 官方生图协议

1. 接口与鉴权

2. 模型与价格

3. 文生图

cURL

JavaScript · OpenAI SDK

Python · OpenAI SDK

4. 文生图参数

`quality` 行为

5. 支持的宽高比

6. 单图编辑

公网 URL

Base64 Data URI

7. 多图编辑

8. 本地图片编辑

JavaScript

Python

9. 参考图要求

10. URL 返回

11. Base64 返回

12. 图片编辑参数

13. 常见错误

14. 重要规则

15. 相关页面