---
title: "Aperçu de l'API et clés"
description: "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."
url: https://www.filmsquare.ai/docs/fr/api/overview/
lang: fr
section: api
updated: 2026-11-10
---

# Aperçu de l'API et clés

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](https://www.filmsquare.ai/docs/fr/api/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).

```bash
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 :

```bash
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](https://www.filmsquare.ai/docs/fr/working-together/crew-and-roles/).

## Une première session

```bash
# 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](https://www.filmsquare.ai/docs/fr/api/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](https://www.filmsquare.ai/docs/fr/concepts/credits-and-costs/) |

## Erreurs que vous rencontrerez

Chaque erreur a la même forme :

```json
{"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 :

```json
{"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](https://www.filmsquare.ai/docs/fr/api/webhooks/)
- [Référence OpenAPI](https://www.filmsquare.ai/docs/fr/api/openapi/)
- [Ce que Claude peut faire](https://www.filmsquare.ai/docs/fr/claude/tools/) : la même API via MCP
