6.0 API6.1 Visão geral da API e chaves
Visão geral da API e chaves
A API REST do Filmsquare: URL base, autenticação com chaves de API ou uma sessão, como criar uma chave, convenções e os erros que você vai encontrar.
Tudo o que o estúdio faz passa por uma só API REST, e você também pode usá-la: o app, o seu próprio Claude e os seus scripts chamam as mesmas rotas, com as mesmas funções e as mesmas regras.
| URL base | https://app.filmsquare.ai/v1 |
| Formato | JSON sobre HTTPS |
| Autenticação | Authorization: Bearer <chave de API ou token de sessão> |
| Referência | https://app.filmsquare.ai/v1/openapi.json (OpenAPI 3.1, pública). Veja a referência OpenAPI |
Autenticação #
Toda rota, exceto algumas públicas (GET /v1/pricing, POST /v1/signup, os receptores de webhook), precisa de um token
bearer:
- Uma chave de API, começando com
fsk_. Uma chave pertence a uma pessoa (ou usuário agente) em um espaço de trabalho, e age com a função da chave, nunca mais do que a função atual dessa pessoa. - Um token de sessão de uma pessoa conectada (o que o app web envia).
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_… # your key
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
GET /me devolve quem você é, se você entrou com uma chave e os seus espaços de trabalho. Toda rota de espaço de trabalho tem o
id do espaço de trabalho no caminho: /v1/workspaces/{ws}/….
Conseguir uma chave #
Uma chave pessoal (qualquer função) #
- No estúdio, abra o menu do espaço de trabalho no alto da barra lateral, e escolha Settings, depois Claude.
- Escolha Use a personal key instead (usar uma chave pessoal), dê um nome e escolha Create a personal key.
- Copie a chave. Ela aparece uma vez só.
Uma chave pessoal tem a sua própria função naquele espaço de trabalho. Ela foi feita para o Claude Code, mas serve para qualquer chamada de API que a sua função permita, exceto gerenciar chaves.
Uma chave de API do espaço de trabalho (produtor(a) e acima) #
Um(a) produtor(a) ou proprietário(a), conectado, pode criar chaves com uma função escolhida pela 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"}'
A resposta traz a key completa uma vez; o Filmsquare guarda só o hash dela. A função de uma chave nunca pode estar acima da sua. Com
userId você pode criar uma chave para um usuário agente que é integrante do espaço de trabalho.
GET /workspaces/{ws}/api-keys lista as chaves (só o prefixo); POST /workspaces/{ws}/api-keys/{id}/revoke revoga uma.
Chaves não criam chaves: essas rotas precisam de uma pessoa conectada ou de uma chave do espaço de trabalho, e recusam uma chave pessoal ou uma
conexão do Claude com 403 not_a_person.
Funções #
Cada rota tem uma função mínima: owner > producer > director > maker > reviewer > viewer. Uma chamada abaixo dela
recebe 403 insufficient_role com {"required": "director", "actual": "maker"}. Uma linha que você não pode ver responde 404,
igual a uma linha que não existe. Veja Equipe, funções e acesso.
Uma primeira sessão #
# 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 é keyframe, video, dialogue, sfx ou music; tier é draft ou final. Nenhum modelo conectado
faz sfx ou music ainda: esses takes entram como envios (createUploadTicket, depois completeUpload com uma
camada de destino). Se você deixar de fora modelKey, o
Filmsquare roteia para o modelo capaz com o menor custo por take aprovado. Em vez de consultar de tempos em tempos, assine
webhooks.
Convenções #
| Assunto | Regra |
|---|---|
| Nomes de campo | Respostas em snake_case, corpos de requisição em camelCase |
| Listas | {"items": […], "next_cursor": "…"}. Passe cursor para a próxima página; limit até 200; order asc ou desc |
| Linhas arquivadas | Ficam fora das listas, a menos que includeArchived=true |
| Apagar | As linhas são arquivadas (POST …/{id}/archive), não apagadas. Versões, escolhas, aprovações e custos nunca mudam |
| Idempotência | Pedidos de geração aceitam um cabeçalho Idempotency-Key (ou idempotencyKey no corpo): a mesma chave devolve a geração existente |
| Dinheiro | Os custos são em créditos, cada um na taxa em que o trabalho começou; quanto um crédito custa em euros está em GET /v1/pricing e em Créditos e quanto as coisas custam |
Erros que você vai encontrar #
Todo erro tem o mesmo formato:
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
| Status | Código | Quando | details |
|---|---|---|---|
| 400 | validation_error | O corpo, a query ou um parâmetro de caminho não bate com o schema | A lista de problemas de validação |
| 400 | bad_request, invalid_value | A rota recusa o pedido, ou o banco de dados não consegue ler um valor (como um id malformado) | — |
| 400 | url_not_allowed | Uma URL de webhook ou de importação não é um endereço http(s) público | — |
| 401 | unauthenticated | Sem token, ou um revogado ou expirado | — |
| 402 | out_of_credits | Créditos livres para gastar insuficientes para este take | needed, available (créditos) |
| 402 | plan_limit | A assinatura não inclui isto: um final no plano Grátis, uma segunda produção, armazenamento, licenças, pacotes sem uma assinatura | limit (final, productions, storage, seats, packs), plan |
| 402 | budget_exceeded | O orçamento do episódio (budgetCredits no episódio) seria ultrapassado | episodeId, budgetCredits, spent, inFlight, needed (créditos) |
| 403 | insufficient_role | A sua função está abaixo do mínimo da rota | required, actual |
| 403 | not_a_signer | Você não é aprovador(a) deste departamento | — |
| 403 | role_exceeds_caller | Um convite ou uma chave com uma função acima da sua | — |
| 403 | not_a_person | Gerenciar chaves com uma chave pessoal ou uma conexão do Claude | — |
| 404 | not_found | A linha não existe, ou você não pode vê-la | — |
| 409 | gate_closed | Um final antes de a liberação abrir | episode_id, waiting_on (departamentos, ou placement para um plano que não está em nenhum episódio) |
| 409 | changed_since | Você aprovou uma versão que não é mais a atual | version (a atual) |
| 409 | already_signed_off | A etapa já está aprovada | — |
| 409 | element_version_frozen | Uma referência acrescentada a uma versão que um take já usou | — |
| 409 | conflict | Já existe uma linha com estes valores | — |
| 422 | foreign_key_violation, check_violation, not_null_violation | Uma linha referenciada não existe (ou está em outro espaço de trabalho), ou uma regra do banco de dados recusou os valores | constraint, table, detail |
402 out_of_credits fica assim:
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
"details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
Relacionados #
- Webhooks
- Referência OpenAPI
- O que o Claude faz: a mesma API via MCP