API et MCP de Cirrela

Démarrage rapide

1. Créez une clé dans les Paramètres, rubrique API et MCP (formule Studio).
2. Lancez une vidéo. La réponse arrive tout de suite, avec un identifiant et status: queued.
3. Redemandez-la jusqu’à ce que status vaille completed, puis téléchargez 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"

Une vidéo prend environ 1 à 3 minutes, une image environ 20 secondes. Un rendu qui échoue est remboursé automatiquement.

Authentification

Envoyez votre clé dans l’en-tête Authorization à chaque requête. Les clés commencent par cir_live_ et ne sont affichées qu’une fois, à leur création. Gardez-les sur un serveur : toute personne qui a une clé peut dépenser vos crédits.

Authorization: Bearer cir_live_your_key

Révoquez une clé dans les Paramètres et elle s’arrête aussitôt. Les clés s’arrêtent aussi tant que le compte n’est pas sur Studio ou qu’il est suspendu, et remarchent quand il revient sur Studio.

URL de base https://cirrela.com/api/v1

Créer une vidéo ou une image

POST /v1/generations prend du JSON. Seul prompt est obligatoire : le reste part des réglages du niveau, comme dans le studio.

Envoyez un en-tête Idempotency-Key (une chaîne unique de 255 caractères au plus) pour réessayer sans risque : la même clé avec le même corps renvoie la même création pendant 24 heures, sans facturer deux fois. La même clé avec un autre corps est refusée avec une 409.

Chaque requête passe par les contrôles du studio : le prix est débité au lancement du rendu et rendu en cas d’échec, le filtre de prompts s’applique, comme les limites de votre formule (rendus en même temps, rendus par jour, résolution). Les fichiers portent les métadonnées « généré par IA ».

Routes

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" }

Erreurs

Les erreurs sont du JSON avec un code stable. Décidez d’après le code, pas le message : les messages sont écrits pour des personnes et peuvent changer.

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

Un rendu qui échoue plus tard n’est pas une erreur HTTP : GET /v1/generations/:id répond status: failed, error.message explique pourquoi en clair, et refunded vaut true.

Limites de requêtes

Chaque clé peut envoyer 120 requêtes par minute, et lancer 20 rendus par minute. Les limites de votre formule s’appliquent aussi : sur Studio, 8 rendus en même temps et 1 500 par jour.

Chaque réponse porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes Unix) ; une 429 ajoute Retry-After, en secondes.

Serveur MCP pour Claude, ChatGPT et les agents

Avec le serveur MCP, un assistant IA crée des vidéos sur votre compte. Demandez à Claude « fais-moi une vidéo 9:16 d’un renard qui court dans la neige » : il vérifie le prix, lance le rendu et vous rapporte le lien.

https://cirrela.com/api/mcp

Streamable HTTP, réponses en JSON, sans session. Votre clé d’API va dans l’en-tête Authorization.

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" }
    }
  }
}