Grok Imagine 2 生圖/編輯 - API易文档中心

概述

Grok Imagine 2 是 xAI 最新發布的第二代影像生成模型，相比初代在引數可控性與編輯能力上是整代升級：寬高比與解析度引數真實生效、2K 檔可用、單次最多出 10 張、參考圖編輯能真正保留原圖特徵。 API易提供 grok-imagine-image（標準）與 grok-imagine-image-quality（高品質）兩個型號，共用同一套介面與引數，區別只在畫質檔位與價格。

核心亮點：按次固定計費（1K 與 2K 同價），5 種寬高比 × 2 檔解析度引數真實生效，單次最多出 10 張，參考圖編輯保真度高（畫風、構圖、配色、主體身份都能保留）。1K 出圖約 9 秒。

模型 ID 裡不帶 2。產品代號叫 Grok Imagine 2，但呼叫時的模型名是 grok-imagine-image 和 grok-imagine-image-quality——不要寫成 grok-imagine-2-image，那樣會因模型不存在而返回 503。

📌 上手前必看的一條：參考圖只能傳給編輯介面 /v1/images/edits，不能傳給文生圖介面。給 /v1/images/generations 傳 image / image_url / images 會返回 200 並正常出圖，但參考圖被靜默丟棄、且照常計費——沒有任何錯誤提示。詳見下方端點一覽。

圖片 API 全部為同步呼叫：沒有非同步任務 ID，客戶端斷開連線結果即丟失、但請求仍會計費。請為本模型設定足夠大的 timeout，詳見圖片 API 呼叫須知與最佳實踐。

文生圖 API

輸入文本提示詞生成圖片，帶互動式 Playground 線上除錯。

圖片編輯 API

上傳參考圖 + 編輯指令生成新圖，支援 1–3 張多圖融合，帶 Playground。

為什麼選 API易的 Grok Imagine 2

OpenAI 相容格式

走標準 /v1/images/generations 與 /v1/images/edits，請求體與響應欄位與 OpenAI Images API 一致，可直接用 OpenAI SDK 呼叫，遷移零改造。

不限併發 · 企業可放量

沒有 RPM/RPD 硬限制，實測 100 RPM 無壓力，渠道資源充足，批量出圖可線性放大，無需申請配額或自建限流。

按次計費 · 成本可預測

固定單價、不區分解析度，出 2K 與出 1K 同價，預算可精確到張，疊加充值加贈活動進一步降低成本。

全球零門檻接入

無需海外伺服器或代理，國內機房、家寬網路、海外節點均可直連 api.apiyi.com，免去出海改造。

模型生態齊全

影像側還有 Nano Banana 2、GPT-Image-2、Seedream、FLUX 可按場景組合；文本側有 Grok 系列。

專業服務 · 企業陪跑

團隊深耕影像生成場景，具備豐富的選型、調優與整合經驗，可為企業客戶提供從 PoC 到生產上線的完整技術支援。

核心特性

雙檔解析度

1k 約 1 兆畫素、2k 約 4.2–4.5 兆畫素（16:9 達 2816×1584），兩檔同價

5 種寬高比

1:1 / 16:9 / 9:16 / 4:3 / 3:4，實測畫素與請求值精確吻合

單次最多 10 張

n 支援 1–10，一次請求返回多張，適合批次選圖

出圖快

1K 約 9 秒、2K 約 15–17 秒；併發下延遲穩定，100 RPM 無壓力

真參考圖編輯

改指定部分、其餘逐畫素保留——畫風、構圖、配色、主體身份都不走樣

多圖融合

編輯介面支援 1–3 張參考圖，可把 A 圖的主體放進 B 圖的場景與畫風

雙返回格式

url 直鏈或 b64_json 純 base64，兩個端點都支援

OpenAI SDK 直連

client.images.generate() / client.images.edit() 直接可用，無需自己拼 HTTP

模型定價

