Filmsquare HilfeDocs

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.

Aktualisiert 5 Min. Lesezeit.md

Auf dieser Seite
  1. Authentifizierung
  2. Einen Schlüssel bekommen
  3. Ein persönlicher Schlüssel (jede Rolle)
  4. Ein Workspace-API-Schlüssel (Producer und höher)
  5. Rollen
  6. Eine erste Session
  7. Konventionen
  8. Fehler, auf die du triffst
  9. Verwandt

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-URLhttps://app.filmsquare.ai/v1
FormatJSON über HTTPS
AuthAuthorization: Bearer <API key or session token>
Referenzhttps://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) #

  1. Öffne im Studio das Workspace-Menü oben in der Seitenleiste und wähle Settings, dann Claude.
  2. Wähle Use a personal key instead, gib ihm einen Namen und wähle Create a personal key.
  3. 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 #

ThemaRegel
FeldnamenAntworten 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 ZeilenAus Listen ausgelassen, außer includeArchived=true
LöschenZeilen werden archiviert (POST …/{id}/archive), nicht gelöscht. Versionen, gewählte Takes, Abnahmen und Kosten werden nie geändert
IdempotenzGenerierungsanfragen nehmen einen Header Idempotency-Key (oder idempotencyKey im Body): Derselbe Schlüssel liefert die bestehende Generierung
GeldKosten 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"]}}}
StatusCodeWanndetails
400validation_errorBody, Query oder Pfadparameter passen nicht zum SchemaDie Liste der Validierungsprobleme
400bad_request, invalid_valueDie Route lehnt die Anfrage ab, oder die Datenbank kann einen Wert nicht lesen (etwa eine fehlerhafte ID)—
400url_not_allowedEine Webhook- oder Import-URL ist keine öffentliche http(s)-Adresse—
401unauthenticatedKein Token, oder ein widerrufenes oder abgelaufenes—
402out_of_creditsNicht genug Credits frei verfügbar für diesen Takeneeded, available (Credits)
402plan_limitDer Tarif enthält das nicht: ein Final im Free-Tarif, eine zweite Produktion, Speicher, Seats, Pakete ohne Tariflimit (final, productions, storage, seats, packs), plan
402budget_exceededDas Budget der Episode (budgetCredits an der Episode) würde überschrittenepisodeId, budgetCredits, spent, inFlight, needed (Credits)
403insufficient_roleDeine Rolle liegt unter der Mindestrolle der Routerequired, actual
403not_a_signerDu gehörst nicht zu den Abnehmenden dieses Gewerks—
403role_exceeds_callerEine Einladung oder ein Schlüssel mit einer Rolle über deiner eigenen—
403not_a_personSchlüssel mit einem persönlichen Schlüssel oder einer Claude-Verbindung verwalten—
404not_foundDie Zeile existiert nicht, oder du darfst sie nicht sehen—
409gate_closedEin Final, bevor das grüne Licht da istepisode_id, waiting_on (Gewerke, oder placement für eine Einstellung in keiner Folge)
409changed_sinceDu hast eine Version abgenommen, die nicht mehr die aktuelle istversion (die aktuelle)
409already_signed_offDer Schritt ist schon abgenommen—
409element_version_frozenEine Referenz wurde einer Version hinzugefügt, die ein Take schon genutzt hat—
409conflictEine Zeile mit diesen Werten gibt es schon—
422foreign_key_violation, check_violation, not_null_violationEine referenzierte Zeile existiert nicht (oder liegt in einem anderen Workspace), oder eine Datenbankregel hat die Werte abgelehntconstraint, 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}}}

Diese Seite als Markdown: /docs/de/api/overview.md