Image Generation API

Use POST /v1/images/generations for public image generation tasks. 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 final image URLs.

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 through Task Retrieval. The async field is accepted for compatibility, but image generation always uses task mode.

Reference inputs

Models that support references can accept image_input URL values or multipart files, depending on model capability metadata.

{
  "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 requests use the same endpoint with multipart/form-data:

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"

Accepted multipart fields are model, prompt, async, response_format, aspect_ratio, resolution, background, output_format, n, repeated image_input / image_input[] URL fields, and repeated image / image[] file fields.

Responses

Image requests return 202 with a 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

• Use /v1/models to confirm the current model-specific limits.
• Keep n at 1 unless discovery explicitly says otherwise.
• Use response_format: "url"; base64 image responses are not currently supported.
• Store the returned task_id and poll poll_url until success or fail.
• Download generated assets promptly if returned URLs are temporary.

GPT Image 2.5

Use gpt-image-2.5-flare or gpt-image-2.5-sunburst. Each supports text-to-image and editing with up to 16 reference images. prompt accepts 1–20,000 characters.

Set resolution to 1K (default), 2K, or 4K, and background to auto (default), opaque, or transparent. aspect_ratio defaults to auto; supported ratios are 1:1, 3:2, 2:3, 16:9, 9:16, 4:3, 3:4, 21:9, 27:16, 16:27, 9:8, and 8:9. The last four require 1K. Omit output_format for these models.

The per-image prices are 0.01875 USDC for 1K, 0.0625 USDC for 2K, and 0.10 USDC for 4K. Read current prices and supported parameters from /v1/models before submitting. Both JSON and multipart requests accept background; reference inputs automatically select editing. Poll the returned task until it reaches a terminal state.