Filmsquare

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"
Enviar una solicitudGET /v1/me

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}/….

URL BASE
https://app.filmsquare.ai/v1
PRIMERAS LLAMADAS
export 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"}'
  1. owner
  2. producer
  3. director
  4. maker
  5. reviewer
  6. viewer

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.

CLAVECÓMO
Clave personalSettings → Claude → Use a personal key instead. Tu propio rol, se muestra una sola vez.
Clave del espacio de trabajoPOST /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.
RevocarPOST /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

UNA OPERACIÓN
"/workspaces/{ws}/shots/{id}/generations": {
  "post": {
    "operationId": "generateForShot",
    "x-min-role": "maker",
    …
  }
}
TERMINAL
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

EVENTOSE ENVÍA CUANDO
generation.succeededUna toma terminó de renderizarse
generation.failedUn renderizado falló
take.selectedSe eligió una toma en un plano o una escena
asset_version.createdUn renderizado produjo una nueva versión del recurso
["*"]Todos los eventos
SUSCRIBIRSE
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"]}'
UNA ENTREGA
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

TEMAREGLA
Nombres de camposRespuestas en snake_case, cuerpos de solicitud en camelCase.
ListasLas listas responden {"items": […], "next_cursor": "…"}. Pasa cursor para la página siguiente, limit hasta 200, order asc o desc.
IdempotenciaLas solicitudes de toma aceptan un encabezado Idempotency-Key: la misma clave devuelve la misma toma.
EliminarLas filas se archivan, nunca se eliminan. Las versiones, las tomas elegidas, los vistos buenos y los costos nunca cambian.
No visibleUna fila que no puedes ver responde 404, igual que una fila que no existe.
ESTADOCÓDIGOCUÁNDO
400validation_errorEl cuerpo, la consulta o un parámetro de la ruta no coincide con el esquema
401unauthenticatedSin token, o con uno revocado o vencido
402out_of_creditsNo hay créditos libres suficientes para esta toma
402plan_limitEl plan no lo incluye, como un final en Free
402budget_exceededSe pasaría el presupuesto del episodio en créditos
403insufficient_roleTu rol está por debajo del x-min-role de la ruta
403account_blockedLa cuenta está suspendida; se rechaza toda solicitud
404not_foundLa fila no existe, o no puedes verla
409gate_closedUn final antes de que den su visto bueno los departamentos de los que depende
409workspace_pausedEl espacio de trabajo está en pausa: no se inicia ninguna toma ni herramienta nueva en él
TODO ERROR TIENE UNA SOLA FORMA
{"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.

TERMINAL
curl -s https://app.filmsquare.ai/v1/pricing

Preguntas

¿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.