Image

Perceptron provides an OpenRouter-compatible image generation API. Image models accept text prompts (and optional reference images) and generate one or more images. You pay using credits purchased with USDT.

Image generation is asynchronous: you submit a job, poll its status, and download the finished image(s). Generation typically takes a few seconds.

Base URL

https://perceptron.cloud/api/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate an API key from the Keys page in the Perceptron app.

Available Models

curl https://perceptron.cloud/api/v1/images/models

Image models (the image output modality) are listed separately from chat models. The response includes each model’s input/output modalities, supported resolutions, aspect ratios, seed support, max images per request, and per-image pricing per resolution tier.

Generating Images

1. Submit a job

POST /api/v1/images

curl -X POST https://perceptron.cloud/api/v1/images \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea/krea-2-large",
    "prompt": "A neon-lit cyberpunk street market in the rain, cinematic, high detail",
    "resolution": "1K",
    "aspect_ratio": "16:9",
    "n": 1,
    "seed": 42
  }'

Returns 202 Accepted with the job details:

{
  "id": "0e1b0c3f-...",
  "polling_url": "/api/v1/images/0e1b0c3f-...",
  "status": "pending"
}

Field	Type	Required	Description
`model`	string	yes	Image model ID from `GET /api/v1/images/models`
`prompt`	string	yes	Text description of the image to generate
`resolution`	string	no	Output resolution tier (e.g. `1K`); defaults to the model’s first supported tier
`aspect_ratio`	string	no	Aspect ratio (e.g. `16:9`, `9:16`, `1:1`)
`n`	integer	no	Number of images to generate (`1`..max_n, default `1`)
`seed`	integer	no	Seed for deterministic generation (models with seed support)
`quality`	string	no	`auto`, `low`, `medium`, or `high`
`output_format`	string	no	`png`, `jpeg`, or `webp`
`background`	string	no	`auto`, `transparent`, or `opaque`
`input_references`	array	no	Reference images for image-to-image generation (up to 1)

output_compression, stream, size, callback_url, and provider are not supported; rejected with 400.

2. Poll for status

GET /api/v1/images/{id}

curl https://perceptron.cloud/api/v1/images/0e1b0c3f-... \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY"

{
  "id": "0e1b0c3f-...",
  "polling_url": "/api/v1/images/0e1b0c3f-...",
  "status": "completed",
  "unsigned_urls": ["/api/v1/images/0e1b0c3f-.../content?index=0"],
  "usage": { "cost": 0.30 }
}

Status	Description
`pending`	The job is queued
`in_progress`	The image is being generated
`completed`	The image is ready to download
`failed`	Generation failed (see `error`); the reservation is fully refunded
`cancelled`	The job was cancelled; fully refunded

Poll at a reasonable interval (e.g. every 2–5 seconds). When n > 1, unsigned_urls contains one entry per output image (index 0..n-1).

3. Download an image

GET /api/v1/images/{id}/content?index=N

curl https://perceptron.cloud/api/v1/images/0e1b0c3f-.../content?index=0 \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  --output image.png

Raw image bytes with Content-Type matching the model’s output format (e.g. image/png). index is 0-based. Finished images are stored as artifacts in your account.

Listing and deleting jobs

GET /api/v1/images — list your image generation jobs, newest first.
DELETE /api/v1/images/{id} — delete a job and its stored images, stopping its storage billing.

See the full reference at API Reference.

Pricing

Image generation is billed per output image from your credits balance — see the live per-resolution rates at GET /api/v1/images/models. The full quoted cost (n × rate) is reserved when you submit and refunded if the job fails. Stored images accrue a small hourly artifact storage charge until deleted. See Billing for more details.

Studio

The Perceptron app includes Studio, a browser interface for generating and managing images without writing any code: open the app and select Studio, then the New Image tab.