影像生成 是做什麼的?
同步的圖片生成與編輯功能。無需輪詢任務狀態。
使用時機
- 文字轉圖片、圖片轉圖片、遮罩內補(masked inpainting)。
- 透明背景、WebP/JPEG 輸出、GPT-Image 動畫 GIF。
- 使用者指定了圖片模型名稱,或要求特定尺寸、品質或格式。
不適用時機
- 影片、音樂、語音或 Jev 決策模型。請使用對應的專用技能。
- 使用者想先比較價格:請執行
models --category image。
先決條件
依此順序解析 API 密鑰(優先採用第一個相符的):
skills/image-generation/config.json→api_keyskills/ai-gateway/config.json→api_keyAIGW_IMAGE_API_KEYAIGW_API_KEYOPENAI_API_KEY
使用以下命令儲存憑證:
python3 core/gateway.py login --key sk-xxx --skill image
--base-url 會將網關位址寫入設定檔。解析順序:技能設定、共用設定、AIGW_IMAGE_BASE_URL、AIGW_BASE_URL,最後是 core/config.json 中封裝的預設值。
指令
# 文字轉圖片
python3 core/gateway.py image generate --prompt "一隻在長凳上的小熊貓,柔和光線" \
--model <model> --size 1024x1024 --quality high --output-format png
# 多張圖片
python3 core/gateway.py image generate --prompt "貼紙組" --n 4
# 透明 PNG(需要支援 Alpha 輸出的模型層級)
python3 core/gateway.py image generate --prompt "卡通狐狸貼紙,乾淨的剪裁邊緣" \
--background transparent --output-format png
# 動畫 GIF(需要支援 GIF 的模型層級)
python3 core/gateway.py image generate --prompt "一個小機器人在揮手,循環播放" \
--output-format gif --frame-count 9 --frame-duration-ms 200
# 編輯 / 內補
python3 core/gateway.py image edit --prompt "將天空改為夕陽橘色" \
--image input.png --mask mask.png
# 使用透明標記圓圈進行編輯(GPT-Image 2.5+)
python3 core/gateway.py image edit --prompt "將圓圈標記的物體替換為紅色蘋果" \
--image input.png --markup markup.png
# 探索模型與別名
python3 core/gateway.py models --category image
python3 core/gateway.py resolve nano-banana
參數
| 標記 | 必要 | 說明 |
|---|---|---|
--prompt | 是 | 文字描述。 |
--model | 否 | 確切的模型 ID。如果只有一個圖片模型可用則可省略。 |
--size | 否 | 1024x1024、1536x1024、auto 或模型特定的值。使用 -1k 模型變體可獲得最低價格層級。 |
--n | 否 | 圖片數量。硬性上限為 128。 |
--quality | 否 | auto / low / medium / high;GPT-Image 2.5+ 還支援 xhigh、max。 |
--output-format | 否 | png / jpeg / webp;GPT-Image 2.6 新增 svg、gif。 |
--background | 否 | transparent 需要 png 或 webp。 |
--moderation | 否 | auto / low。 |
--complexity | 否 | GPT-Image 2.6 規劃深度 low / medium / high。不影響計費。 |
--output-compression | 否 | 0-100,僅 JPEG/WebP。 |
--frame-count | 否 | 2-64,僅 GIF。必須為非負整數。 |
--frame-duration-ms | 否 | 20-2000,僅 GIF。 |
--markup | 否 | 僅編輯。透明 PNG 疊加層,圈出編輯區域;僅 GPT-Image 2.5+。 |
--group | 否 | 路由至特定的計費群組。 |
端點
POST /v1/images/generations— JSON,同步。POST /v1/images/edits— multipart,欄位名稱為image[],可選mask。
回應會攜帶 data[] 項目。每個項目包含 b64_json 或 url。CLI 會解碼 base64、下載 URL,並將檔案寫入 outputs/image/<YYYY-MM-DD>/。如果下載被拒絕,則會回傳原始 URL 於 urls 中。
Gemini 圖片模型也接受 /v1/images/generations,其中 size 會對應到 imageSize 與 aspectRatio。已驗證:2048x2048 會回傳 2048x2048。GPT-Image 2.6 也接受明確的像素尺寸;已驗證 3840x2160 會回傳 3840x2160。
解析度
| 需求 | 尺寸值 | 結果 |
|---|---|---|
| 1K 方形 | 1024x1024 | 1024x1024 或 1254x1254 |
| 2K 方形 (Gemini) | 2048x2048 | 2048x2048 |
| 4K 橫向 | 3840x2160 | 3840x2160 |
使用 -1k 模型變體以獲得最低價格層級;較大尺寸的計費僅在模型採用固定價格時,才會以相同每次呼叫的價格計費。
結尾為 -1k 的模型 ID(gpt-image-2.6-1k、-flare-1k、-sunburst-1k)總是回傳 1K。從它要求 4K 會反映要求尺寸,但實際回傳約 1254x1254,因此請檢查輸出尺寸而非信任要求。
--output-format svg 僅支援 --n 1;上游會拒絕較大的批次。請將 GIF/SVG 要求保持在 n=1,並自行拆分批次。
格式與透明度
| 能力 | 需求 |
|---|---|
png / jpeg / webp | 一般可用。 |
| 透明背景 | 需要 png 或 webp。僅較新的模型層級會產生 Alpha 通道;入門層級會拒絕。 |
| 動畫 GIF | 2.6 層級以上的生成式圖片模型。需要 --output-format gif 加上 --frame-count (2-64) 和 --frame-duration-ms (20-2000)。 |
| SVG 輸出 | 2.6 層級以上,僅生成。編輯端點會拒絕 svg 和 gif。 |
當格式被拒絕並回傳 400 時,表示選定的模型層級不支援該格式。請切換到較新的層級,而不是重試同一個模型。
部分模型會接受 background: transparent 而不報錯,但仍回傳不透明圖片。請務必驗證結果,而非信任要求:
file outputs/image/<date>/<name>.png # "RGBA" 或 "color_type 6" 表示真實的 Alpha 通道
RGB 結果表示該標記被忽略。請改用其他模型層級重試,或在本地端對白色背景進行後處理。
編輯
image edit 會將本地檔案以 multipart 形式上傳,因此輸入圖片不需要是公開的。
--image可重複使用;最多接受 16 個輸入。--mask標記重新繪製的區域;--markup在 GPT-Image 2.5 及之後的版本中圈出編輯區域,並以 multipart 檔案形式傳遞。- 編輯端點僅接受
png/jpeg/webp輸出。svg和gif僅限生成使用。 - 除非提示另有要求,否則回傳的圖片會保持輸入的構圖。
已驗證:透過 image edit 對本地圖片進行操作,無論在 GPT-Image 模型還是 Gemini 圖片模型上都能成功運作,各自回傳保留原始構圖的編輯後圖片。
錯誤
| 狀態碼 | 意義 | 處理方式 |
|---|---|---|
| 400 | 無效參數或不支援的模型能力 | 修正標記;請檢查 models --category image。 |
| 401 | 缺少或無效的金鑰 | 重新執行 login,然後執行 doctor。 |
| 402 | 額度不足 | 請使用者充值。 |
| 429 | 速率限制或並發上限 | 退避並重試。 |
| 503 | 該金鑰所在的群組無法使用該模型 | 切換模型,或使用該群組的金鑰。 |
| 5xx | 上游故障 | 重試一次,然後直接回報錯誤訊息。 |