Image

Perceptron provides an image generation API. Image models accept text prompts (and optional reference images) and generate one or more images.

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

Available Models

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

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)

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. See Billing for more details.

Studio

The Perceptron app includes Perceptron Studio, a creative studio interface for generating and managing images without writing any code: open the app and select Studio in the sidebar menu.