Filmsquare

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"
Envoyer une requêteGET /v1/me

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}/….

URL DE BASE
https://app.filmsquare.ai/v1
PREMIERS APPELS
export 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"}'
  1. owner
  2. producer
  3. director
  4. maker
  5. reviewer
  6. viewer

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é personnelleSettings → Claude → Use a personal key instead (utiliser plutôt une clé personnelle). Votre propre rôle, affiché une seule fois.
Clé d’espace de travailPOST /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évoquerPOST /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

UNE OPÉRATION
"/workspaces/{ws}/shots/{id}/generations": {
  "post": {
    "operationId": "generateForShot",
    "x-min-role": "maker",
    …
  }
}
TERMINAL
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ÉNEMENTENVOYÉ QUAND
generation.succeededUne prise a fini son rendu
generation.failedUn rendu a échoué
take.selectedUne prise a été retenue sur un plan ou une séquence
asset_version.createdUn rendu a produit une nouvelle version de média
["*"]Tous les événements
S’ABONNER
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"]}'
UNE LIVRAISON
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

SUJETRÈGLE
Noms de champsRéponses en snake_case, corps de requête en camelCase.
ListesLes listes répondent {"items": […], "next_cursor": "…"}. Passez cursor pour la page suivante, limit jusqu’à 200, order asc ou desc.
IdempotenceLes requêtes de prise acceptent un en-tête Idempotency-Key : la même clé renvoie la même prise.
SuppressionLes lignes sont archivées, jamais supprimées. Les versions, prises retenues, validations et coûts ne changent jamais.
Non visibleUne ligne que vous n’avez pas le droit de voir répond 404, comme une ligne qui n’existe pas.
STATUTCODEQUAND
400validation_errorLe corps, la requête ou un paramètre de chemin ne correspond pas au schéma
401unauthenticatedPas de jeton, ou un jeton révoqué ou expiré
402out_of_creditsPas assez de crédits libres pour cette prise
402plan_limitLa formule ne l’inclut pas, comme une version finale sur Free
402budget_exceededLe budget de l’épisode en crédits serait dépassé
403insufficient_roleVotre rôle est inférieur au x-min-role de la route
403account_blockedLe compte est suspendu ; toutes les requêtes sont refusées
404not_foundLa ligne n’existe pas, ou vous n’avez pas le droit de la voir
409gate_closedUne version finale avant la validation des départements qu’elle attend
409workspace_pausedL’espace de travail est en pause : aucune nouvelle prise ni aucun outil n’y démarre
TOUTE 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"]}}}

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.

TERMINAL
curl -s https://app.filmsquare.ai/v1/pricing

Questions

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.