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"
WEBHOOK · POST /filmsquare/hook

S3-B5-05Seedance 2.5 · Finale 1080p · 5 s · 105,30 crediti · 5,27 €
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}/….
https://app.filmsquare.ai/v1export 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"}'ownerproducerdirectormakerreviewerviewer
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.
| CHIAVE | COME |
|---|---|
| Chiave personale | Settings → Claude → Use a personal key instead. Con il tuo ruolo; si mostra una sola volta. |
| Chiave dello spazio di lavoro | POST /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. |
| Revoca | POST /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
"/workspaces/{ws}/shots/{id}/generations": {
"post": {
"operationId": "generateForShot",
"x-min-role": "maker",
…
}
}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
| EVENTO | INVIATO QUANDO |
|---|---|
generation.succeeded | Un ciak ha finito il rendering |
generation.failed | Un rendering non è riuscito |
take.selected | Un ciak è stato scelto su un'inquadratura o una scena |
asset_version.created | Un rendering ha prodotto una nuova versione dell'asset |
["*"] | Tutti gli eventi |
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"]}'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
| ARGOMENTO | REGOLA |
|---|---|
| Nomi dei campi | Risposte in snake_case, corpi delle richieste in camelCase. |
| Elenchi | Gli elenchi rispondono {"items": […], "next_cursor": "…"}. Passa cursor per la pagina successiva, limit fino a 200, order asc o desc. |
| Idempotenza | Le richieste di ciak accettano un header Idempotency-Key: la stessa chiave restituisce lo stesso ciak. |
| Eliminazione | Le righe si archiviano, non si eliminano mai. Versioni, ciak scelti, approvazioni e costi non cambiano mai. |
| Non visibile | Una riga che non puoi vedere risponde 404, come una riga che non esiste. |
| STATO | CODICE | QUANDO |
|---|---|---|
| 400 | validation_error | Il corpo, la query o un parametro del percorso non corrisponde allo schema |
| 401 | unauthenticated | Nessun token, oppure uno revocato o scaduto |
| 402 | out_of_credits | Crediti liberi insufficienti per questo ciak |
| 402 | plan_limit | Il piano non lo include, come una finale su Free |
| 402 | budget_exceeded | Il budget dell'episodio in crediti verrebbe superato |
| 403 | insufficient_role | Il tuo ruolo è inferiore all'x-min-role della rotta |
| 403 | account_blocked | L'account è stato sospeso; ogni richiesta viene rifiutata |
| 404 | not_found | La riga non esiste, oppure non puoi vederla |
| 409 | gate_closed | Una finale prima che i reparti da cui dipende abbiano approvato |
| 409 | workspace_paused | Lo spazio di lavoro è in pausa: al suo interno non parte nessun nuovo ciak o strumento |
{"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.
curl -s https://app.filmsquare.ai/v1/pricingDomande
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.