Filmsquare AideDocs

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.

Mis à jour 5 min de lecture.md

Sur cette page
  1. Authentification
  2. Obtenir une clé
  3. Une clé personnelle (n'importe quel rôle)
  4. Une clé d'API d'espace de travail (producteur et au-dessus)
  5. Rôles
  6. Une première session
  7. Conventions
  8. Erreurs que vous rencontrerez
  9. À lire aussi

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 basehttps://app.filmsquare.ai/v1
FormatJSON sur HTTPS
AuthentificationAuthorization: Bearer <API key or session token>
Référencehttps://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) #

  1. Dans le studio, ouvrez le menu de l'espace de travail, en haut de la barre latérale, et choisissez Settings, puis Claude.
  2. Choisissez Use a personal key instead, donnez-lui un nom, et choisissez Create a personal key.
  3. 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 #

SujetRègle
Noms de champsRé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éesExclues des listes sauf si includeArchived=true
SuppressionLes lignes sont archivées (POST …/{id}/archive), pas supprimées. Les versions, prises retenues, validations et coûts ne sont jamais modifiés
IdempotenceLes 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
ArgentLes 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"]}}}
StatutCodeQuanddetails
400validation_errorLe corps, la requête ou un paramètre de chemin ne correspond pas au schémaLa liste des problèmes de validation
400bad_request, invalid_valueLa route refuse la requête, ou la base de données ne peut pas lire une valeur (comme un id mal formé)—
400url_not_allowedUne URL de webhook ou d'import n'est pas une adresse http(s) publique—
401unauthenticatedPas de jeton, ou un jeton révoqué ou expiré—
402out_of_creditsPas assez de crédits disponibles à dépenser pour cette priseneeded, available (crédits)
402plan_limitLa formule n'inclut pas cela : une version finale sur Free, une deuxième production, le stockage, les licences, les packs sans formulelimit (final, productions, storage, seats, packs), plan
402budget_exceededLe budget de l'épisode (budgetCredits sur l'épisode) serait dépasséepisodeId, budgetCredits, spent, inFlight, needed (crédits)
403insufficient_roleVotre rôle est en dessous du minimum de la routerequired, actual
403not_a_signerVous n'êtes pas valideur de ce département—
403role_exceeds_callerUne invitation ou une clé avec un rôle supérieur au vôtre—
403not_a_personGérer des clés avec une clé personnelle ou une connexion Claude—
404not_foundLa ligne n'existe pas, ou vous ne pouvez pas la voir—
409gate_closedUne version finale demandée avant le feu vertepisode_id, waiting_on (départements, ou placement pour un plan dans aucun épisode)
409changed_sinceVous avez validé une version qui n'est plus la version actuelleversion (l'actuelle)
409already_signed_offL'étape est déjà validée—
409element_version_frozenUne référence ajoutée à une version qu'une prise a déjà utilisée—
409conflictUne ligne avec ces valeurs existe déjà—
422foreign_key_violation, check_violation, not_null_violationUne 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 valeursconstraint, 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}}}

Cette page en Markdown: /docs/fr/api/overview.md