API REFERENCE

影像生成

透過一個與 OpenAI 相容的端點產生和編輯影像。相同的請求格式可觸及目錄中的每一個影像模型。

單一個與 OpenAI 相容的圖片 endpoint，可分散導向 Flux、Nano-Banana、Wan 及其他供應商。無論上游為何都送出相同的 request 結構；供應商專屬的選項會透傳，並依各模型的能力進行驗證。

透過列出 models endpoint 來探索圖片模型，並保留那些 output modalities 包含 image 的模型。

POST /v1/images/generations

與 OpenAI 直接相容 images.generate SDK。特定於提供者的參數與標準參數並存－後端轉發每個模型理解的內容。

POSThttps://api.airforce/v1/images/generations

影像模型

…· live

常用參數

Parameter	Type	Required	Description
model	string	Required	Image model ID. Find them on /v1/models: image models carry media_type: "image" and an image_caps block.
prompt	string	Required	Image description.
n	integer	Optional	Number of variations to generate per request. Capped by the model's image_caps.max_n.
size	string	Optional	OpenAI-style WxH, e.g. "1024x1024". Provider-specific values pass through.
aspect_ratio	string	Optional	Alternative to size. "16:9", "1:1", "9:16", … Validated against image_caps.aspect_ratios.
quality	string	Optional	"standard" \| "hd" (OpenAI) or model-specific labels. Validated.
response_format	string	Optional	"url" (default) or "b64_json".
seed	integer	Optional	Reproducibility seed. Same prompt + same seed = same image (where the upstream supports it).
input_images	array	Optional	[{ url? } \| { b64_json? }] for image-to-image / reference / first-frame.
sse	boolean	Optional	When true the response is sent as Server-Sent Events. The full JSON arrives in one event followed by [DONE]. Useful to keep long upstream renders from timing out at proxies.

基本範例

curl https://api.airforce/v1/images/generations \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A cute baby sea otter floating on its back",
    "n": 1,
    "response_format": "url"
  }'

回應形狀

Parameter	Type	Required	Description
created	integer	Optional	Unix timestamp.
data	array	Optional	Generated assets.
data[].url	string	Optional	Image URL when response_format is "url" (default). The image is re-hosted to a file host and the link ends in /image.jpeg; null if the re-host fails.
data[].b64_json	string	Optional	Base64-encoded image bytes when response_format is "b64_json". The format follows the upstream provider (often JPEG), not necessarily PNG.

{
  "created": 1715000000,
  "data": [{
    "url": "https://.../image.jpeg"
  }]
}

串流版本

經過 sse: true 當透過具有嚴格空閒超時的中間件進行代理時。回應是一個帶有完整 JSON 的 SSE 事件，然後 [DONE].

data: {"created":1715000000,"data":[{"url":"https://.../image.jpeg"}]}

data: [DONE]

圖像到圖像和參考

型號有 image_caps.max_input_images > 0 接受參考圖像。傳遞 URL 或 Base64 編碼的資料。

curl https://api.airforce/v1/images/generations \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "Same character, now in a snowy forest",
    "aspect_ratio": "16:9",
    "input_images": [
      {"url": "https://example.com/character.jpg"}
    ]
  }'

影像編輯

相容 OpenAI 的編輯端點。以 multipart 檔案傳送來源影像（OpenAI SDK 的 images.edit 就是這樣做），或在上方的 JSON 內容中使用 input_images。它與 /v1/images/generations 走同一路徑：模型、價格與回應格式皆相同。

POSThttps://api.airforce/v1/images/edits

Parameter	Type	Required	Description
model	string	Required	An image model with image_caps.max_input_images > 0 (see Discovering capabilities below).
prompt	string	Required	What to change or create from the input image(s).
image	file	Required	The source image. Repeat as image[] for several references; images, images[] and input_images are accepted too, as files or as image URLs.
mask	file	Optional	Forwarded as is, but no listed model declares mask support, so the serving model may ignore it.
n	integer	Optional	Number of images to generate.
size	string	Optional	Output size, e.g. "1024x1024", where the model supports it.
aspect_ratio	string	Optional	Output aspect ratio, e.g. "16:9", where the model supports it.
quality	string	Optional	Model-specific quality level.
response_format	string	Optional	"url" or "b64_json", as on /v1/images/generations.

curl https://api.airforce/v1/images/edits \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -F "model=nano-banana-2" \
  -F "prompt=Same character, now in a snowy forest" \
  -F "[email protected]" \
  -F "aspect_ratio=16:9"

from openai import OpenAI

client = OpenAI(base_url="https://api.airforce/v1", api_key="sk-air-YOUR_API_KEY")

with open("character.png", "rb") as image:
    result = client.images.edit(
        model="nano-banana-2",
        image=image,
        prompt="Same character, now in a snowy forest",
    )
print(result.data[0].url)

每個請求最多 16 張輸入影像，每張不超過 25 MB；模型本身的上限見 image_caps.max_input_images。沒有輸入影像的請求會回傳 400，而不會變成文字生成影像的呼叫。每張輸入影像都可能增加費用，以模型頁面為準。

特定型號參數

除了上述通用參數之外，個別型號系列還接受額外參數。未知參數按原樣轉發到上游，因此任何未來特定於提供者的旋鈕也無需更新 SDK 即可運作。

Nano-Banana

nano-banana-2, nano-banana-pro

Parameter	Type	Required	Description
aspect_ratio	string	Optional	"1:1", "16:9", "9:16", "4:3".
resolution	string	Optional	"512", "1024", "2048".
image_urls	array	Optional	Reference images.

Suno (music)

suno-v4.5、suno-v5、suno-v5.5 過去可在此端點上呼叫。現在它們屬於原生音樂 API： /v1/audio/music ——此處的呼叫會以 `wrong_endpoint` 被拒絕。

發現能力

每個影像模型都暴露 image_caps 在 /v1/models 因此客戶端可以在發送之前驗證輸入：

Parameter	Type	Required	Description
image_caps.max_n	integer	Optional	Maximum n per request.
image_caps.aspect_ratios	array	Optional	Allowed aspect_ratio values.
image_caps.qualities	array	Optional	Allowed quality values.
image_caps.max_input_images	integer	Optional	0 = text-only model. Higher = supports reference images.
image_caps.supports_url_input	boolean	Optional	Whether input_images may be passed as URLs (vs base64).
image_caps.supports_seed	boolean	Optional	Whether the model honours a seed value (most scraping-proxy upstreams ignore it).

圖片定價不在 image_caps 中——請使用 /v1/models 上該模型的價格欄位來取得費用。