模型	計費方式	API易定價	說明
`grok-imagine-image`	按次固定價	$0.02 / 張	標準版，日常出圖首選
`grok-imagine-image-quality`	按次固定價	$0.045 / 張	高品質版，對畫質要求更高時用

計費說明

不區分解析度：1k 與 2k 同價，出 2K 不額外加錢。
按張計費：n=4 即按 4 張計費，與提示詞長度無關。
編輯與文生圖同價：走 /v1/images/edits 不額外收費。
響應體裡的 usage 不能用來核賬：prompt_tokens 恆為 1000 × n，是佔位值，真實扣費以控制台賬單為準。

分組介紹

Grok Imagine 2 在 Default 預設分組（1.0x 倍率），與上方定價表一致，無需切換分組即可呼叫。 令牌「計費模式」推薦：選 按量優先（Pay-as-you-go Priority）—— 本系列是按次計費模型，按量優先與按次計費都能正常路由，選按量優先可以讓同一把令牌相容站內其它按 token 計費的模型。

如果你的令牌還覆蓋其它影像模型，保持主分組 Default 即可，本系列不需要任何專屬分組或額外配置。

技術規格

專案	規格
模型 ID	`grok-imagine-image`、`grok-imagine-image-quality`
寬高比	5 種：`1:1` / `16:9` / `9:16` / `4:3` / `3:4`
解析度檔位	`1k`（約 0.9–1.05 MP）、`2k`（約 4.2–4.5 MP）
輸出格式	1K 為 JPEG（約 220–300 KB）、2K 為 PNG（約 5–6 MB）
單次張數	`n` 1–10
參考圖	編輯介面 1–3 張（`image[]` 重複傳入）
mask 局部重繪	❌ 不支援
`seed` 可復現	❌ 不支援，結果不可復現
`revised_prompt` 回顯	❌ 不返回
出圖耗時	1K 約 9 秒、2K 約 15–17 秒
併發 / 速率	不限併發，實測 100 RPM 無壓力
建議客戶端超時	≥ 360 秒

端點一覽

功能	方法	路徑	Content-Type
文生圖	`POST`	`/v1/images/generations`	`application/json`
圖片編輯	`POST`	`/v1/images/edits`	`multipart/form-data`
對話式出圖	`POST`	`/v1/chat/completions`	`application/json`

✅ 編輯介面必須用 multipart/form-data 檔案上傳傳送 JSON 到 /v1/images/edits 會固定返回 400：

request Content-Type isn't multipart/form-data

這條對照著上游廠商文件接入的客戶尤其重要——上游文件寫的是 JSON + 公網圖片 URL 的形式，但在 API易閘道上走不通，請以本站文件為準：用 -F "[email protected]" 上傳檔案。完整示例見圖片編輯 API。檔案欄位名只能是 image 或 image[]，寫成 images / image_file 會返回 415。

⚠️ 參考圖不要傳給文生圖介面/v1/images/generations 收到 image / image_url / images 時不會報錯，而是返回 200 並按提示詞重新生成一張全新的圖，參考圖被完全忽略，並且照常計費。由於沒有任何錯誤訊號，這類問題往往要到發現”出的圖和輸入圖毫無關係”時才被察覺。只要涉及參考圖，一律走 /v1/images/edits。

主域名 https://api.apiyi.com，備用域名 https://vip.apiyi.com。對話式出圖（/v1/chat/completions）可用但不主推，詳見下方常見問題。

從 GPT-Image-2 遷移

如果你已經接入了 GPT-Image-2，端點和呼叫方式完全一樣（/v1/images/generations + /v1/images/edits，OpenAI SDK 直連），但引數體系是另一套，直接換模型名跑不通。下面是必須改的地方。

引數對照

