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"
}
FieldTypeRequiredDescription
modelstringyesImage model ID from GET /api/v1/images/models
promptstringyesText description of the image to generate
resolutionstringnoOutput resolution tier (e.g. 1K); defaults to the model’s first supported tier
aspect_ratiostringnoAspect ratio (e.g. 16:9, 9:16, 1:1)
nintegernoNumber of images to generate (1..max_n, default 1)
seedintegernoSeed for deterministic generation (models with seed support)
qualitystringnoauto, low, medium, or high
output_formatstringnopng, jpeg, or webp
backgroundstringnoauto, transparent, or opaque
input_referencesarraynoReference 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 }
}
StatusDescription
pendingThe job is queued
in_progressThe image is being generated
completedThe image is ready to download
failedGeneration failed (see error); the reservation is fully refunded
cancelledThe 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

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.