Image Generation API

Create image tasks with Xenodia's shared image endpoint, model-specific parameters, and reference input.

Use POST /v1/images/generations to create a public image generation task. Multiple models share the same endpoint, but supported parameters and pricing can differ by model. The endpoint returns a task immediately; poll the task endpoint for the final image URL.

Endpoint

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

Minimal request

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A clean product render of a translucent crystal compute object on a white desk.",
  "response_format": "url"
}

Task request

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "A cinematic dashboard screenshot for a developer API product.",
  "aspect_ratio": "16:9",
  "resolution": "2K",
  "response_format": "url"
}

The request returns a task identifier. Poll it with Task Retrieval. The async field can still be sent for backward compatibility, but image generation always uses task mode.

Reference inputs

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

{
  "model": "gpt-image-2.5-flare",
  "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=gpt-image-2.5-sunburst" \
  -F "prompt=Render the uploaded reference as a clean product image." \
  -F "response_format=url" \
  -F "image=@./reference.png"

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

Responses

Image requests return a 202 task envelope:

{
  "task_id": "task_123",
  "object": "task",
  "model": "gpt-image-2.5-sunburst",
  "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。
Store the returned task_id and poll poll_url until success or fail.
如果返回 URL 是临时资源，应尽快下载生成资产。

GPT Image 2.5

使用 gpt-image-2.5-flare 或 gpt-image-2.5-sunburst。两者均支持文生图和最多 16 张参考图编辑，prompt 为 1–20,000 个字符。

resolution 支持 1K（默认）、2K、4K；background 支持 auto（默认）、opaque、transparent。aspect_ratio 默认 auto，也支持 1:1、3:2、2:3、16:9、9:16、4:3、3:4、21:9、27:16、16:27、9:8、8:9，最后四种比例仅支持 1K。这两个模型不接受 output_format。

每张图片售价：1K 为 0.01875 USDC，2K 为 0.0625 USDC，4K 为 0.10 USDC。提交前通过 /v1/models 查询当前价格与参数。JSON 和 multipart 均支持 background；有参考图时自动进入编辑模式。创建后轮询任务直至结束。