跳转到主要内容
POST
文生图:根据文本提示词生成图片(官转)
🔒 需申请开通 GrokOfficial 分组:Grok Imagine 官转不在 Default 默认分组,需申请开通后才能调用(含本页 Playground)。未开通、或令牌计费模式为「按次计费」时,调用固定返回 503。申请流程见 Grok Imagine 官转概览 · 分组介绍。
右侧的交互式 Playground 支持直接在线调试。请在 Authorization 中填入你的 API Key(格式:Bearer sk-xxx),输入 prompt,选择模型、resolution、aspect_ratio(2.0 再选 quality)后一键发送即可。
场景说明:本页用于「文本生成图片」,每次 1 张。本通道暂不开放图片编辑,需要基于参考图改图或单次多张,请使用 Grok Imagine 官逆。
⚠️ 三个最容易踩的坑
  1. 用 resolution,不要用 size:size 不会被换算成分辨率档,传了会按默认 1k 出图和计费。
  2. 参数写错会报错:resolution / aspect_ratio 不在枚举内返回 422,quality: "high" 返回 400——这与官逆通道「静默回退」的行为相反。
  3. n 固定传 1:需要多张请并发发起多次请求。
图片 API 全部为同步调用:没有异步任务 ID,客户端断开连接结果即丢失、但请求仍会计费。grok-imagine-image-2.0 的 medium 档 2K 约 60–80 秒,建议客户端超时设到 360 秒,详见 图片 API 调用须知与最佳实践。

代码示例

Python(OpenAI SDK 直连)

Python(原生 requests)

cURL

Node.js(原生 fetch)

参数说明速查

每张单价(与 xAI 官网一致):
模型价格与官网对齐,且可能随官网调整;上表仅供参考,具体以顶部导航「模型价格」栏目为准:模型价格。

响应格式

  • data[] 里每项只有 url 或 b64_json 二选一,取决于 response_format。
  • 返回的图片链接请立即下载转存,不要长期引用。
  • usage 是占位值(prompt_tokens 恒为 1000 × 张数),不能用来核账,以控制台账单为准。
  • created 恒为 0,不要拿来计时。

相关文档

授权

Authorization
string
header
必填

在 API易控制台获取的 API Key(令牌分组需包含 GrokOfficial)

请求体

application/json
model
enum<string>
默认值:grok-imagine-image
必填

模型 ID:

  • grok-imagine-image —— 标准版,各分辨率均 $0.02/张
  • grok-imagine-image-quality —— 高质量版,1k / 1.5k / 2k 为 $0.05 / $0.06 / $0.07
  • grok-imagine-image-2.0 —— 新一代,low $0.04 / $0.05 / $0.06,medium $0.06 / $0.07 / $0.08
可用选项:
grok-imagine-image,
grok-imagine-image-quality,
grok-imagine-image-2.0
prompt
string
必填

提示词,支持中英文。建议详细描述主体、场景、风格、光线

示例:

"A photorealistic red wooden boat moored on a glassy alpine lake at dawn, mist over the water, snow-capped peaks behind, cinematic photography"

n
enum<integer>
默认值:1

出图数量。本通道固定为 1,需要多张请并发调用

可用选项:
1
resolution
enum<string>
默认值:1k

分辨率档位(小写),决定计费档:1k(默认)/ 1.5k / 2k。

枚举外的值(如 4k、1K)返回 422。不要用 size 代替,size 不会被换算成分辨率档。

可用选项:
1k,
1.5k,
2k
aspect_ratio
enum<string>
默认值:1:1

输出宽高比,默认 1:1。实测示例:grok-imagine-image 的 1k + 3:2 输出 1248×832;-quality 的 2k + 9:16 输出 1584×2816。

枚举外的值(如 5:7)返回 422。

可用选项:
1:1,
16:9,
9:16,
4:3,
3:4,
3:2,
2:3
quality
enum<string>

画质档,仅 grok-imagine-image-2.0 有效:low(默认)或 medium(单价高 $0.02,更慢)。

传 high 返回 400。另外两个模型不需要传。

可用选项:
low,
medium
response_format
enum<string>
默认值:url

返回格式:url(默认,图片链接,请立即下载转存)或 b64_json(纯 base64,不带 data: 前缀)

可用选项:
url,
b64_json

响应

成功生成图片

created
integer

恒为 0,不可用于计时

示例:

0

data
object[]

图片结果数组(本通道 1 项)

usage
object

占位值,不能用于核账。 prompt_tokens 恒为 1000 × 张数,真实扣费以控制台账单为准