6.0 API6.1 Panoramica dell'API e chiavi
Panoramica dell'API e chiavi
La REST API di Filmsquare: URL di base, autenticazione con chiavi API o una sessione, come creare una chiave, convenzioni e gli errori che incontrerai.
Tutto ciò che fa lo studio passa per un'unica REST API, e puoi usarla anche tu: l'app, il tuo Claude e i tuoi script chiamano tutti le stesse rotte, con gli stessi ruoli e le stesse regole.
| URL di base | https://app.filmsquare.ai/v1 |
| Formato | JSON su HTTPS |
| Autenticazione | Authorization: Bearer <API key or session token> |
| Riferimento | https://app.filmsquare.ai/v1/openapi.json (OpenAPI 3.1, pubblico). Vedi Riferimento OpenAPI |
Autenticazione #
Ogni rotta tranne poche pubbliche (GET /v1/pricing, POST /v1/signup, i ricevitori dei webhook) richiede un token
bearer:
- Una chiave API, che inizia con
fsk_. Una chiave appartiene a una persona (o a un utente agente) in uno spazio di lavoro, e agisce con il ruolo della chiave, mai più del ruolo attuale di quella persona. - Un token di sessione di una persona con l'accesso effettuato (quello che manda l'app web).
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_… # your key
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
GET /me restituisce chi sei, se sei entrato con una chiave, e i tuoi spazi di lavoro. Ogni rotta dello spazio di
lavoro ha l'id dello spazio di lavoro nel percorso: /v1/workspaces/{ws}/….
Ottenere una chiave #
Una chiave personale (qualsiasi ruolo) #
- Nello studio, apri il menu dello spazio di lavoro in alto nella barra laterale e scegli Settings, poi Claude.
- Scegli Use a personal key instead, dalle un nome e scegli Create a personal key.
- Copia la chiave. Viene mostrata una sola volta.
Una chiave personale ha il tuo ruolo in quello spazio di lavoro. È fatta per Claude Code, ma funziona per qualsiasi chiamata API che il tuo ruolo permetta, tranne gestire le chiavi.
Una chiave API dello spazio di lavoro (produttore e superiori) #
Un produttore o proprietario, con l'accesso effettuato, può creare chiavi con un ruolo a scelta tramite l'API:
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"}'
La risposta contiene la key completa una volta sola; Filmsquare ne conserva solo l'hash. Il ruolo di una chiave non
può mai essere superiore al tuo. Con userId puoi creare una chiave per un utente agente che è membro dello spazio
di lavoro.
GET /workspaces/{ws}/api-keys elenca le chiavi (solo il prefisso); POST /workspaces/{ws}/api-keys/{id}/revoke ne
revoca una. Le chiavi non possono creare chiavi: queste rotte richiedono una persona con l'accesso effettuato o una
chiave dello spazio di lavoro, e rifiutano una chiave personale o una connessione Claude con 403 not_a_person.
Ruoli #
Ogni rotta ha un ruolo minimo: owner > producer > director > maker > reviewer > viewer. Una chiamata
sotto quel ruolo riceve 403 insufficient_role con {"required": "director", "actual": "maker"}. Una riga che non puoi
vedere risponde 404, come una riga che non esiste. Vedi Troupe, ruoli e accessi.
Una prima sessione #
# 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 è keyframe, video, dialogue, sfx o music; tier è draft o final. Nessun modello collegato fa
ancora sfx o music: quei ciak entrano come caricamenti (createUploadTicket, poi completeUpload con un
livello di destinazione). Se lasci fuori modelKey, Filmsquare manda al modello capace con il costo più basso per
ciak approvato. Invece di interrogare di continuo, iscriviti ai webhook.
Convenzioni #
| Argomento | Regola |
|---|---|
| Nomi dei campi | Risposte in snake_case, corpi delle richieste in camelCase |
| Elenchi | {"items": […], "next_cursor": "…"}. Passa cursor per la pagina successiva; limit fino a 200; order asc o desc |
| Righe archiviate | Escluse dagli elenchi a meno di includeArchived=true |
| Cancellare | Le righe vengono archiviate (POST …/{id}/archive), non cancellate. Versioni, scelte, approvazioni e costi non cambiano mai |
| Idempotenza | Le richieste di generazione accettano un header Idempotency-Key (o idempotencyKey nel corpo): la stessa chiave restituisce la generazione esistente |
| Denaro | I costi sono in crediti, ciascuno alla tariffa a cui il lavoro è partito; quanto costa un credito in euro sta in GET /v1/pricing e in Crediti e quanto costano le cose |
Errori che incontrerai #
Ogni errore ha la stessa forma:
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
| Stato | Codice | Quando | details |
|---|---|---|---|
| 400 | validation_error | Il corpo, la query o un parametro del percorso non corrisponde allo schema | L'elenco dei problemi di validazione |
| 400 | bad_request, invalid_value | La rotta rifiuta la richiesta, o il database non riesce a leggere un valore (come un id malformato) | — |
| 400 | url_not_allowed | Un URL di webhook o di importazione non è un indirizzo http(s) pubblico | — |
| 401 | unauthenticated | Nessun token, o uno revocato o scaduto | — |
| 402 | out_of_credits | Non abbastanza crediti liberi da spendere per questo ciak | needed, available (crediti) |
| 402 | plan_limit | Il piano non lo include: una finale sul Free, una seconda produzione, spazio di archiviazione, licenze, pacchetti senza un piano | limit (final, productions, storage, seats, packs), plan |
| 402 | budget_exceeded | Verrebbe superato il budget dell'episodio (budgetCredits sull'episodio) | episodeId, budgetCredits, spent, inFlight, needed (crediti) |
| 403 | insufficient_role | Il tuo ruolo è sotto il minimo della rotta | required, actual |
| 403 | not_a_signer | Non fai parte di chi approva questo reparto | — |
| 403 | role_exceeds_caller | Un invito o una chiave con un ruolo superiore al tuo | — |
| 403 | not_a_person | Gestire chiavi con una chiave personale o una connessione Claude | — |
| 404 | not_found | La riga non esiste, o non puoi vederla | — |
| 409 | gate_closed | Una finale prima che il via libera sia aperto | episode_id, waiting_on (reparti, o placement per un'inquadratura in nessun episodio) |
| 409 | changed_since | Hai approvato una versione che non è più quella attuale | version (quella attuale) |
| 409 | already_signed_off | La fase è già approvata | — |
| 409 | element_version_frozen | Un riferimento aggiunto a una versione che un ciak ha già usato | — |
| 409 | conflict | Esiste già una riga con questi valori | — |
| 422 | foreign_key_violation, check_violation, not_null_violation | Una riga referenziata non esiste (o è in un altro spazio di lavoro), o una regola del database ha rifiutato i valori | constraint, table, detail |
402 out_of_credits si presenta così:
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
"details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
Correlati #
- Webhook
- Riferimento OpenAPI
- Cosa può fare Claude: la stessa API tramite MCP