維度	GPT-Image-2	Grok Imagine 2	遷移動作
輸出尺寸	`size`（`1536x1024` 等具體畫素）	`aspect_ratio` + `resolution`	必須改寫，且 `size` 傳了不報錯
畫質檔位	`quality`（`low`/`medium`/`high`/`auto`）	無此引數，用模型名區分	刪掉 `quality`，改選 `-quality` 型號
輸出格式	`output_format`（png/jpeg/webp）+ `output_compression`	無此引數，格式由解析度決定	刪掉；1K 固定 JPEG、2K 固定 PNG
背景	`background`（`opaque`/`auto`）	無此引數	刪掉
稽核強度	`moderation`（`auto`/`low`）	無此引數	刪掉
高保真	禁傳 `input_fidelity`	無此引數	刪掉
單次張數	`n` 僅支援 1	`n` 支援 1–10	✅ 可以去掉客戶端的併發出圖迴圈
編輯參考圖上限	16 張	3 張	⚠️ 超過 3 張要改邏輯
mask 局部重繪	✅ 支援	❌ 不支援	⚠️ 依賴 mask 的流程無法遷移
計費	按 token（high 檔約 $0.21/張）	按次固定 $0.02 / $0.045	預算模型從”按量”變”按張”

三個最容易踩的坑

1. 響應格式預設值是反的 —— 這條最容易漏GPT-Image-2 只返回 b64_json（沒有 url），而 Grok Imagine 2 預設返回 url。如果你的解析程式碼寫的是 resp.data[0].b64_json，遷移後會拿到 None / undefined。兩個解法，二選一：

保持原始碼不動 → 顯式傳 "response_format": "b64_json"
改用直鏈 → 讀 data[0].url 再下載

另外 GPT-Image-2 的 usage 是真實 token 數，Grok Imagine 2 的 usage 是佔位值（恆為 1000 × n）——如果你有基於 usage 做成本統計的指令碼，遷移後會算出錯誤的數字。

2. size 傳了不會報錯，只會靜默失效GPT-Image-2 的引數校驗是嚴格的，傳錯通常直接 400。Grok Imagine 2 的校驗很寬鬆：size、quality、style 這些 OpenAI 習慣欄位傳進來一律靜默忽略，非法的 aspect_ratio / resolution 也會靜默回退預設值。也就是說，如果你只把 model 改了、size: "1536x1024" 忘了刪，請求會返回 200 並出一張 1024×1024 的方圖——沒有任何報錯提示你引數沒生效。遷移後請先用一次呼叫核對輸出畫素，確認 aspect_ratio / resolution 真的生效了。

3. 參考圖不能再傳給文生圖介面這是本模型獨有的坑：給 /v1/images/generations 傳參考圖會 200 出圖但靜默丟棄參考圖並照常計費。任何涉及參考圖的呼叫都必須走 /v1/images/edits（multipart/form-data），詳見上方端點一覽。

遷移前後程式碼對照

# 遷移前：GPT-Image-2
resp = client.images.generate(
    model="gpt-image-2",
    prompt="賽博朋克城市雨夜",
    size="1536x1024",           # ← 刪掉
    quality="high",             # ← 刪掉
    output_format="jpeg"        # ← 刪掉
)
img = base64.b64decode(resp.data[0].b64_json)

# 遷移後：Grok Imagine 2
resp = client.images.generate(
    model="grok-imagine-image",           # 高畫質用 grok-imagine-image-quality
    prompt="賽博朋克城市雨夜",
    n=1,
    extra_body={
        "aspect_ratio": "16:9",           # ← 取代 size
        "resolution": "1k",               # ← 取代 quality 的尺寸含義
        "response_format": "b64_json"     # ← 顯式指定，保持解析程式碼不變
    }
)
img = base64.b64decode(resp.data[0].b64_json)

該選哪個？ 需要 mask 局部重繪、精確到畫素的自定義尺寸、或 16 張參考圖融合 → 繼續用 GPT-Image-2。想要成本可預測（按張固定價、2K 不加價）、單次多圖（n 最多 10）、或編輯時高度保留原圖 → 用 Grok Imagine 2。兩者共存不衝突，同一把令牌都能調。

