Filmsquare

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"
Verstuur een requestGET /v1/me

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

BASIS-URL
https://app.filmsquare.ai/v1
EERSTE CALLS
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

Keys hebben geen scopes. De macht van een key is zijn rol in één workspace, nooit boven de rol van de persoon erachter.

KEYHOE
Persoonlijke keySettings → Claude → Use a personal key instead. Je eigen rol, eenmalig getoond.
Workspace-keyPOST /workspaces/{ws}/api-keys met een naam en een rol, door een producent of eigenaar. Eenmalig getoond; alleen de hash wordt bewaard.
IntrekkenPOST /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

ÉÉN OPERATIE
"/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

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

EVENTVERSTUURD ALS
generation.succeededEen take is klaar met renderen
generation.failedEen render is mislukt
take.selectedEr is een take gekozen op een shot of scène
asset_version.createdEen render leverde een nieuwe assetversie op
["*"]Elk event
ABONNEREN
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"]}'
EEN OPLEVERING
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

ONDERWERPREGEL
VeldnamenResponses in snake_case, request-bodies in camelCase.
LijstenLijsten antwoorden met {"items": […], "next_cursor": "…"}. Geef cursor mee voor de volgende pagina, limit tot 200, order asc of desc.
IdempotentieTake-requests accepteren een Idempotency-Key-header: dezelfde key geeft dezelfde take terug.
VerwijderenRijen worden gearchiveerd, nooit verwijderd. Versies, gekozen takes, akkoorden en kosten veranderen nooit.
Niet zichtbaarEen rij die je niet mag zien antwoordt 404, net als een rij die niet bestaat.
STATUSCODEWANNEER
400validation_errorDe body, query of een padparameter komt niet overeen met het schema
401unauthenticatedGeen token, of een ingetrokken of verlopen token
402out_of_creditsNiet genoeg credits vrij voor deze take
402plan_limitJe abonnement bevat het niet, zoals een final op Free
402budget_exceededHet creditbudget van de aflevering zou worden overschreden
403insufficient_roleJe rol ligt onder de x-min-role van de route
403account_blockedHet account is geschorst; elk verzoek wordt geweigerd
404not_foundDe rij bestaat niet, of je mag hem niet zien
409gate_closedEen final voordat de departementen waarop hij wacht hebben afgetekend
409workspace_pausedDe workspace is gepauzeerd: er start geen nieuwe take of tool in
ELKE FOUT HEEFT ÉÉN VORM
{"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.

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

Vragen

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.