API REFERENCE

图像生成

通过一个与 OpenAI 兼容的端点生成和编辑图像。相同的请求格式可触达目录中的每一个图像模型。

一个与 OpenAI 兼容的 image endpoint 会分发到 Flux、Nano-Banana、Wan 及其他提供方。无论上游是哪个，都使用相同的请求结构发送；提供方特有的选项会透传，并依据各模型的能力进行校验。

通过列出 models endpoint 并保留那些输出 modalities 包含 image 的模型，即可发现 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 上该模型的价格字段获取费用。