Cirrela API and MCP

Quickstart

1. Create a key in Settings, under API and MCP (Studio plan).
2. Start a video. The answer comes at once, with an id and status: queued.
3. Ask for it until status is completed, then download outputs[0].url.

curl https://cirrela.com/api/v1/generations \
  -H "Authorization: Bearer $CIRRELA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fox-snow-001" \
  -d '{
    "prompt": "A red fox running through fresh snow at sunrise",
    "tier": "great",
    "aspect_ratio": "9:16",
    "duration": 5
  }'

curl https://cirrela.com/api/v1/generations/GENERATION_ID \
  -H "Authorization: Bearer $CIRRELA_API_KEY"

A video takes about 1 to 3 minutes, an image about 20 seconds. A render that fails is refunded automatically.

Authentication

Send your key in the Authorization header on every request. Keys start with cir_live_ and are shown once, when you create them. Keep them on a server: anyone with a key can spend your credits.

Authorization: Bearer cir_live_your_key

Revoke a key in Settings and it stops at once. Keys also stop while the account isn't on Studio or is suspended, and work again when it is back on Studio.

Base URL https://cirrela.com/api/v1

Make a video or an image

POST /v1/generations takes JSON. Only prompt is required: the rest starts from the tier's settings, like in the studio.

Send an Idempotency-Key header (a unique string of up to 255 characters) to retry safely: the same key and body give back the same creation for 24 hours, without charging twice. The same key with another body is refused with 409.

Every request goes through the studio's own checks: the price is taken when the render starts and given back if it fails, the prompt filter applies, and so do your plan's limits (renders at once, renders a day, resolution). Files carry AI-generated metadata.

Endpoints

curl https://cirrela.com/api/v1/me -H "Authorization: Bearer $CIRRELA_API_KEY"

{
  "object": "account",
  "plan": "studio",
  "credits": 3170,
  "rendering": 1,
  "limits": { "parallel_renders": 8, "renders_per_day": 1500, "max_video_resolution": "4K", … }
}

curl https://cirrela.com/api/v1/models -H "Authorization: Bearer $CIRRELA_API_KEY"

curl https://cirrela.com/api/v1/estimates \
  -H "Authorization: Bearer $CIRRELA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A lighthouse in a storm", "tier": "cinema", "duration": 10 }'

{ "object": "estimate", "credits": 200, "balance": 3170, "affordable": true, … }

curl https://cirrela.com/api/v1/generations \
  -H "Authorization: Bearer $CIRRELA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fox-snow-001" \
  -d '{
    "prompt": "A red fox running through fresh snow at sunrise",
    "tier": "great",
    "aspect_ratio": "9:16",
    "duration": 5
  }'

{
  "id": "j57a8m3f0k2x9q1r4t6v",
  "object": "generation",
  "type": "video",
  "status": "queued",
  "progress": 0,
  "model": "minimax-h3",
  "tier": "great",
  "prompt": "A red fox running through fresh snow at sunrise",
  "settings": { "aspect_ratio": "9:16", "duration": 5, "sound": true, "resolution": "768P" },
  "credits": 30,
  "refunded": false,
  "outputs": [],
  "error": null,
  "public": false,
  "share_url": null,
  "ai_generated": true,
  "created_at": "2026-10-24T09:12:03.000Z",
  "completed_at": null
}

curl https://cirrela.com/api/v1/generations/GENERATION_ID \
  -H "Authorization: Bearer $CIRRELA_API_KEY"

{
  "id": "j57a8m3f0k2x9q1r4t6v",
  "status": "completed",
  "progress": 1,
  "outputs": [{ "url": "https://…/video.mp4", "width": 720, "height": 1280 }],
  …
}

curl "https://cirrela.com/api/v1/generations?limit=20&type=video" -H "Authorization: Bearer $CIRRELA_API_KEY"

{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "…" }

curl https://cirrela.com/api/v1/uploads \
  -H "Authorization: Bearer $CIRRELA_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

{ "id": "kg2…", "object": "upload" }

Errors

Errors are JSON with a stable code. Branch on the code, not the message: messages are written for people and can change.

{
  "error": {
    "code": "insufficient_credits",
    "message": "This generation needs 100 credits — you have 42. Top up to continue.",
    "details": { "required": 100, "balance": 42 }
  }
}

A render that fails later is not an HTTP error: GET /v1/generations/:id answers status: failed, error.message says why in plain words, and refunded is true.

Rate limits

Each key may send 120 requests a minute, and start 20 renders a minute. Your plan's limits still apply: on Studio, 8 renders at once and 1,500 a day.

Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds); a 429 adds Retry-After, in seconds.

MCP server for Claude, ChatGPT and agents

With the MCP server, an AI assistant makes videos on your account. Ask Claude “make me a 9:16 video of a fox running through snow”: it checks the price, starts the render and brings back the link.

https://cirrela.com/api/mcp

Streamable HTTP, JSON answers, no sessions. Your API key goes in the Authorization header.

claude mcp add --transport http cirrela https://cirrela.com/api/mcp \
  --header "Authorization: Bearer cir_live_your_key"

{
  "mcpServers": {
    "cirrela": {
      "type": "http",
      "url": "https://cirrela.com/api/mcp",
      "headers": { "Authorization": "Bearer cir_live_your_key" }
    }
  }
}