API
El studio, como una API.
La API REST de Filmsquare es la misma API que usan el studio y el propio Claude de cada persona, abierta a tus scripts. JSON sobre HTTPS, un único documento OpenAPI 3.1 generado a partir de las rutas, una clave de portador por persona y espacio de trabajo, y webhooks firmados para cuando una toma está lista.
curl -s "$FS/me" \
-H "Authorization: Bearer $FS_KEY"
WEBHOOK · POST /filmsquare/hook

S3-B5-05Seedance 2.5 · Final 1080p · 5 s · 105.30 créditos · €5.27
URL BASE Y AUTENTICACIÓN
Una clave, un rol, un espacio de trabajo
Cada llamada envía Authorization: Bearer <token>: una clave de API que empieza con fsk_, o una sesión iniciada. Las rutas del espacio de trabajo llevan el espacio de trabajo en la ruta, /v1/workspaces/{ws}/….
https://app.filmsquare.ai/v1export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_…
# Who you are, and your workspaces
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
# A draft take of a shot (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"}'ownerproducerdirectormakerreviewerviewer
Las claves no tienen alcances. El poder de una clave es su rol en un espacio de trabajo, nunca por encima del rol de la persona que está detrás.
| CLAVE | CÓMO |
|---|---|
| Clave personal | Settings → Claude → Use a personal key instead. Tu propio rol, se muestra una sola vez. |
| Clave del espacio de trabajo | POST /workspaces/{ws}/api-keys con un nombre y un rol, por un productor o un propietario. Se muestra una sola vez; solo se guarda su hash. |
| Revocar | POST /workspaces/{ws}/api-keys/{id}/revoke. La siguiente llamada con ella responde 401 api_key_revoked. |
OPENAPI 3.1
Un solo nombre para una llamada y una tarea
GET https://app.filmsquare.ai/v1/openapi.json es pública, OpenAPI 3.1, y se genera a partir de las propias rutas. Cada ruta tiene un operationId, el mismo nombre con el que Claude la ejecuta con run_action, así que una llamada que programas y una tarea que le encargas a Claude son lo mismo. x-min-role indica el rol más bajo que puede llamarla. Referencia de OpenAPI · MCP para Claude
"/workspaces/{ws}/shots/{id}/generations": {
"post": {
"operationId": "generateForShot",
"x-min-role": "maker",
…
}
}curl -s https://app.filmsquare.ai/v1/openapi.json | jq '.paths | keys | length'WEBHOOKS
Suscríbete en vez de consultar sin parar
Productor o superior; el secreto de whsec_ se muestra una sola vez. Responde con un 2xx. Ante un 5xx, un 429 o un tiempo de espera agotado, Filmsquare reintenta con espera exponencial, de unos 2 segundos hasta 10 minutos entre intentos, hasta 8 intentos. x-fs-delivery se mantiene igual entre reintentos. Webhooks
| EVENTO | SE ENVÍA CUANDO |
|---|---|
generation.succeeded | Una toma terminó de renderizarse |
generation.failed | Un renderizado falló |
take.selected | Se eligió una toma en un plano o una escena |
asset_version.created | Un renderizado produjo una nueva versión del recurso |
["*"] | Todos los eventos |
curl -s -X POST "$FS/workspaces/$WS/webhooks" \
-H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
-d '{"url": "https://example.com/filmsquare/hook", "events": ["generation.succeeded", "take.selected"]}'POST /filmsquare/hook
content-type: application/json
x-fs-signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with whsec_…>
x-fs-event: generation.succeeded
x-fs-delivery: generation.succeeded:9b2e…CONVENCIONES Y ERRORES
Todo error tiene una sola forma
| TEMA | REGLA |
|---|---|
| Nombres de campos | Respuestas en snake_case, cuerpos de solicitud en camelCase. |
| Listas | Las listas responden {"items": […], "next_cursor": "…"}. Pasa cursor para la página siguiente, limit hasta 200, order asc o desc. |
| Idempotencia | Las solicitudes de toma aceptan un encabezado Idempotency-Key: la misma clave devuelve la misma toma. |
| Eliminar | Las filas se archivan, nunca se eliminan. Las versiones, las tomas elegidas, los vistos buenos y los costos nunca cambian. |
| No visible | Una fila que no puedes ver responde 404, igual que una fila que no existe. |
| ESTADO | CÓDIGO | CUÁNDO |
|---|---|---|
| 400 | validation_error | El cuerpo, la consulta o un parámetro de la ruta no coincide con el esquema |
| 401 | unauthenticated | Sin token, o con uno revocado o vencido |
| 402 | out_of_credits | No hay créditos libres suficientes para esta toma |
| 402 | plan_limit | El plan no lo incluye, como un final en Free |
| 402 | budget_exceeded | Se pasaría el presupuesto del episodio en créditos |
| 403 | insufficient_role | Tu rol está por debajo del x-min-role de la ruta |
| 403 | account_blocked | La cuenta está suspendida; se rechaza toda solicitud |
| 404 | not_found | La fila no existe, o no puedes verla |
| 409 | gate_closed | Un final antes de que den su visto bueno los departamentos de los que depende |
| 409 | workspace_paused | El espacio de trabajo está en pausa: no se inicia ninguna toma ni herramienta nueva en él |
{"error": {"code": "gate_closed",
"message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}GET /v1/pricing no necesita clave. Devuelve el precio de un crédito en euros, el de las licencias y los créditos que trae cada una, la acumulación, el almacenamiento y los paquetes de créditos: los números detrás de los precios.
curl -s https://app.filmsquare.ai/v1/pricingPreguntas
¿Es la misma API que usa el studio?
Sí. El studio, el propio Claude de cada persona y tus scripts llaman a las mismas rutas, con los mismos roles y las mismas reglas.
¿Las claves de API tienen alcances?
No. Una clave funciona en un espacio de trabajo con un rol, nunca por encima del rol de la persona que la creó. El rol es el alcance.
¿Dónde está la referencia?
El documento OpenAPI 3.1 en https://app.filmsquare.ai/v1/openapi.json es público y se genera a partir de las rutas, así que nunca queda desfasado.
¿Cómo sé cuándo una toma está lista?
Suscribe un webhook a generation.succeeded. Las entregas van firmadas con x-fs-signature y se reintentan ante 5xx, 429 y tiempos de espera agotados.
¿Puede un script renderizar finales antes del visto bueno?
No. Un final pedido antes de que se abra la luz verde responde 409 gate_closed, con los departamentos que está esperando.
¿Se pueden leer los precios sin una clave?
Sí. GET https://app.filmsquare.ai/v1/pricing es público y devuelve el precio del crédito, el de las licencias, la acumulación y los paquetes.