6.0 API6.1 Aperçu de l'API et clés
Aperçu de l'API et clés
L'API REST de Filmsquare : URL de base, authentification par clé d'API ou session, comment créer une clé, conventions, et les erreurs que vous rencontrerez.
Tout ce que fait le studio passe par une seule API REST, et vous pouvez l'utiliser aussi : l'app, votre propre Claude et vos scripts appellent les mêmes routes, avec les mêmes rôles et les mêmes règles.
| URL de base | https://app.filmsquare.ai/v1 |
| Format | JSON sur HTTPS |
| Authentification | Authorization: Bearer <API key or session token> |
| Référence | https://app.filmsquare.ai/v1/openapi.json (OpenAPI 3.1, publique). Voir Référence OpenAPI |
Authentification #
Chaque route, sauf quelques routes publiques (GET /v1/pricing, POST /v1/signup, les récepteurs de webhooks), demande
un jeton bearer :
- Une clé d'API, qui commence par
fsk_. Une clé appartient à une personne (ou à un agent) dans un seul espace de travail, et agit avec le rôle de la clé, jamais plus que le rôle actuel de cette personne. - Un jeton de session d'une personne connectée (ce qu'envoie l'app web).
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_… # your key
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
GET /me renvoie qui vous êtes, si vous êtes entré avec une clé, et vos espaces de travail. Chaque route d'espace de
travail a l'id de l'espace de travail dans son chemin : /v1/workspaces/{ws}/….
Obtenir une clé #
Une clé personnelle (n'importe quel rôle) #
- Dans le studio, ouvrez le menu de l'espace de travail, en haut de la barre latérale, et choisissez Settings, puis Claude.
- Choisissez Use a personal key instead, donnez-lui un nom, et choisissez Create a personal key.
- Copiez la clé. Elle n'est affichée qu'une fois.
Une clé personnelle a votre propre rôle dans cet espace de travail. Elle est faite pour Claude Code, mais fonctionne pour tout appel d'API que votre rôle permet, sauf gérer des clés.
Une clé d'API d'espace de travail (producteur et au-dessus) #
Un producteur ou un propriétaire, connecté, peut créer des clés avec un rôle choisi par l'API :
curl -s -X POST "$FS/workspaces/$WS/api-keys" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "content-type: application/json" \
-d '{"name": "Render farm sync", "role": "maker"}'
La réponse contient la key complète une seule fois ; Filmsquare n'en garde que le hash. Le rôle d'une clé ne peut
jamais dépasser le vôtre. Avec userId, vous pouvez créer une clé pour un agent qui est membre de l'espace de
travail.
GET /workspaces/{ws}/api-keys liste les clés (préfixe seulement) ; POST /workspaces/{ws}/api-keys/{id}/revoke en
révoque une. Les clés ne peuvent pas créer de clés : ces routes demandent une personne connectée ou une clé d'espace de
travail, et refusent une clé personnelle ou une connexion Claude avec 403 not_a_person.
Rôles #
Chaque route a un rôle minimum : owner > producer > director > maker > reviewer > viewer. Un appel en dessous
reçoit 403 insufficient_role avec {"required": "director", "actual": "maker"}. Une ligne que vous ne pouvez pas voir
répond 404, comme une ligne qui n'existe pas. Voir Équipe, rôles et accès.
Une première session #
# Your productions
curl -s "$FS/workspaces/$WS/projects" -H "Authorization: Bearer $FS_KEY"
# An episode's steps and the finals gate
curl -s "$FS/workspaces/$WS/episodes/$EP/steps" -H "Authorization: Bearer $FS_KEY"
# Price a draft of a shot before making it
curl -s -X POST "$FS/workspaces/$WS/shots/$SHOT/estimate" \
-H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
-d '{"kind": "video", "tier": "draft"}'
# Make it (the same Idempotency-Key never makes it twice)
curl -s -X POST "$FS/workspaces/$WS/shots/$SHOT/generations" \
-H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
-H "Idempotency-Key: shot-$SHOT-draft-1" \
-d '{"kind": "video", "tier": "draft"}'
# Follow it
curl -s "$FS/workspaces/$WS/generations?shotId=$SHOT&order=desc&limit=5" \
-H "Authorization: Bearer $FS_KEY"
kind vaut keyframe, video, dialogue, sfx ou music ; tier vaut draft ou final. Aucun modèle connecté ne
produit encore sfx ou music : ces prises arrivent par téléversement (createUploadTicket, puis completeUpload
avec une couche cible). Omettez modelKey et
Filmsquare route vers le modèle capable au coût le plus bas par prise acceptée. Plutôt que d'interroger en boucle,
abonnez-vous aux webhooks.
Conventions #
| Sujet | Règle |
|---|---|
| Noms de champs | Réponses en snake_case, corps de requête en camelCase |
| Listes | {"items": […], "next_cursor": "…"}. Passez cursor pour la page suivante ; limit jusqu'à 200 ; order asc ou desc |
| Lignes archivées | Exclues des listes sauf si includeArchived=true |
| Suppression | Les lignes sont archivées (POST …/{id}/archive), pas supprimées. Les versions, prises retenues, validations et coûts ne sont jamais modifiés |
| Idempotence | Les demandes de prise acceptent un en-tête Idempotency-Key (ou idempotencyKey dans le corps) : la même clé renvoie la prise déjà lancée |
| Argent | Les coûts sont en crédits, chacun au tarif en vigueur au début du travail ; ce que coûte un crédit en euros figure dans GET /v1/pricing et Crédits et ce que coûtent les choses |
Erreurs que vous rencontrerez #
Chaque erreur a la même forme :
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
| Statut | Code | Quand | details |
|---|---|---|---|
| 400 | validation_error | Le corps, la requête ou un paramètre de chemin ne correspond pas au schéma | La liste des problèmes de validation |
| 400 | bad_request, invalid_value | La route refuse la requête, ou la base de données ne peut pas lire une valeur (comme un id mal formé) | — |
| 400 | url_not_allowed | Une URL de webhook ou d'import n'est pas une adresse http(s) publique | — |
| 401 | unauthenticated | Pas de jeton, ou un jeton révoqué ou expiré | — |
| 402 | out_of_credits | Pas assez de crédits disponibles à dépenser pour cette prise | needed, available (crédits) |
| 402 | plan_limit | La formule n'inclut pas cela : une version finale sur Free, une deuxième production, le stockage, les licences, les packs sans formule | limit (final, productions, storage, seats, packs), plan |
| 402 | budget_exceeded | Le budget de l'épisode (budgetCredits sur l'épisode) serait dépassé | episodeId, budgetCredits, spent, inFlight, needed (crédits) |
| 403 | insufficient_role | Votre rôle est en dessous du minimum de la route | required, actual |
| 403 | not_a_signer | Vous n'êtes pas valideur de ce département | — |
| 403 | role_exceeds_caller | Une invitation ou une clé avec un rôle supérieur au vôtre | — |
| 403 | not_a_person | Gérer des clés avec une clé personnelle ou une connexion Claude | — |
| 404 | not_found | La ligne n'existe pas, ou vous ne pouvez pas la voir | — |
| 409 | gate_closed | Une version finale demandée avant le feu vert | episode_id, waiting_on (départements, ou placement pour un plan dans aucun épisode) |
| 409 | changed_since | Vous avez validé une version qui n'est plus la version actuelle | version (l'actuelle) |
| 409 | already_signed_off | L'étape est déjà validée | — |
| 409 | element_version_frozen | Une référence ajoutée à une version qu'une prise a déjà utilisée | — |
| 409 | conflict | Une ligne avec ces valeurs existe déjà | — |
| 422 | foreign_key_violation, check_violation, not_null_violation | Une ligne référencée n'existe pas (ou est dans un autre espace de travail), ou une règle de la base de données a refusé les valeurs | constraint, table, detail |
402 out_of_credits ressemble à ceci :
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
"details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
À lire aussi #
- Webhooks
- Référence OpenAPI
- Ce que Claude peut faire : la même API via MCP