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"
WEBHOOK · POST /filmsquare/hook

S3-B5-05Seedance 2.5 · Final 1080p · 5 s · 105,30 créditos · € 5,27
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}/….
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
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.
| CHAVE | COMO |
|---|---|
| Chave pessoal | Settings → Claude → Use a personal key instead. Com a sua própria função, mostrada uma única vez. |
| Chave do espaço de trabalho | POST /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. |
| Revogar | POST /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
"/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
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
| EVENTO | ENVIADO QUANDO |
|---|---|
generation.succeeded | Um take terminou de renderizar |
generation.failed | Uma renderização falhou |
take.selected | Um take foi escolhido num plano ou numa cena |
asset_version.created | Uma renderização gerou uma nova versão do asset |
["*"] | Todos os 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…CONVENÇÕES E ERROS
Todo erro tem um formato
| TÓPICO | REGRA |
|---|---|
| Nomes dos campos | Respostas em snake_case, corpos de requisição em camelCase. |
| Listas | As listas respondem {"items": […], "next_cursor": "…"}. Passe cursor para a próxima página, limit até 200, order asc ou desc. |
| Idempotência | Os pedidos de take aceitam um cabeçalho Idempotency-Key: a mesma chave devolve o mesmo take. |
| Exclusão | As linhas são arquivadas, nunca apagadas. Versões, takes escolhidos, aprovações e custos nunca mudam. |
| Não visível | Uma linha que você não pode ver responde 404, igual a uma linha que não existe. |
| STATUS | CÓDIGO | QUANDO |
|---|---|---|
| 400 | validation_error | O corpo, a query ou um parâmetro de caminho não bate com o esquema |
| 401 | unauthenticated | Sem token, ou com um token revogado ou expirado |
| 402 | out_of_credits | Créditos livres insuficientes para este take |
| 402 | plan_limit | A assinatura não inclui isso, como um final no plano Grátis |
| 402 | budget_exceeded | O orçamento do episódio, em créditos, seria ultrapassado |
| 403 | insufficient_role | A sua função está abaixo do x-min-role da rota |
| 403 | account_blocked | A conta foi suspensa; todos os pedidos são recusados |
| 404 | not_found | A linha não existe, ou você não pode vê-la |
| 409 | gate_closed | Um final antes de os departamentos de que ele depende terem aprovado |
| 409 | workspace_paused | O espaço de trabalho está pausado: nenhum take ou ferramenta novo começa nele |
{"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.
curl -s https://app.filmsquare.ai/v1/pricingPerguntas
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.