Image Generation

Xenodia uses a single public entrypoint for image generation: POST /v1/images/generations. The first production image model exposed on this surface is nano-banana-pro. Send JSON for prompt-only or URL-only references, or use multipart/form-data when uploading local reference files. The default behavior is synchronous. Add async: true to receive a Xenodia task object instead of the final image payload.

Endpoint

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

Authentication

Authorization: Bearer YOUR_LONG_TERM_KEY

Supported Content Types

• application/json: best for prompt-only and URL-based reference input.
• multipart/form-data: required for local file uploads and also supports mixed URL + file input.

Request Body Schema

type: object
required:
  - model
  - prompt
properties:
  model:
    type: string
    enum:
      - nano-banana-pro
    default: nano-banana-pro
    description: Public model ID for this image endpoint.
  prompt:
    type: string
    minLength: 1
    description: Generation instruction. Must be non-empty.
  n:
    type: integer
    minimum: 1
    maximum: 1
    default: 1
    description: Only n=1 is currently supported.
  async:
    type: boolean
    default: false
    description: When true, returns a Xenodia task resource instead of waiting for the final image.
  response_format:
    type: string
    enum:
      - url
    default: url
    description: Only url is currently supported.
  aspect_ratio:
    type: string
    enum:
      - '1:1'
      - '2:3'
      - '3:2'
      - '3:4'
      - '4:3'
      - '4:5'
      - '5:4'
      - '9:16'
      - '16:9'
      - '21:9'
      - auto
    default: '1:1'
    description: Output aspect ratio.
  resolution:
    type: string
    enum:
      - 1K
      - 2K
      - 4K
    default: 1K
    description: Output resolution. 1K and 2K share the same base pricing tier; 4K uses the higher tier.
  output_format:
    type: string
    enum:
      - png
      - jpg
    default: png
    description: Output image file format.
  image_input:
    type: array
    items:
      type: string
      format: uri
    maxItems: 8
    description: Reference image URLs. Total references across URLs and uploaded files cannot exceed 8.

Multipart Fields

scalar_fields:
  - model
  - prompt
  - n
  - async
  - response_format
  - aspect_ratio
  - resolution
  - output_format

reference_url_fields:
  - image_input
  - image_input[]

reference_file_fields:
  - image
  - image[]

file_limits:
  accepted_mime:
    - image/jpeg
    - image/png
    - image/webp
  max_size_per_file_bytes: 31457280
  max_total_references: 8

JSON Request Example

{
  "model": "nano-banana-pro",
  "prompt": "A cinematic banana pilot standing on a wet neon runway.",
  "aspect_ratio": "16:9",
  "resolution": "2K",
  "output_format": "png",
  "image_input": [
    "https://example.com/reference-1.png",
    "https://example.com/reference-2.png"
  ],
  "response_format": "url"
}

Multipart Request Example

curl -X POST "https://api.xenodia.xyz/v1/images/generations" \
  -H "Authorization: Bearer $XENODIA_API_KEY" \
  -F "model=nano-banana-pro" \
  -F "prompt=A cinematic banana pilot standing on a wet neon runway." \
  -F "async=false" \
  -F "response_format=url" \
  -F "aspect_ratio=16:9" \
  -F "resolution=2K" \
  -F "output_format=png" \
  -F "image_input[]=https://example.com/reference-1.png" \
  -F "image[]=@/path/to/local-reference.png"

Reference Input Rules

• Both URL references and uploaded files are supported.
• URL references and uploaded files are counted together, with a combined cap of 8.
• Accepted MIME types are image/jpeg, image/png, and image/webp.
• Maximum file size per reference is 30MB.
• If omitted, aspect_ratio, resolution, and output_format default to1:1, 1K, and png.

Synchronous Success Response

{
  "created": 1760001111,
  "data": [
    { "url": "https://cdn.xenodia.xyz/generated/a.png" }
  ]
}

Async Request Example

{
  "model": "nano-banana-pro",
  "prompt": "A cinematic banana pilot standing on a wet neon runway.",
  "resolution": "4K",
  "async": true
}

Async Create Success Response

{
  "task_id": "0f6b9f2f-4d2a-4e1a-ae49-3e5d4f88dc2f",
  "object": "task",
  "model": "nano-banana-pro",
  "type": "image",
  "state": "waiting",
  "created_at": 1760002222,
  "poll_url": "/v1/tasks/0f6b9f2f-4d2a-4e1a-ae49-3e5d4f88dc2f"
}

Status Codes

200:
  description: Synchronous image generation succeeded

202:
  description: Async media task created successfully

400:
  description: Invalid request payload or unsupported parameter
  possible_errors:
    - bad_request
    - unsupported_model

401:
  description: Missing or invalid Bearer token

402:
  description: Insufficient balance

502:
  description: Upstream image generation failed
  possible_errors:
    - image_generation_failed

Common Validation Errors

{
  "error": "bad_request",
  "message": "only n=1 is supported"
}

{
  "error": "bad_request",
  "message": "only response_format=url is supported"
}

{
  "error": "bad_request",
  "message": "image_input accepts at most 8 references"
}