Filmsquare AiutoDocumentazione

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.

Aggiornato il 5 min di lettura.md

In questa pagina
  1. Autenticazione
  2. Ottenere una chiave
  3. Una chiave personale (qualsiasi ruolo)
  4. Una chiave API dello spazio di lavoro (produttore e superiori)
  5. Ruoli
  6. Una prima sessione
  7. Convenzioni
  8. Errori che incontrerai
  9. Correlati

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 basehttps://app.filmsquare.ai/v1
FormatoJSON su HTTPS
AutenticazioneAuthorization: Bearer <API key or session token>
Riferimentohttps://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) #

  1. Nello studio, apri il menu dello spazio di lavoro in alto nella barra laterale e scegli Settings, poi Claude.
  2. Scegli Use a personal key instead, dalle un nome e scegli Create a personal key.
  3. 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 #

ArgomentoRegola
Nomi dei campiRisposte 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 archiviateEscluse dagli elenchi a meno di includeArchived=true
CancellareLe righe vengono archiviate (POST …/{id}/archive), non cancellate. Versioni, scelte, approvazioni e costi non cambiano mai
IdempotenzaLe richieste di generazione accettano un header Idempotency-Key (o idempotencyKey nel corpo): la stessa chiave restituisce la generazione esistente
DenaroI 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"]}}}
StatoCodiceQuandodetails
400validation_errorIl corpo, la query o un parametro del percorso non corrisponde allo schemaL'elenco dei problemi di validazione
400bad_request, invalid_valueLa rotta rifiuta la richiesta, o il database non riesce a leggere un valore (come un id malformato)—
400url_not_allowedUn URL di webhook o di importazione non è un indirizzo http(s) pubblico—
401unauthenticatedNessun token, o uno revocato o scaduto—
402out_of_creditsNon abbastanza crediti liberi da spendere per questo ciakneeded, available (crediti)
402plan_limitIl piano non lo include: una finale sul Free, una seconda produzione, spazio di archiviazione, licenze, pacchetti senza un pianolimit (final, productions, storage, seats, packs), plan
402budget_exceededVerrebbe superato il budget dell'episodio (budgetCredits sull'episodio)episodeId, budgetCredits, spent, inFlight, needed (crediti)
403insufficient_roleIl tuo ruolo è sotto il minimo della rottarequired, actual
403not_a_signerNon fai parte di chi approva questo reparto—
403role_exceeds_callerUn invito o una chiave con un ruolo superiore al tuo—
403not_a_personGestire chiavi con una chiave personale o una connessione Claude—
404not_foundLa riga non esiste, o non puoi vederla—
409gate_closedUna finale prima che il via libera sia apertoepisode_id, waiting_on (reparti, o placement per un'inquadratura in nessun episodio)
409changed_sinceHai approvato una versione che non è più quella attualeversion (quella attuale)
409already_signed_offLa fase è già approvata—
409element_version_frozenUn riferimento aggiunto a una versione che un ciak ha già usato—
409conflictEsiste già una riga con questi valori—
422foreign_key_violation, check_violation, not_null_violationUna riga referenziata non esiste (o è in un altro spazio di lavoro), o una regola del database ha rifiutato i valoriconstraint, 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}}}

Questa pagina in Markdown: /docs/it/api/overview.md