---
title: "Panoramica dell'API e chiavi"
description: "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."
url: https://www.filmsquare.ai/docs/it/api/overview/
lang: it
section: api
updated: 2026-11-10
---

# Panoramica dell'API e chiavi

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

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

```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"}'
```

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

## Una prima sessione

```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` è `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](https://www.filmsquare.ai/docs/it/api/webhooks/).

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

## Errori che incontrerai

Ogni errore ha la stessa forma:

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

```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}}}
```

## Correlati

- [Webhook](https://www.filmsquare.ai/docs/it/api/webhooks/)
- [Riferimento OpenAPI](https://www.filmsquare.ai/docs/it/api/openapi/)
- [Cosa può fare Claude](https://www.filmsquare.ai/docs/it/claude/tools/): la stessa API tramite MCP
