Quickstart

From zero to a generated image in five minutes.

V1 surface is being redesigned. Resource paths split into /v1/images + /v1/videos. The legacy /v1/generations + /v1/video-generations paths still work via 308 redirects through 2026-08-04 (Aurous-Deprecated: route, Sunset header). Multi-LoRA stacking (loras: [{ lora, weight }]), opaque IDs, idempotency, signed webhooks, and a /v1/files upload endpoint are landing across the redesign — see the Changelog for each shipped change.

This walks you through the five surfaces you’ll touch on day one: authenticate, estimate cost, generate, poll, and read the output. There’s a teaser for webhooks at the end so you don’t have to keep polling forever.

1. Authenticate

Create a team in the dashboard and mint a key under Settings → API keys. The plaintext is shown once at creation — store it in a secret manager. Keys look like al_live_<64-hex> (older keys may begin with og_ — both work).

Send the key in the X-Api-Key header on every request. A 5-second proof-of-life:

curl https://api.aurous-labs.com/v1/balance \
  -H "X-Api-Key: $AUROUS_API_KEY"

{
  "credits": 1023.49,
  "held_credits": 4,
  "available_credits": 1019.49,
  "currency": "credit"
}

If you see your balance, you’re in. If you see 401 invalid_api_key, double-check the header name (X-Api-Key, not Authorization) and the value.

2. Estimate cost without committing

POST /v1/images/estimate mirrors the body shape of POST /v1/images and returns the credit cost the real call would charge — no row inserted, no balance held. Use it to power “what will this cost?” UIs.

curl -X POST https://api.aurous-labs.com/v1/images/estimate \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A golden retriever wearing sunglasses, cinematic lighting",
    "size": "hd_square"
  }'

{
  "object": "estimate",
  "estimated_cost": { "amount": 2, "currency": "credit", "breakdown": { "base": 1, "enhance": 1 } },
  "currency": "credit"
}

The full live rate card is at GET /v1/pricing — frozen per Aurous-Version, so price changes are never silently retroactive.

3. Generate an image

Pick a LoRA from GET /v1/loras and pass its id (or slug) as lora_id. Or omit lora_id entirely and the platform’s dispatcher picks a style based on your prompt.

curl

# Pick a LoRA (or omit lora_id and let the dispatcher choose)
curl https://api.aurous-labs.com/v1/loras \
  -H "X-Api-Key: $AUROUS_API_KEY"

# Create the generation
curl -X POST https://api.aurous-labs.com/v1/images \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "prompt": "A golden retriever wearing sunglasses, cinematic lighting",
    "lora_id": "lora_01HXMQ7Z3K8Y2ABCDEFGHJKM",
    "size": "hd_square"
  }'

The response carries the row in its initial queued (or processing) state. The Idempotency-Key header is optional but recommended — see Idempotency for how safe retries work.

4. Poll for completion

GET /v1/images/{id} returns the live row. Loop until status is one of the terminal values: succeeded, failed, cancelled, expired, moderation_rejected.

curl https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2ABCDEFGHJKM \
  -H "X-Api-Key: $AUROUS_API_KEY"

A succeeded response looks like:

{
  "id": "img_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "status": "succeeded",
  "prompt": "A golden retriever wearing sunglasses, cinematic lighting",
  "output_urls": [
    "https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2ABCDEFGHJKM/output/0?token=..."
  ],
  "cost": { "amount": 2, "currency": "credit", "breakdown": { "base": 1, "enhance": 1 } },
  "created_at": "2026-05-04T10:00:00Z",
  "completed_at": "2026-05-04T10:00:14Z"
}

Most generations finish in 10–30 seconds. Poll on a 2-second interval with exponential backoff if you want to be a good citizen, and watch for 429 — see Rate limits.

5. Read the output

output_urls[0] is a signed proxy URL on api.aurous-labs.com. Fetch it directly — no auth header needed, the signature is in the query string:

curl -L -o image.png \
  "https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2ABCDEFGHJKM/output/0?token=..."

Output URLs expire ~24 hours after generation (410 Gone after that). Save what you want to keep — long-term storage is intentionally not part of the platform.

Skip polling — use webhooks

Polling is fine for prototypes. For production, register a webhook endpoint and we’ll POST a signed payload the moment the generation reaches succeeded / failed / cancelled:

curl -X POST https://api.aurous-labs.com/v1/webhook_endpoints \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.dev/aurous-webhook",
    "events": ["image.completed", "image.failed"]
  }'

The response carries a one-time secret — store it. See Webhooks for the full signature-verification cookbook (Node + Python + curl).

Response headers worth knowing

Every response carries:

• Aurous-Request-Id: req_<26-char ULID> — quote this in any support ticket so we can find your request.
• Aurous-Version: YYYY-MM-DD — the API version applied to this response. Pin a specific version with the Aurous-Version request header to insulate yourself from future changes.
• X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset — see Rate limits.

Where to next?

• Authentication — key formats, scopes, rotation, the 24h grace window.
• Errors — every type, every code, what to do.
• Idempotency — safe retries on POST /v1/images and /v1/videos.
• Rate limits — per-team buckets, headers, what 429 means.
• Webhooks — signed deliveries, retries, secret rotation.
• API reference — every endpoint, every parameter.