Filmsquare HelpDocs

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.

Bijgewerkt 5 min lezen.md

Op deze pagina
  1. Authenticatie
  2. Een sleutel krijgen
  3. Een persoonlijke sleutel (elke rol)
  4. Een workspace-API-sleutel (producent en hoger)
  5. Rollen
  6. Een eerste sessie
  7. Conventies
  8. Fouten die je tegenkomt
  9. Gerelateerd

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-URLhttps://app.filmsquare.ai/v1
FormaatJSON over HTTPS
AuthAuthorization: Bearer <API key or session token>
Referentiehttps://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) #

  1. Open in de studio het workspacemenu bovenaan de zijbalk en kies Settings en daarna Claude.
  2. Kies Use a personal key instead, geef hem een naam en kies Create a personal key.
  3. 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 #

OnderwerpRegel
VeldnamenAntwoorden 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 rijenWeggelaten uit lijsten tenzij includeArchived=true
VerwijderenRijen worden gearchiveerd (POST …/{id}/archive), niet verwijderd. Versies, gekozen takes, akkoorden en kosten veranderen nooit
IdempotentieGeneratieverzoeken nemen een Idempotency-Key-header (of idempotencyKey in de body): dezelfde sleutel geeft de bestaande generatie terug
GeldKosten 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"]}}}
StatusCodeWanneerdetails
400validation_errorDe body, de query of een padparameter past niet bij het schemaDe lijst met validatieproblemen
400bad_request, invalid_valueDe route weigert het verzoek, of de database kan een waarde niet lezen (zoals een misvormde id)—
400url_not_allowedEen webhook- of import-URL is geen openbaar http(s)-adres—
401unauthenticatedGeen token, of een ingetrokken of verlopen token—
402out_of_creditsNiet genoeg credits vrij te besteden voor deze takeneeded, available (credits)
402plan_limitHet abonnement omvat dit niet: een final op Free, een tweede productie, opslag, seats, pakketten zonder abonnementlimit (final, productions, storage, seats, packs), plan
402budget_exceededHet budget van de aflevering (budgetCredits op de aflevering) zou worden overschredenepisodeId, budgetCredits, spent, inFlight, needed (credits)
403insufficient_roleJe rol ligt onder het minimum van de routerequired, actual
403not_a_signerJe bent geen aftekenaar van dit departement—
403role_exceeds_callerEen uitnodiging of sleutel met een rol boven de jouwe—
403not_a_personSleutels beheren met een persoonlijke sleutel of een Claude-koppeling—
404not_foundDe rij bestaat niet, of je mag hem niet zien—
409gate_closedEen final voordat er groen licht isepisode_id, waiting_on (departementen, of placement voor een shot in geen enkele aflevering)
409changed_sinceJe tekende een versie af die niet meer de huidige isversion (de huidige)
409already_signed_offDe stap is al afgetekend—
409element_version_frozenEen referentie toegevoegd aan een versie die een take al gebruikte—
409conflictEr bestaat al een rij met deze waarden—
422foreign_key_violation, check_violation, not_null_violationEen verwezen rij bestaat niet (of zit in een andere workspace), of een databaseregel weigerde de waardenconstraint, 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}}}

Deze pagina als Markdown: /docs/nl/api/overview.md