Filmsquare

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"
Anfrage sendenGET /v1/me

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

BASIS-URL
https://app.filmsquare.ai/v1
ERSTE AUFRUFE
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 haben keine Scopes. Die Macht eines Keys ist seine Rolle in einem Workspace, nie über der Rolle der Person dahinter.

KEYWIE
Persönlicher KeySettings → Claude → Use a personal key instead. Deine eigene Rolle, wird einmal angezeigt.
Workspace-KeyPOST /workspaces/{ws}/api-keys mit Namen und Rolle, von einem Producer oder Owner. Wird einmal angezeigt; nur sein Hash wird gespeichert.
WiderrufenPOST /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

EINE OPERATION
"/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

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

EREIGNISGESENDET, WENN
generation.succeededEin Take ist fertig gerendert
generation.failedEin Render ist fehlgeschlagen
take.selectedEin Take wurde auf einer Einstellung oder Szene gewählt
asset_version.createdEin Render hat eine neue Asset-Version erzeugt
["*"]Alle Ereignisse
ABONNIEREN
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"]}'
EINE ZUSTELLUNG
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

THEMAREGEL
FeldnamenAntworten in snake_case, Request-Bodies in camelCase.
ListenListen antworten mit {"items": […], "next_cursor": "…"}. Gib cursor für die nächste Seite mit, limit bis 200, order asc oder desc.
IdempotenzTake-Anfragen akzeptieren einen Idempotency-Key-Header: Derselbe Key liefert denselben Take.
LöschenZeilen werden archiviert, nie gelöscht. Versionen, gewählte Takes, Abnahmen und Kosten ändern sich nie.
Nicht sichtbarEine Zeile, die du nicht sehen darfst, antwortet mit 404, genau wie eine Zeile, die es nicht gibt.
STATUSCODEWANN
400validation_errorBody, Query oder ein Pfadparameter passt nicht zum Schema
401unauthenticatedKein Token, oder ein widerrufenes oder abgelaufenes
402out_of_creditsNicht genug freie Credits für diesen Take
402plan_limitDer Tarif enthält es nicht, etwa ein Final im Free-Tarif
402budget_exceededDas Budget der Folge in Credits würde überschritten
403insufficient_roleDeine Rolle liegt unter dem x-min-role der Route
403account_blockedDas Konto ist gesperrt; jede Anfrage wird abgelehnt
404not_foundDie Zeile gibt es nicht, oder du darfst sie nicht sehen
409gate_closedEin Final, bevor die Gewerke, auf die es wartet, abgenommen haben
409workspace_pausedDer Workspace ist pausiert: Es startet darin kein neuer Take und kein Tool
JEDER FEHLER HAT DIESELBE FORM
{"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.

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

Fragen

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.