---
title: "Resumen de la API y claves"
description: "La API REST de Filmsquare: URL base, autenticación con claves de API o con una sesión, cómo crear una clave, convenciones y los errores que te encontrarás."
url: https://www.filmsquare.ai/docs/es/api/overview/
lang: es
section: api
updated: 2026-11-10
---

# Resumen de la API y claves

Todo lo que hace el estudio pasa por una sola API REST, y tú también puedes usarla: la app, tu propio Claude y tus
scripts llaman a las mismas rutas, con los mismos roles y las mismas reglas.

| | |
| --- | --- |
| URL base | `https://app.filmsquare.ai/v1` |
| Formato | JSON sobre HTTPS |
| Autenticación | `Authorization: Bearer <API key or session token>` |
| Referencia | `https://app.filmsquare.ai/v1/openapi.json` (OpenAPI 3.1, pública). Consulta la [referencia OpenAPI](https://www.filmsquare.ai/docs/es/api/openapi/) |

## Autenticación

Todas las rutas, salvo unas pocas públicas (`GET /v1/pricing`, `POST /v1/signup`, los receptores de webhooks),
necesitan un token bearer:

- **Una clave de API**, que empieza por `fsk_`. Una clave pertenece a una persona (o a un usuario agente) en **un**
  espacio de trabajo, y actúa con el rol de la clave, nunca más que el rol actual de esa persona.
- **Un token de sesión** de una persona con la sesión iniciada (lo que envía la 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` devuelve quién eres, si entraste con una clave, y tus espacios de trabajo. Cada ruta de espacio de trabajo lleva el id del
espacio de trabajo en su ruta: `/v1/workspaces/{ws}/…`.

## Conseguir una clave

### Una clave personal (cualquier rol)

1. En el estudio, abre el menú del espacio de trabajo, arriba en la barra lateral, y elige **Settings**, después **Claude**.
2. Elige **Use a personal key instead**, ponle un nombre y elige **Create a personal key**.
3. Copia la clave. Se muestra una sola vez.

Una clave personal tiene tu propio rol en ese espacio de trabajo. Está pensada para Claude Code, pero sirve para cualquier
llamada de la API que tu rol permita, salvo gestionar claves.

### Una clave de API del espacio de trabajo (productor y superior)

Un productor o un propietario, con la sesión iniciada, puede crear claves con un rol elegido mediante la 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 respuesta contiene la `key` completa una sola vez; Filmsquare guarda solo su hash. El rol de una clave nunca puede
estar por encima del tuyo. Con `userId` puedes crear una clave para un usuario agente que sea miembro del espacio de trabajo.

`GET /workspaces/{ws}/api-keys` lista las claves (solo el prefijo); `POST /workspaces/{ws}/api-keys/{id}/revoke`
revoca una. Las claves no pueden crear claves: estas rutas necesitan una persona con la sesión iniciada o una clave
del espacio de trabajo, y rechazan una clave personal o una conexión de Claude con `403 not_a_person`.

## Roles

Cada ruta tiene un rol mínimo: `owner` > `producer` > `director` > `maker` > `reviewer` > `viewer`. Una llamada por
debajo recibe `403 insufficient_role` con `{"required": "director", "actual": "maker"}`. Una fila que no puedes ver
responde `404`, igual que una fila que no existe. Consulta [Equipo, roles y acceso](https://www.filmsquare.ai/docs/es/working-together/crew-and-roles/).

## Una primera sesión

```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` es `keyframe`, `video`, `dialogue`, `sfx` o `music`; `tier` es `draft` o `final`. Ningún modelo conectado
hace todavía `sfx` ni `music`: esas tomas llegan como subidas (`createUploadTicket`, y después `completeUpload` con
una capa de destino). Si no indicas `modelKey`, Filmsquare enruta al modelo capaz con el menor costo por toma
aceptada. En vez de consultar una y otra vez, suscríbete a los [webhooks](https://www.filmsquare.ai/docs/es/api/webhooks/).

## Convenciones

| Tema | Regla |
| --- | --- |
| Nombres de campo | Respuestas en `snake_case`, cuerpos de petición en `camelCase` |
| Listas | `{"items": […], "next_cursor": "…"}`. Pasa `cursor` para la página siguiente; `limit` hasta 200; `order` `asc` o `desc` |
| Filas archivadas | Quedan fuera de las listas salvo `includeArchived=true` |
| Borrado | Las filas se archivan (`POST …/{id}/archive`), no se borran. Las versiones, tomas elegidas, vistos buenos y costos nunca se cambian |
| Idempotencia | Las peticiones de generación admiten una cabecera `Idempotency-Key` (o `idempotencyKey` en el cuerpo): la misma clave devuelve la generación existente |
| Dinero | Los costos están en créditos, cada uno a la tarifa con la que empezó el trabajo; lo que cuesta un crédito en euros está en `GET /v1/pricing` y [Créditos y lo que cuestan las cosas](https://www.filmsquare.ai/docs/es/concepts/credits-and-costs/) |

## Errores que te encontrarás

Todos los errores tienen la misma forma:

```json
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
  "details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
```

| Estado | Código | Cuándo | `details` |
| --- | --- | --- | --- |
| 400 | `validation_error` | El cuerpo, la query o un parámetro de ruta no coincide con el esquema | La lista de problemas de validación |
| 400 | `bad_request`, `invalid_value` | La ruta rechaza la petición, o la base de datos no puede leer un valor (como un id mal formado) | — |
| 400 | `url_not_allowed` | La URL de un webhook o de una importación no es una dirección http(s) pública | — |
| 401 | `unauthenticated` | Sin token, o con uno revocado o vencido | — |
| 402 | `out_of_credits` | No hay créditos suficientes disponibles para gastar en esta toma | `needed`, `available` (créditos) |
| 402 | `plan_limit` | El plan no incluye esto: un final en Free, una segunda producción, almacenamiento, licencias, paquetes sin un plan | `limit` (`final`, `productions`, `storage`, `seats`, `packs`), `plan` |
| 402 | `budget_exceeded` | Se superaría el presupuesto del episodio (`budgetCredits` en el episodio) | `episodeId`, `budgetCredits`, `spent`, `inFlight`, `needed` (créditos) |
| 403 | `insufficient_role` | Tu rol está por debajo del mínimo de la ruta | `required`, `actual` |
| 403 | `not_a_signer` | No eres responsable del visto bueno de este departamento | — |
| 403 | `role_exceeds_caller` | Una invitación o una clave con un rol por encima del tuyo | — |
| 403 | `not_a_person` | Gestionar claves con una clave personal o una conexión de Claude | — |
| 404 | `not_found` | La fila no existe, o no puedes verla | — |
| 409 | `gate_closed` | Un final antes de que haya luz verde | `episode_id`, `waiting_on` (departamentos, o `placement` para un plano que no está en ningún episodio) |
| 409 | `changed_since` | Diste el visto bueno a una versión que ya no es la actual | `version` (la actual) |
| 409 | `already_signed_off` | El paso ya tiene visto bueno | — |
| 409 | `element_version_frozen` | Una referencia añadida a una versión que una toma ya usó | — |
| 409 | `conflict` | Ya existe una fila con estos valores | — |
| 422 | `foreign_key_violation`, `check_violation`, `not_null_violation` | Una fila referenciada no existe (o está en otro espacio de trabajo), o una regla de la base de datos rechazó los valores | `constraint`, `table`, `detail` |

`402 out_of_credits` tiene este aspecto:

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

## Relacionado

- [Webhooks](https://www.filmsquare.ai/docs/es/api/webhooks/)
- [Referencia OpenAPI](https://www.filmsquare.ai/docs/es/api/openapi/)
- [Qué puede hacer Claude](https://www.filmsquare.ai/docs/es/claude/tools/): la misma API por MCP