關鍵引數詳解

`aspect_ratio` 與 `resolution`（輸出尺寸）

兩個引數組合決定實際輸出畫素。下表為實測值，與請求值精確吻合：

`aspect_ratio`	`resolution: 1k`	`resolution: 2k`
`1:1`	1024×1024	2048×2048
`16:9`	1280×720	2816×1584
`9:16`	720×1280	1584×2816
`4:3`	1152×864	2368×1776
`3:4`	864×1152	1776×2368

這兩個引數只在文生圖介面生效。 在編輯介面 /v1/images/edits 上傳入不會報錯，但也不起作用——編輯結果的畫幅跟隨輸入參考圖（輸入 1280×720 就輸出 1280×720）。需要改變畫幅請先自行裁剪參考圖。

引數校驗很寬鬆，寫錯不會報錯：傳入列舉外的 aspect_ratio（如 5:7、21:9）或 resolution（如 1K、1024x1024）都會靜默回退預設值並正常出圖。response_format 傳非法值同樣靜默回退為 url。所以拿到的圖不符合預期時，先檢查引數拼寫。唯一的例外是 resolution: "4k" —— 它會返回 503 model_service_unavailable，這是該檔位不支援，不是渠道故障，改回 1k / 2k 即可。

`n`（單次出圖數量）

取值 1–10，返回的 data 陣列長度等於 n，按張計費。傳 0 會靜默按 1 處理；傳 11 及以上返回 400。

最佳實踐

先明確是「生成」還是「編輯」

沒有參考圖 → /v1/images/generations；有參考圖（哪怕只是想微調一處）→ /v1/images/edits。選錯端點不會報錯，只會拿到不符預期的圖。

客戶端超時設到 360 秒

圖片 API 是同步呼叫，2K 出圖約 15–17 秒，高峰或冷啟動時可能更久。按 60 秒配置會產生大量誤超時，而請求實際仍在計費。

用 aspect_ratio 控制構圖，不要寫進提示詞

引數是真實生效的，直接傳 aspect_ratio: "16:9" 比在提示詞裡寫「橫版構圖」可靠得多。

按頻寬選擇解析度檔

2K 是 PNG 無損、單張 5–6 MB，1K 是 JPEG、單張 220–300 KB，相差約 20 倍。移動端或需要批量回傳的場景優先 1K——反正兩檔同價，選擇只取決於畫質與頻寬的權衡。

編輯時明確寫「其餘保持不變」

編輯指令建議寫成「把圍巾改成紅色，其餘部分完全保持不變」這種形式，模型對這類約束遵循度很好，能最大限度保留原圖。

多圖融合時在提示詞裡顯式指代

image[] 的上傳順序就是「圖1 / 圖2 / 圖3」，在提示詞裡寫明「把圖1的主體放進圖2的場景」，比讓模型自己猜要穩。

不要依賴 seed 做復現

本系列不支援 seed，同一提示詞兩次呼叫結果不同。需要固定素材請把出圖結果存下來，而不是指望重跑復現。

批量出圖直接併發

沒有併發限制，實測 100 RPM 無壓力，渠道資源充足。不需要自建佇列序列化，也不用額外申請配額。

錯誤碼與重試

HTTP	code	含義	處理建議
`400`	`invalid_image_request`	編輯介面收到了 JSON 而非 multipart	改用 `multipart/form-data` 檔案上傳，不要重試
`400`	`invalid_request`	引數非法或提示詞被內容稽核攔截	兩者同碼，先自查引數；引數無誤則調整提示詞
`415`	—	編輯介面的檔案欄位名不受支援	欄位名改為 `image` 或 `image[]`
`429`	—	頻率超限或額度不足	指數退避重試，並檢查賬戶餘額
`503`	`model_service_unavailable`	引數檔位不支援（如 `resolution: 4k`）	不是渠道故障，改回 `1k` / `2k`，不要重試
`503`	—	當前分組無可用渠道	檢查令牌分組配置，見上方「分組介紹」

