Grok 生图

RootFlowAI 提供兼容 OpenAI Images API 的 Grok 文生图和参考图编辑服务。文生图调用 /v1/images/generations，图像编辑调用 /v1/images/edits，成功后都会收到 RootFlowAI CDN 图片 URL。

创建 API Key 时选择 Grok 绘图计次 分组。

可用模型

::: warning 文生图采用固定画布 当前两个模型的文生图实测均返回 1280x720 JPEG。请求中的 size、resolution 和 aspect_ratio 不会改变最终像素或宽高比，因此不要把这两个模型当作可控 1K、2K 或竖图模型使用。

建议新请求省略 size 和 extra_fields。为避免把不支持的规格静默降级，任一请求边超过 2048，或传入 resolution=4k，仍会直接返回 400。

参考图编辑不使用这个固定文生图画布，输出比例通常会跟随输入图片；具体说明见下方“参考图编辑”。

快速开始

curl

curl https://api.rootflowai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "广角香港维多利亚港城市天际线，真实自然日光，无文字，无水印",
    "n": 1
  }'

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxxxxxxxx",
    base_url="https://api.rootflowai.com/v1",
)

response = client.images.generate(
    model="grok-imagine-image-quality",
    prompt="现代滨海城市天际线，商业摄影质感，画面通透，无文字",
    n=1,
)

print(response.data[0].url)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxxxxxxxxxxxxx",
  baseURL: "https://api.rootflowai.com/v1",
});

const response = await client.images.generate({
  model: "grok-imagine-image-quality",
  prompt: "现代滨海城市天际线，商业摄影质感，画面通透，无文字",
  n: 1,
});

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

请求参数

::: tip 两个模型必须通过模型名区分 不要用 quality=high 代替 grok-imagine-image-quality。标准模型和质量模型是两个独立模型，必须在 model 字段中明确选择。

固定画布兼容行为

旧客户端如果必须发送 size，可以继续使用不超过 2048x2048 的正整数尺寸，但返回图片仍为 1280x720。extra_fields.resolution 和 extra_fields.aspect_ratio 同样不控制实际输出，不建议在新代码中使用。

需要可控 1K、2K、4K 或竖图输出时，请改用 图像生成 中对应规格的计次模型，或使用 超分生图。

响应格式

成功响应兼容 OpenAI Images API：

{
  "created": 1786553296,
  "data": [
    {
      "url": "https://cdn.rootflowai.com/images/2026-08-13/example.jpg"
    }
  ]
}

图片已经转存到 RootFlowAI CDN。文生图当前为 1280x720 JPEG；建议下载后自行持久化，并始终读取文件的真实像素和 MIME 类型。

参考图编辑

图像编辑会尽量保留参考图的主体、构图、姿势和背景，再按提示词完成修改。这是生成式编辑，模型会重新生成整张画面，不能保证身份和局部细节完全不变，也不等同于传统图像软件的原像素局部修改。

::: warning 编辑画布与参数 参考图编辑当前只有 model、prompt、image / images 和 n 参与上游请求。size、quality、style、response_format 不会控制编辑结果；需要使用质量模型时，请直接把 model 设置为 grok-imagine-image-quality。

输出通常会参考输入图片的长宽比，但不会保持输入图片的原始像素尺寸。请始终以返回图片的真实像素为准。

本地文件

使用 OpenAI Images Edit 兼容的 multipart 请求上传 JPEG、PNG 或 WebP 文件：

curl https://api.rootflowai.com/v1/images/edits \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -F "model=grok-imagine-image" \
  -F "prompt=仅把中央人物的上衣改成红色，其他内容保持不变" \
  -F "image=@reference.jpg"

Adapter 会把上传文件转换成上游要求的 JSON Data URI，客户端不需要自行转换。

URL 或 Data URI

也可以直接向 /v1/images/edits 发送 JSON。image.url 接受上游可访问的 HTTPS URL 或 Base64 Data URI：

{
  "model": "grok-imagine-image-quality",
  "prompt": "保持商品形状和构图，仅将外壳改为红色",
  "image": {
    "url": "https://example.com/reference.jpg",
    "type": "image_url"
  }
}

多张参考图使用 images 数组，每个元素都使用上面的 url 对象格式。multipart 请求则可以重复传入多个 image 字段。

限制与错误处理

• 参考图编辑支持单图和多图，当前不支持 mask 遮罩局部编辑。
• 文生图支持 n=1-10；参考图编辑当前只支持 n=1。
• 文生图当前固定返回 1280x720，size、resolution 和 aspect_ratio 不控制输出规格。
• 未知模型、空提示词、文生图 n 超出 1-10，或编辑请求 n 不是 1 时会返回 400 invalid_request_error。
• 文生图任一请求边超过 2048，或传入 resolution=4k 时会返回 400 invalid_request_error。
• 生图通常需要数秒到几十秒，客户端请求超时建议设置为 120 秒以上。
• 如果连接在响应返回前中断，不要自动重试。上游可能已经开始生成，自动重试可能造成重复任务和重复计费。

需要 4K 输出时，请改用 图像生成 中对应分辨率档位的计次模型，或使用 超分生图。