6.0 API6.1 API-overzicht en sleutels
API-overzicht en sleutels
De Filmsquare REST API: basis-URL, authenticatie met API-sleutels of een sessie, hoe je een sleutel maakt, conventies en de fouten die je tegenkomt.
Alles wat de studio doet, gaat via één REST API, en jij kunt hem ook gebruiken: de app, je eigen Claude en je scripts roepen dezelfde routes aan, met dezelfde rollen en dezelfde regels.
| Basis-URL | https://app.filmsquare.ai/v1 |
| Formaat | JSON over HTTPS |
| Auth | Authorization: Bearer <API key or session token> |
| Referentie | https://app.filmsquare.ai/v1/openapi.json (OpenAPI 3.1, openbaar). Zie OpenAPI-referentie |
Authenticatie #
Elke route behalve een paar openbare (GET /v1/pricing, POST /v1/signup, de webhookontvangers) vraagt een bearer
token:
- Een API-sleutel, beginnend met
fsk_. Een sleutel hoort bij één persoon (of agentgebruiker) in één workspace en handelt met de rol van de sleutel, nooit meer dan de huidige rol van die persoon. - Een sessietoken van een ingelogd persoon (wat de webapp stuurt).
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_… # your key
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
GET /me geeft terug wie je bent, of je met een sleutel binnenkwam en wat je workspaces zijn. Elke workspaceroute heeft
de workspace-id in zijn pad: /v1/workspaces/{ws}/….
Een sleutel krijgen #
Een persoonlijke sleutel (elke rol) #
- Open in de studio het workspacemenu bovenaan de zijbalk en kies Settings en daarna Claude.
- Kies Use a personal key instead, geef hem een naam en kies Create a personal key.
- Kopieer de sleutel. Hij wordt één keer getoond.
Een persoonlijke sleutel heeft je eigen rol in die workspace. Hij is gemaakt voor Claude Code, maar werkt voor elke API-aanroep die je rol toestaat, behalve sleutels beheren.
Een workspace-API-sleutel (producent en hoger) #
Een producent of eigenaar kan, ingelogd, via de API sleutels maken met een gekozen rol:
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"}'
Het antwoord bevat de volledige key één keer; Filmsquare bewaart alleen de hash. De rol van een sleutel kan nooit boven de jouwe liggen. Met
userId kun je een sleutel maken voor een agentgebruiker die lid is van de workspace.
GET /workspaces/{ws}/api-keys toont sleutels (alleen het voorvoegsel); POST /workspaces/{ws}/api-keys/{id}/revoke trekt er een in.
Sleutels kunnen geen sleutels maken: deze routes vragen een ingelogd persoon of een workspacesleutel, en weigeren een persoonlijke sleutel of een
Claude-koppeling met 403 not_a_person.
Rollen #
Elke route heeft een minimale rol: owner > producer > director > maker > reviewer > viewer. Een aanroep eronder
krijgt 403 insufficient_role met {"required": "director", "actual": "maker"}. Een rij die je niet mag zien, antwoordt 404,
net als een rij die niet bestaat. Zie Crew, rollen en toegang.
Een eerste sessie #
# 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 is keyframe, video, dialogue, sfx of music; tier is draft of final. Geen gekoppeld model
maakt al sfx of music: die takes komen binnen als uploads (createUploadTicket, dan completeUpload met een
doellaag). Laat modelKey weg en
Filmsquare routeert naar het geschikte model met de laagste kosten per geaccepteerde take. Abonneer je liever op
webhooks dan te pollen.
Conventies #
| Onderwerp | Regel |
|---|---|
| Veldnamen | Antwoorden in snake_case, request bodies in camelCase |
| Lijsten | {"items": […], "next_cursor": "…"}. Geef cursor mee voor de volgende pagina; limit tot 200; order asc of desc |
| Gearchiveerde rijen | Weggelaten uit lijsten tenzij includeArchived=true |
| Verwijderen | Rijen worden gearchiveerd (POST …/{id}/archive), niet verwijderd. Versies, gekozen takes, akkoorden en kosten veranderen nooit |
| Idempotentie | Generatieverzoeken nemen een Idempotency-Key-header (of idempotencyKey in de body): dezelfde sleutel geeft de bestaande generatie terug |
| Geld | Kosten zijn in credits, elk tegen het tarief waarop het werk begon; wat een credit in euro kost staat in GET /v1/pricing en Credits en wat dingen kosten |
Fouten die je tegenkomt #
Elke fout heeft dezelfde vorm:
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
| Status | Code | Wanneer | details |
|---|---|---|---|
| 400 | validation_error | De body, de query of een padparameter past niet bij het schema | De lijst met validatieproblemen |
| 400 | bad_request, invalid_value | De route weigert het verzoek, of de database kan een waarde niet lezen (zoals een misvormde id) | — |
| 400 | url_not_allowed | Een webhook- of import-URL is geen openbaar http(s)-adres | — |
| 401 | unauthenticated | Geen token, of een ingetrokken of verlopen token | — |
| 402 | out_of_credits | Niet genoeg credits vrij te besteden voor deze take | needed, available (credits) |
| 402 | plan_limit | Het abonnement omvat dit niet: een final op Free, een tweede productie, opslag, seats, pakketten zonder abonnement | limit (final, productions, storage, seats, packs), plan |
| 402 | budget_exceeded | Het budget van de aflevering (budgetCredits op de aflevering) zou worden overschreden | episodeId, budgetCredits, spent, inFlight, needed (credits) |
| 403 | insufficient_role | Je rol ligt onder het minimum van de route | required, actual |
| 403 | not_a_signer | Je bent geen aftekenaar van dit departement | — |
| 403 | role_exceeds_caller | Een uitnodiging of sleutel met een rol boven de jouwe | — |
| 403 | not_a_person | Sleutels beheren met een persoonlijke sleutel of een Claude-koppeling | — |
| 404 | not_found | De rij bestaat niet, of je mag hem niet zien | — |
| 409 | gate_closed | Een final voordat er groen licht is | episode_id, waiting_on (departementen, of placement voor een shot in geen enkele aflevering) |
| 409 | changed_since | Je tekende een versie af die niet meer de huidige is | version (de huidige) |
| 409 | already_signed_off | De stap is al afgetekend | — |
| 409 | element_version_frozen | Een referentie toegevoegd aan een versie die een take al gebruikte | — |
| 409 | conflict | Er bestaat al een rij met deze waarden | — |
| 422 | foreign_key_violation, check_violation, not_null_violation | Een verwezen rij bestaat niet (of zit in een andere workspace), of een databaseregel weigerde de waarden | constraint, table, detail |
402 out_of_credits ziet er zo uit:
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
"details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
Gerelateerd #
- Webhooks
- OpenAPI-referentie
- Wat Claude kan doen: dezelfde API via MCP