客戶端建議：400 與 415 是確定性錯誤，重試沒有意義，應直接告警。只有 429 和網路層超時值得重試，建議指數退避、最多 3 次。注意 400 invalid_request 同時承載「引數錯誤」和「內容被稽核攔截」兩種語義，錯誤體無法區分。經驗判據是耗時：被稽核攔截通常在 5–6 秒返回，比正常出圖（約 9 秒）更快，因為攔截髮生在生成之前。

常見問題

為什麼我按廠商文件發 JSON 到 /v1/images/edits 就報 400？

因為 API易閘道的編輯介面只接受 multipart/form-data，而上游廠商文件寫的是 JSON + 公網圖片 URL 的形式。這兩種口徑不一致，請以本站文件為準。正確寫法是檔案上傳：

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=grok-imagine-image" \
  -F "prompt=把圍巾改成紅色，其餘保持不變" \
  -F "[email protected]"

好處是不需要圖床——直接傳本地檔案即可，比公網 URL 的方式更省事。完整示例見圖片編輯 API。

我給文生圖介面傳了參考圖，返回 200 但圖完全不對？

這是預期行為，也是本模型最容易踩的坑：/v1/images/generations 收到 image / image_url / images 時會靜默忽略它們，只按提示詞重新生成，並且照常計費。因為沒有任何錯誤訊號，很容易誤以為”編輯功能有問題”。只要涉及參考圖，請改用 /v1/images/edits。

編輯介面傳了 resolution / aspect_ratio 為什麼不生效？

編輯介面的輸出畫幅跟隨輸入參考圖：輸入 1280×720 就輸出 1280×720，輸入 1024×1024 就輸出 1024×1024。resolution 與 aspect_ratio 在這個端點上傳了不報錯也不起作用。需要改變輸出畫幅，請先自行裁剪或縮放參考圖再上傳。

響應裡為什麼沒有 revised_prompt？

本系列不返回 revised_prompt，也不返回 respect_moderation 等欄位。data[] 裡每項只有 url 或 b64_json 二選一（取決於 response_format），不會同時出現。解析響應時請不要假設這些欄位存在。

usage 裡的 token 數能用來核對賬單嗎？

不能。 響應體的 usage.prompt_tokens 恆為 1000 × n，與提示詞實際長度無關，是佔位值。本系列是按次計費（按張固定價），真實扣費請以 API易控制台的賬單記錄為準。

為什麼 1K 出 JPEG、2K 出 PNG？體積差很多

這是上游的行為：resolution: 1k 返回 JPEG（約 220–300 KB），resolution: 2k 返回 PNG 無損（約 5–6 MB），體積相差約 20 倍。返回的 URL 副檔名、HTTP Content-Type 與實際位元組格式三者是一致的，可以直接按 Content-Type 分支處理。如果你的場景對頻寬敏感（移動端、批量回傳），建議用 1k——兩檔同價，選擇只取決於畫質需求。

傳 resolution: 4k 報 503，是渠道掛了嗎？

不是。 4k 不是本系列支援的檔位，閘道會返回 503 model_service_unavailable。這個錯誤碼看起來像服務故障，但實際是引數問題，重試無效，改回 1k 或 2k 即可。支援的檔位只有 1k 和 2k 兩個。

為什麼引數寫錯了不報錯，只是圖不對？

本系列的引數校驗很寬鬆：非法的 aspect_ratio（如 5:7）、resolution（如 1K、1024x1024）、response_format（如 base64）都會靜默回退到預設值並正常出圖，不會返回 400。所以拿到的圖不符合預期時，第一步先檢查引數拼寫，特別注意 resolution 的值是小寫 1k / 2k。

