API
Le studio, en API.
L’API REST de Filmsquare est la même API que celle du studio et du Claude de chaque personne, ouverte à vos scripts. JSON sur HTTPS, un seul document OpenAPI 3.1 généré à partir des routes, une clé porteuse par personne et par espace de travail, et des webhooks signés pour savoir quand une prise est prête.
curl -s "$FS/me" \
-H "Authorization: Bearer $FS_KEY"
WEBHOOK · POST /filmsquare/hook

S3-B5-05Seedance 2.5 · Version finale 1080p · 5 s · 105,30 crédits · 5,27 €
URL DE BASE ET AUTHENTIFICATION
Une clé, un rôle, un espace de travail
Chaque appel envoie Authorization: Bearer <token> : une clé d’API commençant par fsk_, ou une session connectée. Les routes d’espace de travail portent l’espace de travail dans le chemin, /v1/workspaces/{ws}/….
https://app.filmsquare.ai/v1export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_…
# Who you are, and your workspaces
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
# A draft take of a shot (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"}'ownerproducerdirectormakerreviewerviewer
Les clés n’ont pas de portées. Le pouvoir d’une clé, c’est son rôle dans un seul espace de travail, jamais au-dessus du rôle de la personne derrière.
| CLÉ | COMMENT |
|---|---|
| Clé personnelle | Settings → Claude → Use a personal key instead (utiliser plutôt une clé personnelle). Votre propre rôle, affiché une seule fois. |
| Clé d’espace de travail | POST /workspaces/{ws}/api-keys avec un nom et un rôle, par un producteur ou un propriétaire. Affichée une seule fois ; seul son hash est conservé. |
| Révoquer | POST /workspaces/{ws}/api-keys/{id}/revoke. L’appel suivant avec elle répond 401 api_key_revoked. |
OPENAPI 3.1
Un seul nom pour un appel et une tâche
GET https://app.filmsquare.ai/v1/openapi.json est public, en OpenAPI 3.1, et généré à partir des routes elles-mêmes. Chaque route a un operationId, le même nom que Claude exécute avec run_action, si bien qu’un appel que vous scriptez et une tâche que vous confiez à Claude ne font qu’un. x-min-role indique le rôle le plus bas autorisé à l’appeler. Référence OpenAPI · MCP pour Claude
"/workspaces/{ws}/shots/{id}/generations": {
"post": {
"operationId": "generateForShot",
"x-min-role": "maker",
…
}
}curl -s https://app.filmsquare.ai/v1/openapi.json | jq '.paths | keys | length'WEBHOOKS
S’abonner plutôt que d’interroger en boucle
Producteur et au-dessus ; le secret whsec_ n’est affiché qu’une fois. Répondez par un 2xx. Sur 5xx, 429 ou un délai dépassé, Filmsquare réessaie avec un backoff exponentiel, d’environ 2 secondes jusqu’à 10 minutes entre deux essais, jusqu’à 8 tentatives. x-fs-delivery reste identique d’un essai à l’autre. Webhooks
| ÉVÉNEMENT | ENVOYÉ QUAND |
|---|---|
generation.succeeded | Une prise a fini son rendu |
generation.failed | Un rendu a échoué |
take.selected | Une prise a été retenue sur un plan ou une séquence |
asset_version.created | Un rendu a produit une nouvelle version de média |
["*"] | Tous les événements |
curl -s -X POST "$FS/workspaces/$WS/webhooks" \
-H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
-d '{"url": "https://example.com/filmsquare/hook", "events": ["generation.succeeded", "take.selected"]}'POST /filmsquare/hook
content-type: application/json
x-fs-signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with whsec_…>
x-fs-event: generation.succeeded
x-fs-delivery: generation.succeeded:9b2e…CONVENTIONS ET ERREURS
Toute erreur a la même forme
| SUJET | RÈGLE |
|---|---|
| Noms de champs | Réponses en snake_case, corps de requête en camelCase. |
| Listes | Les listes répondent {"items": […], "next_cursor": "…"}. Passez cursor pour la page suivante, limit jusqu’à 200, order asc ou desc. |
| Idempotence | Les requêtes de prise acceptent un en-tête Idempotency-Key : la même clé renvoie la même prise. |
| Suppression | Les lignes sont archivées, jamais supprimées. Les versions, prises retenues, validations et coûts ne changent jamais. |
| Non visible | Une ligne que vous n’avez pas le droit de voir répond 404, comme une ligne qui n’existe pas. |
| STATUT | CODE | QUAND |
|---|---|---|
| 400 | validation_error | Le corps, la requête ou un paramètre de chemin ne correspond pas au schéma |
| 401 | unauthenticated | Pas de jeton, ou un jeton révoqué ou expiré |
| 402 | out_of_credits | Pas assez de crédits libres pour cette prise |
| 402 | plan_limit | La formule ne l’inclut pas, comme une version finale sur Free |
| 402 | budget_exceeded | Le budget de l’épisode en crédits serait dépassé |
| 403 | insufficient_role | Votre rôle est inférieur au x-min-role de la route |
| 403 | account_blocked | Le compte est suspendu ; toutes les requêtes sont refusées |
| 404 | not_found | La ligne n’existe pas, ou vous n’avez pas le droit de la voir |
| 409 | gate_closed | Une version finale avant la validation des départements qu’elle attend |
| 409 | workspace_paused | L’espace de travail est en pause : aucune nouvelle prise ni aucun outil n’y démarre |
{"error": {"code": "gate_closed",
"message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}GET /v1/pricing ne demande pas de clé. Il renvoie le prix d’un crédit en euros, le prix des licences et les crédits qu’apporte une licence, le report, le stockage et les packs de crédits : les chiffres derrière les tarifs.
curl -s https://app.filmsquare.ai/v1/pricingQuestions
L’API est-elle la même que celle du studio ?
Oui. Le studio, le Claude de chaque personne et vos scripts appellent les mêmes routes, avec les mêmes rôles et les mêmes règles.
Les clés d’API ont-elles des portées ?
Non. Une clé fonctionne dans un seul espace de travail avec un seul rôle, jamais au-dessus du rôle de la personne qui l’a créée. Le rôle est la portée.
Où est la référence ?
Le document OpenAPI 3.1 à l’adresse https://app.filmsquare.ai/v1/openapi.json est public et généré à partir des routes, donc il ne prend jamais de retard sur elles.
Comment savoir quand une prise est prête ?
Abonnez un webhook à generation.succeeded. Les livraisons sont signées avec x-fs-signature et retentées sur 5xx, 429 et délais dépassés.
Un script peut-il lancer des rendus finaux avant validation ?
Non. Une version finale avant l’ouverture du feu vert répond 409 gate_closed, avec les départements qu’elle attend.
Les tarifs sont-ils lisibles sans clé ?
Oui. GET https://app.filmsquare.ai/v1/pricing est public et renvoie le prix du crédit, le prix des licences, le report et les packs.