---
title: "API-Überblick und Schlüssel"
description: "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."
url: https://www.filmsquare.ai/docs/de/api/overview/
lang: de
section: api
updated: 2026-11-10
---

# API-Überblick und Schlüssel

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](https://www.filmsquare.ai/docs/de/api/openapi/) |

## 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).

```bash
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:

```bash
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](https://www.filmsquare.ai/docs/de/working-together/crew-and-roles/).

## Eine erste Session

```bash
# 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](https://www.filmsquare.ai/docs/de/api/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](https://www.filmsquare.ai/docs/de/concepts/credits-and-costs/) |

## Fehler, auf die du triffst

Jeder Fehler hat dieselbe Form:

```json
{"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:

```json
{"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](https://www.filmsquare.ai/docs/de/api/webhooks/)
- [OpenAPI-Referenz](https://www.filmsquare.ai/docs/de/api/openapi/)
- [Was Claude kann](https://www.filmsquare.ai/docs/de/claude/tools/): dieselbe API über MCP
