Gemini 3.1 Flash Image Preview

• 模型：gemini-3.1-flash-image-preview（固定）
• 功能：文字生圖、圖像轉圖像（最多 14 張參考圖），最高 4K，極端長寬比，可選 Google 搜尋接地

不要透過 /v1/chat/completions 呼叫此模型——你會收到 400 錯誤，提示你改用 Images API。

端點

模式	端點	使用時機
同步（建議）	POST https://apimaster.ai/v1/images/generations	單次 HTTP 往返；平台輪詢上游，回傳 { "data": [{ "url" }] }
非同步	POST https://apimaster.ai/v1/images/generations/async → GET https://apimaster.ai/v1/tasks/{task_id}?model=gemini-3.1-flash-image-preview	長時間任務、自訂佇列

快速開始（同步）

curl -s "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "Cyberpunk city at night, neon lights",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'

成功回應

{
  "created": 1782633696,
  "data": [{ "url": "https://apimaster.ai/imgs/1782633695067198543.jpg" }]
}

設定 HTTP 讀取逾時 ≥ 180s（用於 2K/4K）。請盡快下載或鏡像 URL——它們會過期。

非同步流程

提交

curl -s "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

提交回應

{
  "code": 200,
  "data": [{ "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }]
}

輪詢

curl -s "https://apimaster.ai/v1/tasks/TASK_ID?model=gemini-3.1-flash-image-preview" \
  -H "Authorization: Bearer YOUR_API_KEY"

成功時讀取 data.result.images[0].url。常見輪詢狀態：in_progress → succeeded / completed。

第一次輪詢前等待 10–20 秒，之後每隔 3–5 秒。

驗證

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

請求主體參數

欄位	類型	必填	備註
model	string	是	gemini-3.1-flash-image-preview
prompt	string	是	場景描述
size	string	否	長寬比；詳見下方
resolution	string	否	0.5K / 1K / 2K / 4K，預設 1K；不區分大小寫
n	integer	否	僅支援 1（數字，非字串）
image_urls	array	否	參考圖片（URL 或 data URI）
google_search	boolean	否	Google 文字搜尋接地
google_image_search	boolean	否	需設 google_search: true

解析度與計費層級

值	~像素	相較於 1K 基礎的價格倍率
0.5K	~512	同 1K
1K	~1024	基礎
2K	~2048	× 4/3
4K	~4096	× 2

實際費用 = 通道價格 × 解析度倍率 × 群組比例。請參閱市場或主控台日誌。

錯誤

HTTP	含義
400	參數錯誤，或使用了錯誤端點（聊天）
401	API 金鑰無效
402	餘額不足
408	同步輪詢超時——改用非同步或降低解析度
500 / 502	上游或平台錯誤

無效的長寬比可能導致 500 錯誤（當僅配置一個通道時）。

備註

• 使用日誌中包含 result_url（圖片預覽）和 request_data.effective_resolution。
• 價格因通道和解析度而異——請參閱市場。