API
De studio, als API.
De REST API van Filmsquare is dezelfde API die de studio en de eigen Claude van een persoon gebruiken, opengesteld voor je scripts. JSON over HTTPS, één OpenAPI 3.1-document gegenereerd uit de routes, een bearer-key per persoon en workspace, en ondertekende webhooks voor als een take klaar is.
curl -s "$FS/me" \
-H "Authorization: Bearer $FS_KEY"
WEBHOOK · POST /filmsquare/hook

S3-B5-05Seedance 2.5 · Final 1080p · 5 s · 105,30 credits · € 5,27
BASIS-URL EN AUTH
Eén key, één rol, één workspace
Elke call stuurt Authorization: Bearer <token> mee: een API-key die begint met fsk_, of een ingelogde sessie. Workspace-routes dragen de workspace in het pad, /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
Keys hebben geen scopes. De macht van een key is zijn rol in één workspace, nooit boven de rol van de persoon erachter.
| KEY | HOE |
|---|---|
| Persoonlijke key | Settings → Claude → Use a personal key instead. Je eigen rol, eenmalig getoond. |
| Workspace-key | POST /workspaces/{ws}/api-keys met een naam en een rol, door een producent of eigenaar. Eenmalig getoond; alleen de hash wordt bewaard. |
| Intrekken | POST /workspaces/{ws}/api-keys/{id}/revoke. De eerstvolgende call ermee antwoordt 401 api_key_revoked. |
OPENAPI 3.1
Eén naam voor een call en een klus
GET https://app.filmsquare.ai/v1/openapi.json is openbaar, OpenAPI 3.1, en gegenereerd uit de routes zelf. Elke route heeft een operationId, dezelfde naam waarmee Claude hem uitvoert met run_action, dus een call die je scriptet en een klus die je aan Claude geeft zijn één en hetzelfde. x-min-role noemt de laagste rol die hem mag aanroepen. OpenAPI-referentie · MCP voor 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
Abonneer je in plaats van te pollen
Vanaf producent; het whsec_-secret wordt eenmalig getoond. Antwoord met een 2xx. Bij 5xx, 429 of een timeout probeert Filmsquare het opnieuw met exponentiële backoff, van ongeveer 2 seconden tot 10 minuten tussen pogingen, tot 8 pogingen. x-fs-delivery blijft gelijk bij elke nieuwe poging. Webhooks
| EVENT | VERSTUURD ALS |
|---|---|
generation.succeeded | Een take is klaar met renderen |
generation.failed | Een render is mislukt |
take.selected | Er is een take gekozen op een shot of scène |
asset_version.created | Een render leverde een nieuwe assetversie op |
["*"] | Elk event |
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…CONVENTIES EN FOUTEN
Elke fout heeft één vorm
| ONDERWERP | REGEL |
|---|---|
| Veldnamen | Responses in snake_case, request-bodies in camelCase. |
| Lijsten | Lijsten antwoorden met {"items": […], "next_cursor": "…"}. Geef cursor mee voor de volgende pagina, limit tot 200, order asc of desc. |
| Idempotentie | Take-requests accepteren een Idempotency-Key-header: dezelfde key geeft dezelfde take terug. |
| Verwijderen | Rijen worden gearchiveerd, nooit verwijderd. Versies, gekozen takes, akkoorden en kosten veranderen nooit. |
| Niet zichtbaar | Een rij die je niet mag zien antwoordt 404, net als een rij die niet bestaat. |
| STATUS | CODE | WANNEER |
|---|---|---|
| 400 | validation_error | De body, query of een padparameter komt niet overeen met het schema |
| 401 | unauthenticated | Geen token, of een ingetrokken of verlopen token |
| 402 | out_of_credits | Niet genoeg credits vrij voor deze take |
| 402 | plan_limit | Je abonnement bevat het niet, zoals een final op Free |
| 402 | budget_exceeded | Het creditbudget van de aflevering zou worden overschreden |
| 403 | insufficient_role | Je rol ligt onder de x-min-role van de route |
| 403 | account_blocked | Het account is geschorst; elk verzoek wordt geweigerd |
| 404 | not_found | De rij bestaat niet, of je mag hem niet zien |
| 409 | gate_closed | Een final voordat de departementen waarop hij wacht hebben afgetekend |
| 409 | workspace_paused | De workspace is gepauzeerd: er start geen nieuwe take of tool in |
{"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 heeft geen key nodig. Het geeft de prijs van een credit in euro, seatprijzen en de credits die een seat meebrengt, rollover, opslag en creditpakketten: de cijfers achter prijzen.
curl -s https://app.filmsquare.ai/v1/pricingVragen
Is de API dezelfde als die de studio gebruikt?
Ja. De studio, de eigen Claude van een persoon en je scripts roepen dezelfde routes aan, met dezelfde rollen en dezelfde regels.
Hebben API-keys scopes?
Nee. Een key werkt in één workspace met één rol, nooit boven de rol van de persoon die hem heeft gemaakt. De rol is de scope.
Waar vind ik de referentie?
Het OpenAPI 3.1-document op https://app.filmsquare.ai/v1/openapi.json is openbaar en gegenereerd uit de routes, dus het loopt er nooit op achter.
Hoe weet ik wanneer een take klaar is?
Abonneer een webhook op generation.succeeded. Leveringen worden ondertekend met x-fs-signature en opnieuw geprobeerd bij 5xx, 429 en timeouts.
Kan een script finals renderen vóór het akkoord?
Nee. Een final vóór het groene licht antwoordt 409 gate_closed, met de departementen waarop hij wacht.
Zijn de prijzen leesbaar zonder key?
Ja. GET https://app.filmsquare.ai/v1/pricing is openbaar en geeft de creditprijs, seatprijzen, rollover en creditpakketten terug.