API
Das Studio als API.
Die REST-API von Filmsquare ist dieselbe API, die das Studio und der eigene Claude einer Person nutzen, offen für deine Skripte. JSON über HTTPS, ein OpenAPI-3.1-Dokument, aus den Routen generiert, ein Bearer-Key pro Person und Workspace und signierte Webhooks für den Moment, in dem ein Take fertig ist.
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 UND AUTH
Ein Key, eine Rolle, ein Workspace
Jeder Aufruf sendet Authorization: Bearer <token>: einen API-Key, der mit fsk_ beginnt, oder eine angemeldete Sitzung. Workspace-Routen tragen den Workspace im Pfad, /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 haben keine Scopes. Die Macht eines Keys ist seine Rolle in einem Workspace, nie über der Rolle der Person dahinter.
| KEY | WIE |
|---|---|
| Persönlicher Key | Settings → Claude → Use a personal key instead. Deine eigene Rolle, wird einmal angezeigt. |
| Workspace-Key | POST /workspaces/{ws}/api-keys mit Namen und Rolle, von einem Producer oder Owner. Wird einmal angezeigt; nur sein Hash wird gespeichert. |
| Widerrufen | POST /workspaces/{ws}/api-keys/{id}/revoke. Der nächste Aufruf damit antwortet 401 api_key_revoked. |
OPENAPI 3.1
Ein Name für Aufruf und Auftrag
GET https://app.filmsquare.ai/v1/openapi.json ist öffentlich, OpenAPI 3.1, und aus den Routen selbst generiert. Jede Route hat eine operationId, denselben Namen, mit dem Claude sie über run_action ausführt, sodass ein Aufruf, den du skriptest, und ein Auftrag, den du Claude gibst, ein und dasselbe sind. x-min-role nennt die niedrigste Rolle, die sie aufrufen darf. OpenAPI-Referenz · MCP für 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
Abonnieren statt pollen
Ab Producer; das whsec_-Secret wird einmal angezeigt. Antworte mit einem 2xx. Bei 5xx, 429 oder einem Timeout versucht Filmsquare es mit exponentiellem Backoff erneut, mit etwa 2 Sekunden bis zu 10 Minuten zwischen den Versuchen, bis zu 8 Versuche. x-fs-delivery bleibt über alle Wiederholungen gleich. Webhooks
| EREIGNIS | GESENDET, WENN |
|---|---|
generation.succeeded | Ein Take ist fertig gerendert |
generation.failed | Ein Render ist fehlgeschlagen |
take.selected | Ein Take wurde auf einer Einstellung oder Szene gewählt |
asset_version.created | Ein Render hat eine neue Asset-Version erzeugt |
["*"] | Alle Ereignisse |
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…KONVENTIONEN UND FEHLER
Jeder Fehler hat dieselbe Form
| THEMA | REGEL |
|---|---|
| Feldnamen | Antworten in snake_case, Request-Bodies in camelCase. |
| Listen | Listen antworten mit {"items": […], "next_cursor": "…"}. Gib cursor für die nächste Seite mit, limit bis 200, order asc oder desc. |
| Idempotenz | Take-Anfragen akzeptieren einen Idempotency-Key-Header: Derselbe Key liefert denselben Take. |
| Löschen | Zeilen werden archiviert, nie gelöscht. Versionen, gewählte Takes, Abnahmen und Kosten ändern sich nie. |
| Nicht sichtbar | Eine Zeile, die du nicht sehen darfst, antwortet mit 404, genau wie eine Zeile, die es nicht gibt. |
| STATUS | CODE | WANN |
|---|---|---|
| 400 | validation_error | Body, Query oder ein Pfadparameter passt nicht zum Schema |
| 401 | unauthenticated | Kein Token, oder ein widerrufenes oder abgelaufenes |
| 402 | out_of_credits | Nicht genug freie Credits für diesen Take |
| 402 | plan_limit | Der Tarif enthält es nicht, etwa ein Final im Free-Tarif |
| 402 | budget_exceeded | Das Budget der Folge in Credits würde überschritten |
| 403 | insufficient_role | Deine Rolle liegt unter dem x-min-role der Route |
| 403 | account_blocked | Das Konto ist gesperrt; jede Anfrage wird abgelehnt |
| 404 | not_found | Die Zeile gibt es nicht, oder du darfst sie nicht sehen |
| 409 | gate_closed | Ein Final, bevor die Gewerke, auf die es wartet, abgenommen haben |
| 409 | workspace_paused | Der Workspace ist pausiert: Es startet darin kein neuer Take und kein Tool |
{"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 braucht keinen Key. Es liefert den Preis eines Credits in Euro, die Seat-Preise und die Credits, die ein Seat mitbringt, Übertrag, Speicher und Credit-Pakete: die Zahlen hinter den Preisen.
curl -s https://app.filmsquare.ai/v1/pricingFragen
Ist die API dieselbe wie im Studio?
Ja. Das Studio, der eigene Claude einer Person und deine Skripte rufen dieselben Routen auf, mit denselben Rollen und denselben Regeln.
Haben API-Keys Scopes?
Nein. Ein Key gilt in einem Workspace mit einer Rolle, nie über der Rolle der Person, die ihn erstellt hat. Die Rolle ist der Scope.
Wo ist die Referenz?
Das OpenAPI-3.1-Dokument unter https://app.filmsquare.ai/v1/openapi.json ist öffentlich und aus den Routen generiert, es hinkt ihnen also nie hinterher.
Woher weiß ich, dass ein Take fertig ist?
Abonniere einen Webhook auf generation.succeeded. Zustellungen sind mit x-fs-signature signiert und werden bei 5xx, 429 und Timeouts wiederholt.
Kann ein Skript Finals vor der Abnahme rendern?
Nein. Ein Final vor dem grünen Licht antwortet mit 409 gate_closed, samt den Gewerken, auf die es wartet.
Sind die Preise ohne Key lesbar?
Ja. GET https://app.filmsquare.ai/v1/pricing ist öffentlich und liefert den Credit-Preis, die Seat-Preise, den Übertrag und die Credit-Pakete.