OneMux/文件中心/圖片模型

圖片模型

透過 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"
}

以上參數並非所有模型通用。若介面提示不支援參數,請移除選用參數,或確認所選模型和管道的能力。