單次最多能出幾張？

n 支援 1–10，返回的 data 陣列長度等於 n，按張計費。傳 0 會靜默按 1 處理；傳 11 及以上返回 400 invalid_request。

支援 seed 復現嗎？

不支援。 傳入 seed 不會報錯，但也不生效——相同提示詞、相同 seed 的兩次呼叫會得到不同的圖。需要複用某張圖請把結果儲存下來，不要指望通過重跑復現。

能用 OpenAI 官方 SDK 直接呼叫嗎？

可以。兩個端點都相容 OpenAI Images API 格式，把 base_url 指向 https://api.apiyi.com/v1 即可：

from openai import OpenAI
client = OpenAI(api_key="sk-your-api-key", base_url="https://api.apiyi.com/v1")

resp = client.images.generate(
    model="grok-imagine-image",
    prompt="a red wooden boat on an alpine lake at dawn",
    extra_body={"aspect_ratio": "16:9", "resolution": "1k"}
)

注意 aspect_ratio / resolution 不是 OpenAI SDK 的標準欄位，需要放進 extra_body 傳遞。

有併發限制嗎？批量出圖會不會被限流？

不限制併發。 實測 100 RPM 無壓力，沒有 429、沒有排隊拒絕，渠道資源充足，可以直接併發呼叫，不需要自建序列佇列，也無需額外申請配額。真正要注意的是 timeout：圖片 API 是同步呼叫，建議客戶端超時設到 360 秒，避免請求還在正常處理就被本地超時掐斷——被掐斷的請求仍然會計費。

內容稽核是怎樣的？被攔了怎麼判斷？

本系列有內容稽核。被攔截時返回 400 invalid_request，與引數錯誤使用完全相同的錯誤碼和提示文案，從響應體無法區分。實用判據是耗時：稽核攔截通常在 5–6 秒返回（攔截髮生在生成之前），而正常出圖約 9 秒。另外，稽核結果具有一定隨機性，個別邊界內容多次重試的結果可能不一致，因此不要根據單次結果就下判斷。確認引數無誤後仍持續報 400，通常就是提示詞觸發了稽核，建議調整表述。

能用 /v1/chat/completions 對話方式出圖嗎？

可以，但不主推。該端點會返回標準的 chat 結構，content 是一個 markdown 圖片連結：

![image](https://apac.ossforai.com/...)

適合 Chatbox / LobeChat 這類對話式客戶端直接接入。但程式化呼叫請統一使用 Images API（/v1/images/generations 與 /v1/images/edits）——引數更完整、響應結構更穩定，也與本文件的說明一致。

​概述

文生圖 API

圖片編輯 API

​為什麼選 API易 的 Grok Imagine 2

OpenAI 相容格式

不限併發 · 企業可放量

按次計費 · 成本可預測

全球零門檻接入

模型生態齊全

專業服務 · 企業陪跑

​核心特性

雙檔解析度

5 種寬高比

單次最多 10 張

出圖快

真參考圖編輯

多圖融合

雙返回格式

OpenAI SDK 直連

​模型定價

​分組介紹

​技術規格

​端點一覽

​從 GPT-Image-2 遷移

​引數對照

​三個最容易踩的坑

​遷移前後程式碼對照

​關鍵引數詳解

​aspect_ratio 與 resolution（輸出尺寸）

​n（單次出圖數量）

​最佳實踐

​錯誤碼與重試

​常見問題

​相關文件

概述

為什麼選 API易的 Grok Imagine 2

核心特性

模型定價

分組介紹

技術規格

端點一覽

從 GPT-Image-2 遷移

引數對照

三個最容易踩的坑

遷移前後程式碼對照

關鍵引數詳解

`aspect_ratio` 與 `resolution`（輸出尺寸）

`n`（單次出圖數量）

最佳實踐

錯誤碼與重試

常見問題

相關文件