Skip to main content
POST
文生图:根据文本提示词生成图片
右侧的交互式 Playground 支持直接在线调试。请在 Authorization 中填入你的 API Key(格式:Bearer sk-xxx),输入 prompt、选择 aspect_ratio / resolution 后一键发送即可。
场景说明:本页用于「文本生成图片」,只需提示词,无需上传任何图片。如果你要基于现有图片做修改、或做多图融合,请使用 图片编辑接口
⚠️ 不要把参考图传到这个端点本端点传入 image / image_url / images 不会报错,会返回 200 并按提示词生成一张全新的图——参考图被静默丢弃,且照常计费由于没有任何错误信号,这个问题往往要到发现「出的图和输入图毫无关系」时才被察觉。只要涉及参考图,一律走 /v1/images/edits
⚠️ 参数写错不会报错非法的 aspect_ratio(如 5:7)、resolution(如 1K1024x1024)、response_format(如 base64)都会静默回退默认值并正常出图。拿到的图不符合预期时,请先检查参数拼写——注意 resolution 是小写 1k / 2k唯一例外:resolution: "4k" 返回 503 model_service_unavailable,这是该档位不支持而非渠道故障,重试无效。
图片 API 全部为同步调用:没有异步任务 ID,客户端断开连接结果即丢失、但请求仍会计费。1K 出图约 9 秒、2K 约 15–17 秒,建议客户端超时设到 360 秒,详见 图片 API 调用须知与最佳实践

代码示例

Python(OpenAI SDK 直连)

Python(原生 requests)

cURL

Node.js(原生 fetch)

浏览器 JavaScript

参数说明速查

各宽高比的实际输出像素
不支持 seed(传了不报错也不生效,结果不可复现)、不支持 mask。size / quality / style 等 OpenAI 习惯字段会被静默忽略。

响应格式

响应字段陷阱
  • data[] 每项只有 urlb64_json 二选一,取决于 response_format,不会同时出现。
  • 不返回 revised_prompt,也没有 respect_moderation / model 等字段,解析时不要假设它们存在。
  • b64_json纯 base64,不带 data:image/...;base64, 前缀,可直接 base64.b64decode
  • created 恒为 0,不能当时间戳用。
  • n > 1data 数组有多项,别只取 data[0]
usage 不能用来核账prompt_tokens 恒为 1000 × n,与提示词实际长度无关,是占位值。本系列按次固定计费($0.02 / $0.045 一张),真实扣费请以 API易 控制台账单为准。

授权

Authorization
string
header
必填

在 API易控制台获取的 API Key

请求体

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

模型 ID。quality 版画质更高、价格更贵

可用选项:
grok-imagine-image,
grok-imagine-image-quality
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
integer
默认值:1

生成图片数量,取值 1–10。传 11 及以上返回 400;传 0 静默按 1 处理

必填范围: 1 <= x <= 10
示例:

1

aspect_ratio
enum<string>
默认值:1:1

输出宽高比。各比例在两档分辨率下的实际像素:

传入枚举外的值不会报错,会静默按默认 1:1 处理。

可用选项:
1:1,
16:9,
9:16,
4:3,
3:4
示例:

"16:9"

resolution
enum<string>
默认值:1k

输出分辨率档位。1k 约 0.9–1.05 兆像素、输出 JPEG; 2k 约 4.2–4.5 兆像素、输出 PNG(单张 5–6 MB)。两档同价。

4k 会返回 503;传其它非法值(如 1K1024x1024)静默按 1k 处理。

可用选项:
1k,
2k
示例:

"1k"

response_format
enum<string>
默认值:url

返回格式。url 返回图片直链(无签名参数); b64_json 返回纯 base64 字符串(不带 data: 前缀)。

传入非法值静默回退为默认的 url

可用选项:
url,
b64_json
示例:

"url"

响应

成功生成图片

created
integer

创建时间戳。本模型恒返回 0,不可用于计时

示例:

0

data
object[]

图片结果数组,长度等于请求的 n

usage
object

占位值,不能用于核账。 prompt_tokens 恒为 1000 × n,与实际提示词长度无关。 真实扣费以控制台账单为准。