Filmsquare AyudaDocumentación

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.

Actualizado 5 min de lectura.md

En esta página
  1. Autenticación
  2. Conseguir una clave
  3. Una clave personal (cualquier rol)
  4. Una clave de API del espacio de trabajo (productor y superior)
  5. Roles
  6. Una primera sesión
  7. Convenciones
  8. Errores que te encontrarás
  9. Relacionado

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 basehttps://app.filmsquare.ai/v1
FormatoJSON sobre HTTPS
AutenticaciónAuthorization: Bearer <API key or session token>
Referenciahttps://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) #

  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:

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 #

TemaRegla
Nombres de campoRespuestas 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 archivadasQuedan fuera de las listas salvo includeArchived=true
BorradoLas filas se archivan (POST …/{id}/archive), no se borran. Las versiones, tomas elegidas, vistos buenos y costos nunca se cambian
IdempotenciaLas peticiones de generación admiten una cabecera Idempotency-Key (o idempotencyKey en el cuerpo): la misma clave devuelve la generación existente
DineroLos 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"]}}}
EstadoCódigoCuándodetails
400validation_errorEl cuerpo, la query o un parámetro de ruta no coincide con el esquemaLa lista de problemas de validación
400bad_request, invalid_valueLa ruta rechaza la petición, o la base de datos no puede leer un valor (como un id mal formado)—
400url_not_allowedLa URL de un webhook o de una importación no es una dirección http(s) pública—
401unauthenticatedSin token, o con uno revocado o vencido—
402out_of_creditsNo hay créditos suficientes disponibles para gastar en esta tomaneeded, available (créditos)
402plan_limitEl plan no incluye esto: un final en Free, una segunda producción, almacenamiento, licencias, paquetes sin un planlimit (final, productions, storage, seats, packs), plan
402budget_exceededSe superaría el presupuesto del episodio (budgetCredits en el episodio)episodeId, budgetCredits, spent, inFlight, needed (créditos)
403insufficient_roleTu rol está por debajo del mínimo de la rutarequired, actual
403not_a_signerNo eres responsable del visto bueno de este departamento—
403role_exceeds_callerUna invitación o una clave con un rol por encima del tuyo—
403not_a_personGestionar claves con una clave personal o una conexión de Claude—
404not_foundLa fila no existe, o no puedes verla—
409gate_closedUn final antes de que haya luz verdeepisode_id, waiting_on (departamentos, o placement para un plano que no está en ningún episodio)
409changed_sinceDiste el visto bueno a una versión que ya no es la actualversion (la actual)
409already_signed_offEl paso ya tiene visto bueno—
409element_version_frozenUna referencia añadida a una versión que una toma ya usó—
409conflictYa existe una fila con estos valores—
422foreign_key_violation, check_violation, not_null_violationUna fila referenciada no existe (o está en otro espacio de trabajo), o una regla de la base de datos rechazó los valoresconstraint, 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}}}

Esta página en Markdown: /docs/es/api/overview.md