Filmsquare

API

Lo studio, come API.

L'API REST di Filmsquare è la stessa API che usano lo studio e il Claude di ciascuno, aperta ai tuoi script. JSON su HTTPS, un unico documento OpenAPI 3.1 generato dalle rotte, una chiave bearer per persona e spazio di lavoro, e webhook firmati per quando un ciak è pronto.

curl -s "$FS/me" \
  -H "Authorization: Bearer $FS_KEY"
Invia una richiestaGET /v1/me

BASE URL E AUTENTICAZIONE

Una chiave, un ruolo, uno spazio di lavoro

Ogni chiamata invia Authorization: Bearer <token>: una chiave API che inizia con fsk_, oppure una sessione autenticata. Le rotte dello spazio di lavoro portano lo spazio di lavoro nel percorso, /v1/workspaces/{ws}/….

BASE URL
https://app.filmsquare.ai/v1
PRIME CHIAMATE
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

Le chiavi non hanno ambiti. Il potere di una chiave è il suo ruolo in uno spazio di lavoro, mai sopra il ruolo della persona che c'è dietro.

CHIAVECOME
Chiave personaleSettings → Claude → Use a personal key instead. Con il tuo ruolo; si mostra una sola volta.
Chiave dello spazio di lavoroPOST /workspaces/{ws}/api-keys con un nome e un ruolo, da un produttore o dal proprietario. Si mostra una sola volta; si conserva solo il suo hash.
RevocaPOST /workspaces/{ws}/api-keys/{id}/revoke. La chiamata successiva con quella chiave risponde 401 api_key_revoked.

OPENAPI 3.1

Un solo nome per una chiamata e per un lavoro

GET https://app.filmsquare.ai/v1/openapi.json è pubblico, OpenAPI 3.1, e generato dalle rotte stesse. Ogni rotta ha un operationId, lo stesso nome con cui Claude la esegue con run_action, quindi una chiamata che scrivi in uno script e un lavoro che affidi a Claude sono la stessa cosa. x-min-role indica il ruolo più basso che può chiamarla. Riferimento OpenAPI · MCP per Claude

UN'OPERAZIONE
"/workspaces/{ws}/shots/{id}/generations": {
  "post": {
    "operationId": "generateForShot",
    "x-min-role": "maker",
    …
  }
}
TERMINALE
curl -s https://app.filmsquare.ai/v1/openapi.json | jq '.paths | keys | length'

WEBHOOK

Iscriviti invece di fare polling

Da produttore in su; il segreto whsec_ si mostra una sola volta. Rispondi con un 2xx. Su 5xx, 429 o timeout Filmsquare riprova con backoff esponenziale, da circa 2 secondi fino a 10 minuti tra un tentativo e l'altro, fino a 8 tentativi. x-fs-delivery resta lo stesso a ogni nuovo tentativo. Webhook

EVENTOINVIATO QUANDO
generation.succeededUn ciak ha finito il rendering
generation.failedUn rendering non è riuscito
take.selectedUn ciak è stato scelto su un'inquadratura o una scena
asset_version.createdUn rendering ha prodotto una nuova versione dell'asset
["*"]Tutti gli eventi
ISCRIZIONE
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"]}'
UNA CONSEGNA
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…

CONVENZIONI ED ERRORI

Ogni errore ha una sola forma

ARGOMENTOREGOLA
Nomi dei campiRisposte in snake_case, corpi delle richieste in camelCase.
ElenchiGli elenchi rispondono {"items": […], "next_cursor": "…"}. Passa cursor per la pagina successiva, limit fino a 200, order asc o desc.
IdempotenzaLe richieste di ciak accettano un header Idempotency-Key: la stessa chiave restituisce lo stesso ciak.
EliminazioneLe righe si archiviano, non si eliminano mai. Versioni, ciak scelti, approvazioni e costi non cambiano mai.
Non visibileUna riga che non puoi vedere risponde 404, come una riga che non esiste.
STATOCODICEQUANDO
400validation_errorIl corpo, la query o un parametro del percorso non corrisponde allo schema
401unauthenticatedNessun token, oppure uno revocato o scaduto
402out_of_creditsCrediti liberi insufficienti per questo ciak
402plan_limitIl piano non lo include, come una finale su Free
402budget_exceededIl budget dell'episodio in crediti verrebbe superato
403insufficient_roleIl tuo ruolo è inferiore all'x-min-role della rotta
403account_blockedL'account è stato sospeso; ogni richiesta viene rifiutata
404not_foundLa riga non esiste, oppure non puoi vederla
409gate_closedUna finale prima che i reparti da cui dipende abbiano approvato
409workspace_pausedLo spazio di lavoro è in pausa: al suo interno non parte nessun nuovo ciak o strumento
OGNI ERRORE HA UNA SOLA FORMA
{"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 non richiede nessuna chiave. Restituisce il prezzo di un credito in euro, i prezzi delle licenze e i crediti che porta una licenza, il riporto, lo spazio di archiviazione e i pacchetti di crediti: i numeri dietro i prezzi.

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

Domande

L'API è la stessa che usa lo studio?

Sì. Lo studio, il Claude di ciascuno e i tuoi script chiamano le stesse rotte, con gli stessi ruoli e le stesse regole.

Le chiavi API hanno ambiti?

No. Una chiave funziona in uno spazio di lavoro con un ruolo, mai sopra il ruolo di chi l'ha creata. Il ruolo è l'ambito.

Dov'è il riferimento?

Il documento OpenAPI 3.1 all'indirizzo https://app.filmsquare.ai/v1/openapi.json è pubblico e generato dalle rotte, quindi non resta mai indietro rispetto a loro.

Come faccio a sapere quando un ciak è pronto?

Iscrivi un webhook a generation.succeeded. Le consegne sono firmate con x-fs-signature e ripetute su 5xx, 429 e timeout.

Uno script può renderizzare le finali prima dell'approvazione?

No. Una finale prima che il via libera sia aperto risponde 409 gate_closed, con i reparti da cui dipende.

I prezzi si leggono senza una chiave?

Sì. GET https://app.filmsquare.ai/v1/pricing è pubblico e restituisce il prezzo del credito, i prezzi delle licenze, il riporto e i pacchetti di crediti.