圖片模型
透過 OneMux 圖片模型介面進行圖片生成和圖片編輯。
介面說明
圖片模型使用獨立的 Images 介面,請勿將圖片生成請求傳送至 /v1/chat/completions。
- 圖片生成:
POST https://api.onemux.net/v1/images/generations - 圖片編輯:
POST https://api.onemux.net/v1/images/edits - 驗證:
Authorization: Bearer YOUR_API_KEY - 模型: 使用目前模型清單介面回傳的實際圖片模型 ID
請先取得目前可用的模型:
curl https://api.onemux.net/v1/models \
-H "Authorization: Bearer $ONEMUX_API_KEY"
圖片模型是否支援生成、編輯、參考圖、尺寸、品質、輸出格式等參數,請以模型清單和上游實際能力為準。
圖片生成
使用 /v1/images/generations 傳送文字生成圖片請求。
curl https://api.onemux.net/v1/images/generations \
-H "Authorization: Bearer $ONEMUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_IMAGE_MODEL_ID",
"prompt": "一只坐在窗边的橘猫,午后自然光,写实摄影风格",
"size": "1024x1024",
"quality": "medium"
}'
常用參數:
| 參數 | 必填 | 說明 |
|---|---|---|
model | 是 | 目前可用的圖片模型 ID |
prompt | 是 | 圖片內容描述 |
size | 否 | 圖片尺寸,支援範圍由模型決定 |
quality | 否 | 圖片品質,支援值由模型決定 |
n | 否 | 生成數量,支援範圍由模型決定 |
response_format | 否 | b64_json 或 url,僅支援的模型可使用 |
background | 否 | 透明或不透明背景,僅支援的模型可使用 |
output_format | 否 | png、jpeg、webp,僅支援的模型可使用 |
請勿將某個模型支援的參數直接用於其他圖片模型。遇到 model_not_found、invalid_model 或參數不支援錯誤時,請先確認模型 ID 和模型能力。
圖片編輯
使用 /v1/images/edits 編輯既有圖片。常見的 OpenAI 相容圖片模型使用 multipart/form-data 上傳圖片:
curl https://api.onemux.net/v1/images/edits \
-H "Authorization: Bearer $ONEMUX_API_KEY" \
-F "model=YOUR_IMAGE_MODEL_ID" \
-F "image[]=@input.png" \
-F "prompt=将背景改为浅蓝色,保持主体和文字不变" \
-F "size=1024x1024"
多張參考圖可以重複傳入 image[],例如:
-F "image[]=@person.png" \
-F "image[]=@product.png"
圖片數量、圖片格式、遮罩、參考圖 URL 和 JSON 編輯格式由模型及上游管道決定。只有模型明確支援時,才使用這些參數。
Python 呼叫
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ONEMUX_API_KEY"],
base_url="https://api.onemux.net/v1",
)
result = client.images.generate(
model="YOUR_IMAGE_MODEL_ID",
prompt="一张简洁的蓝色科技风产品海报",
size="1024x1024",
)
print(result.data[0].b64_json or result.data[0].url)
圖片編輯通常需要直接提交 multipart 檔案。如果目前的 Python SDK 版本不支援目標模型的編輯參數,請使用上方的 cURL 請求。
回傳結果
成功回應通常包含 data 陣列:
{
"created": 1760000000,
"data": [
{
"b64_json": "iVBORw0KGgo..."
}
]
}
部分模型在請求 response_format 設為 url 時會回傳圖片網址:
{
"created": 1760000000,
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}
回傳 Base64 時,請依實際圖片格式儲存檔案;回傳 URL 時,請及時下載並自行儲存,以免臨時網址過期。
計費說明
圖片模型的計費方式不一律採用 Token。OneMux 會依照模型目前公布的計費規則結算,可能包括:
- 依生成圖片張數計費
- 依圖片解析度或品質等級計費
- 依圖片輸入、輸出 Token 或其他上游用量計費
實際價格、計費單位和支援規格,請以模型目錄中對應模型的目前說明為準。請求失敗通常不會產生成功結果所對應的圖片費用,但具體情況仍以頁面顯示和伺服器回應為準。
常見問題
為什麼不能使用對話介面生成圖片?
圖片模型使用獨立的 Images 路由。傳送至 /v1/chat/completions 或其他不相符的介面,可能會收到模型不支援該端點或參數錯誤的回應。
為什麼查得到模型名稱,但請求仍然失敗?
請檢查模型是否允許圖片生成或圖片編輯、目前的 API Key 是否有權限、請求參數是否在該模型的支援範圍內,以及對應的上游管道是否可用。
為什麼回傳的是 Base64,而不是圖片連結?
不同模型或 response_format 設定會決定回傳格式。收到 b64_json 時,需要在用戶端自行解碼並儲存;收到 url 時,則需要下載回傳網址。
圖片生成很慢時該怎麼辦?
高解析度、高品質或複雜的編輯請求可能需要較長時間。用戶端應設定合理的請求逾時時間,不要因用戶端逾時就重複提交相同請求,以免產生重複任務或費用。
GPT Image 2.6:SVG、GIF 與複雜度
GPT Image 2.6 系列新增 SVG 輸出、GIF 動畫輸出和 complexity 參數。這些功能僅適用於支援的模型和上游管道。
輸出 SVG
SVG 用於圖片生成,不適用於圖片編輯。呼叫生成介面時,將 output_format 設為 svg,並將 n 設為 1。回應中的圖片資料為 Base64,解碼後請儲存為 .svg 檔案。
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一个简洁的蓝色几何图形标志",
"output_format": "svg",
"n": 1
}
部分上游設定可能還要求額外的 svg 物件,例如 svg.model。只有在模型或管道說明明確要求時才加入。並非所有圖片模型和管道都支援 SVG。
輸出 GIF 動畫
支援此功能的 GPT Image 2.6 模型可在圖片生成介面中將 output_format 設為 gif。在模型支援的情況下,可使用 frame_count 和 frame_duration_ms 設定動畫影格數和每個影格的時間長度。GIF 屬於生成能力,請勿假設圖片編輯介面也能回傳 GIF。
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一只蓝色小鸟循环拍打翅膀的动画",
"output_format": "gif",
"frame_count": 6,
"frame_duration_ms": 200
}
複雜度參數
GPT Image 2.6 系列支援 complexity:low、medium、high。簡單修改可嘗試較低的複雜度;文字密集或版面複雜的圖片則可嘗試較高的複雜度。此參數與 quality 不同,複雜度較高時,生成可能會比較慢。
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一张细节丰富的城市街景编辑插画",
"complexity": "high",
"quality": "high"
}
以上參數並非所有模型通用。若介面提示不支援參數,請移除選用參數,或確認所選模型和管道的能力。