6.0 API6.1 Resumen de la API y claves
Resumen de la API y claves
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.
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 |
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).
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) #
- En el estudio, abre el menú del espacio de trabajo, arriba en la barra lateral, y elige Settings, después Claude.
- Elige Use a personal key instead, ponle un nombre y elige Create a personal key.
- 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:
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.
Una primera sesión #
# 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.
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 |
Errores que te encontrarás #
Todos los errores tienen la misma forma:
{"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:
{"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
- Referencia OpenAPI
- Qué puede hacer Claude: la misma API por MCP