Image Generation API

使用 Xenodia shared image endpoint、模型专属参数、reference input 和 async task mode 生成图片。

使用 POST /v1/images/generations 进行 public image generation。多个模型共享同一个 endpoint，但支持的参数和价格可能不同。

Endpoint

POST https://api.xenodia.xyz/v1/images/generations

Minimal request

{
  "model": "gpt-image-2",
  "prompt": "A clean product render of a translucent AI gateway cube on a white desk.",
  "response_format": "url"
}

Async request

{
  "model": "nano-banana-pro",
  "prompt": "A cinematic dashboard screenshot for a developer API product.",
  "async": true,
  "aspect_ratio": "16:9",
  "resolution": "2K",
  "response_format": "url"
}

Async request 返回 task identifier，通过 Task Retrieval 轮询。

Reference inputs

支持 reference 的模型可以接受 image_input URL 或 multipart file。

{
  "model": "gpt-image-2",
  "prompt": "Use this reference as the product shape, render it in a clean studio.",
  "image_input": [
    "https://example.com/reference.png"
  ],
  "response_format": "url"
}

Multipart request：

curl -X POST "https://api.xenodia.xyz/v1/images/generations" \
  -H "Authorization: Bearer $XENODIA_API_KEY" \
  -F "model=nano-banana-pro" \
  -F "prompt=Render the uploaded reference as a clean product image." \
  -F "async=true" \
  -F "response_format=url" \
  -F "image=@./reference.png"

Multipart fields：model、prompt、async、response_format、aspect_ratio、resolution、output_format、n、channel_id、重复的 image_input / image_input[] URL fields，以及重复的 image / image[] file fields。

Responses

同步请求返回 200：

{
  "created": 1760000000,
  "data": [
    {
      "url": "https://cdn.example.com/generated.png"
    }
  ]
}

异步请求返回 202 task envelope：

{
  "task_id": "task_123",
  "object": "task",
  "model": "nano-banana-pro",
  "type": "image",
  "state": "waiting",
  "created_at": 1760000000,
  "poll_url": "/v1/tasks/task_123"
}

Shared rules

使用 /v1/models 确认当前模型限制。
除非 discovery 明确支持，否则 n 保持 1。
使用 response_format: "url"；当前不支持 base64 image response。
长时间媒体生成使用 async: true。
如果返回 URL 是临时资源，应尽快下载生成资产。