Filmsquare

API

O estúdio, como API.

A API REST do Filmsquare é a mesma API que o estúdio e o Claude de cada pessoa usam, aberta para os seus scripts. JSON sobre HTTPS, um único documento OpenAPI 3.1 gerado a partir das rotas, uma chave bearer por pessoa e por espaço de trabalho, e webhooks assinados para quando um take fica pronto.

curl -s "$FS/me" \
  -H "Authorization: Bearer $FS_KEY"
Enviar uma requisiçãoGET /v1/me

URL BASE E AUTENTICAÇÃO

Uma chave, uma função, um espaço de trabalho

Toda chamada envia Authorization: Bearer <token>: uma chave de API que começa com fsk_, ou uma sessão iniciada. As rotas do espaço de trabalho levam o espaço de trabalho no caminho, /v1/workspaces/{ws}/….

URL BASE
https://app.filmsquare.ai/v1
PRIMEIRAS CHAMADAS
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

As chaves não têm escopos. O poder de uma chave é a função dela em um espaço de trabalho, nunca acima da função da pessoa por trás dela.

CHAVECOMO
Chave pessoalSettings → Claude → Use a personal key instead. Com a sua própria função, mostrada uma única vez.
Chave do espaço de trabalhoPOST /workspaces/{ws}/api-keys com um nome e uma função, por um(a) produtor(a) ou proprietário(a). Mostrada uma única vez; só o hash dela é guardado.
RevogarPOST /workspaces/{ws}/api-keys/{id}/revoke. A próxima chamada com ela responde 401 api_key_revoked.

OPENAPI 3.1

Um nome para uma chamada e uma tarefa

GET https://app.filmsquare.ai/v1/openapi.json é público, OpenAPI 3.1, e gerado a partir das próprias rotas. Toda rota tem um operationId, o mesmo nome com que o Claude a executa com run_action, então uma chamada que você escreve em script e uma tarefa que você passa ao Claude são exatamente a mesma coisa. x-min-role indica a menor função que pode chamá-la. Referência OpenAPI · MCP para o Claude

UMA OPERAÇÃO
"/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

Assine em vez de ficar consultando

Produtor(a) ou acima; o segredo whsec_ é mostrado uma única vez. Responda com um 2xx. Em caso de 5xx, 429 ou timeout, o Filmsquare tenta de novo com backoff exponencial, de cerca de 2 segundos até 10 minutos entre as tentativas, até 8 tentativas. x-fs-delivery continua o mesmo em todas as tentativas. Webhooks

EVENTOENVIADO QUANDO
generation.succeededUm take terminou de renderizar
generation.failedUma renderização falhou
take.selectedUm take foi escolhido num plano ou numa cena
asset_version.createdUma renderização gerou uma nova versão do asset
["*"]Todos os eventos
ASSINAR
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"]}'
UMA 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…

CONVENÇÕES E ERROS

Todo erro tem um formato

TÓPICOREGRA
Nomes dos camposRespostas em snake_case, corpos de requisição em camelCase.
ListasAs listas respondem {"items": […], "next_cursor": "…"}. Passe cursor para a próxima página, limit até 200, order asc ou desc.
IdempotênciaOs pedidos de take aceitam um cabeçalho Idempotency-Key: a mesma chave devolve o mesmo take.
ExclusãoAs linhas são arquivadas, nunca apagadas. Versões, takes escolhidos, aprovações e custos nunca mudam.
Não visívelUma linha que você não pode ver responde 404, igual a uma linha que não existe.
STATUSCÓDIGOQUANDO
400validation_errorO corpo, a query ou um parâmetro de caminho não bate com o esquema
401unauthenticatedSem token, ou com um token revogado ou expirado
402out_of_creditsCréditos livres insuficientes para este take
402plan_limitA assinatura não inclui isso, como um final no plano Grátis
402budget_exceededO orçamento do episódio, em créditos, seria ultrapassado
403insufficient_roleA sua função está abaixo do x-min-role da rota
403account_blockedA conta foi suspensa; todos os pedidos são recusados
404not_foundA linha não existe, ou você não pode vê-la
409gate_closedUm final antes de os departamentos de que ele depende terem aprovado
409workspace_pausedO espaço de trabalho está pausado: nenhum take ou ferramenta novo começa nele
TODO ERRO TEM UM FORMATO
{"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 não precisa de chave. Ele devolve o preço de um crédito em euros, os preços das licenças e os créditos que cada licença traz, o acúmulo de créditos, o armazenamento e os pacotes de créditos: os números por trás dos preços.

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

Perguntas

A API é a mesma que o estúdio usa?

Sim. O estúdio, o Claude de cada pessoa e os seus scripts chamam as mesmas rotas, com as mesmas funções e as mesmas regras.

As chaves de API têm escopos?

Não. Uma chave funciona em um espaço de trabalho com uma função, nunca acima da função de quem a criou. A função é o escopo.

Onde fica a referência?

O documento OpenAPI 3.1 em https://app.filmsquare.ai/v1/openapi.json é público e gerado a partir das rotas, então nunca fica para trás delas.

Como eu sei quando um take está pronto?

Assine um webhook em generation.succeeded. As entregas são assinadas com x-fs-signature e repetidas em caso de 5xx, 429 e timeouts.

Um script pode renderizar finais antes da aprovação?

Não. Um final pedido antes de a liberação abrir responde 409 gate_closed, com os departamentos de que ele está aguardando.

Os preços podem ser lidos sem uma chave?

Sim. GET https://app.filmsquare.ai/v1/pricing é público e devolve o preço do crédito, os preços das licenças, o acúmulo de créditos e os pacotes.