6.0 API6.1 API-Überblick und Schlüssel
API-Überblick und Schlüssel
Die Filmsquare-REST-API: Basis-URL, Authentifizierung mit API-Schlüsseln oder einer Session, wie du einen Schlüssel anlegst, Konventionen, und die Fehler, auf die du triffst.
Alles, was das Studio tut, läuft über eine REST-API, und du kannst sie auch nutzen: Die App, dein eigener Claude und deine Skripte rufen dieselben Routen auf, mit denselben Rollen und denselben Regeln.
| Basis-URL | https://app.filmsquare.ai/v1 |
| Format | JSON über HTTPS |
| Auth | Authorization: Bearer <API key or session token> |
| Referenz | https://app.filmsquare.ai/v1/openapi.json (OpenAPI 3.1, öffentlich). Siehe OpenAPI-Referenz |
Authentifizierung #
Jede Route außer ein paar öffentlichen (GET /v1/pricing, POST /v1/signup, die Webhook-Empfänger) braucht ein
Bearer-Token:
- Ein API-Schlüssel, der mit
fsk_beginnt. Ein Schlüssel gehört einer Person (oder einem Agent-User) in einem Workspace und handelt mit der Rolle des Schlüssels, nie mit mehr als der aktuellen Rolle dieser Person. - Ein Session-Token einer angemeldeten Person (das, was die Web-App sendet).
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_… # your key
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
GET /me liefert, wer du bist, ob du mit einem Schlüssel gekommen bist, und deine Workspaces. Jede Workspace-Route
hat die Workspace-ID in ihrem Pfad: /v1/workspaces/{ws}/….
Einen Schlüssel bekommen #
Ein persönlicher Schlüssel (jede Rolle) #
- Öffne im Studio das Workspace-Menü oben in der Seitenleiste und wähle Settings, dann Claude.
- Wähle Use a personal key instead, gib ihm einen Namen und wähle Create a personal key.
- Kopiere den Schlüssel. Er wird nur einmal angezeigt.
Ein persönlicher Schlüssel hat deine eigene Rolle in diesem Workspace. Er ist für Claude Code gemacht, funktioniert aber für jeden API-Aufruf, den deine Rolle erlaubt, außer Schlüssel zu verwalten.
Ein Workspace-API-Schlüssel (Producer und höher) #
Ein Producer oder Owner kann, angemeldet, über die API Schlüssel mit einer gewählten Rolle anlegen:
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"}'
Die Antwort enthält den vollständigen key einmal; Filmsquare behält nur seinen Hash. Die Rolle eines Schlüssels
kann nie über deiner eigenen liegen. Mit userId kannst du einen Schlüssel für einen Agent-User anlegen, der
Mitglied des Workspace ist.
GET /workspaces/{ws}/api-keys listet Schlüssel (nur das Präfix); POST /workspaces/{ws}/api-keys/{id}/revoke
widerruft einen. Schlüssel können keine Schlüssel anlegen: Diese Routen brauchen eine angemeldete Person oder einen
Workspace-Schlüssel und lehnen einen persönlichen Schlüssel oder eine Claude-Verbindung mit 403 not_a_person ab.
Rollen #
Jede Route hat eine Mindestrolle: owner > producer > director > maker > reviewer > viewer. Ein Aufruf
darunter bekommt 403 insufficient_role mit {"required": "director", "actual": "maker"}. Eine Zeile, die du nicht
sehen darfst, antwortet mit 404, genau wie eine Zeile, die nicht existiert. Siehe Crew, Rollen und Zugriff.
Eine erste Session #
# 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 ist keyframe, video, dialogue, sfx oder music; tier ist draft oder final. Noch kein
angebundenes Modell macht sfx oder music: Diese Takes kommen als Uploads (createUploadTicket, dann
completeUpload mit einem Ziel-Layer). Lass modelKey weg, und
Filmsquare routet zum geeigneten Modell mit den niedrigsten Kosten pro akzeptiertem Take. Statt zu pollen,
abonniere Webhooks.
Konventionen #
| Thema | Regel |
|---|---|
| Feldnamen | Antworten in snake_case, Request-Bodys in camelCase |
| Listen | {"items": […], "next_cursor": "…"}. Gib cursor für die nächste Seite mit; limit bis 200; order asc oder desc |
| Archivierte Zeilen | Aus Listen ausgelassen, außer includeArchived=true |
| Löschen | Zeilen werden archiviert (POST …/{id}/archive), nicht gelöscht. Versionen, gewählte Takes, Abnahmen und Kosten werden nie geändert |
| Idempotenz | Generierungsanfragen nehmen einen Header Idempotency-Key (oder idempotencyKey im Body): Derselbe Schlüssel liefert die bestehende Generierung |
| Geld | Kosten sind in Credits, jeweils zu dem Satz, zu dem die Arbeit begann; was ein Credit in Euro kostet, steht in GET /v1/pricing und Credits und was Dinge kosten |
Fehler, auf die du triffst #
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"]}}}
| Status | Code | Wann | details |
|---|---|---|---|
| 400 | validation_error | Body, Query oder Pfadparameter passen nicht zum Schema | Die Liste der Validierungsprobleme |
| 400 | bad_request, invalid_value | Die Route lehnt die Anfrage ab, oder die Datenbank kann einen Wert nicht lesen (etwa eine fehlerhafte ID) | — |
| 400 | url_not_allowed | Eine Webhook- oder Import-URL ist keine öffentliche http(s)-Adresse | — |
| 401 | unauthenticated | Kein Token, oder ein widerrufenes oder abgelaufenes | — |
| 402 | out_of_credits | Nicht genug Credits frei verfügbar für diesen Take | needed, available (Credits) |
| 402 | plan_limit | Der Tarif enthält das nicht: ein Final im Free-Tarif, eine zweite Produktion, Speicher, Seats, Pakete ohne Tarif | limit (final, productions, storage, seats, packs), plan |
| 402 | budget_exceeded | Das Budget der Episode (budgetCredits an der Episode) würde überschritten | episodeId, budgetCredits, spent, inFlight, needed (Credits) |
| 403 | insufficient_role | Deine Rolle liegt unter der Mindestrolle der Route | required, actual |
| 403 | not_a_signer | Du gehörst nicht zu den Abnehmenden dieses Gewerks | — |
| 403 | role_exceeds_caller | Eine Einladung oder ein Schlüssel mit einer Rolle über deiner eigenen | — |
| 403 | not_a_person | Schlüssel mit einem persönlichen Schlüssel oder einer Claude-Verbindung verwalten | — |
| 404 | not_found | Die Zeile existiert nicht, oder du darfst sie nicht sehen | — |
| 409 | gate_closed | Ein Final, bevor das grüne Licht da ist | episode_id, waiting_on (Gewerke, oder placement für eine Einstellung in keiner Folge) |
| 409 | changed_since | Du hast eine Version abgenommen, die nicht mehr die aktuelle ist | version (die aktuelle) |
| 409 | already_signed_off | Der Schritt ist schon abgenommen | — |
| 409 | element_version_frozen | Eine Referenz wurde einer Version hinzugefügt, die ein Take schon genutzt hat | — |
| 409 | conflict | Eine Zeile mit diesen Werten gibt es schon | — |
| 422 | foreign_key_violation, check_violation, not_null_violation | Eine referenzierte Zeile existiert nicht (oder liegt in einem anderen Workspace), oder eine Datenbankregel hat die Werte abgelehnt | constraint, table, detail |
402 out_of_credits sieht so aus:
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
"details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
Verwandt #
- Webhooks
- OpenAPI-Referenz
- Was Claude kann: dieselbe API über MCP