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,与实际提示词长度无关。 真实扣费以控制台账单为准。