Filmsquare AjudaDocumentação

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.

Atualizado em 5 min de leitura.md

Nesta página
  1. Autenticação
  2. Conseguir uma chave
  3. Uma chave pessoal (qualquer função)
  4. Uma chave de API do espaço de trabalho (produtor(a) e acima)
  5. Funções
  6. Uma primeira sessão
  7. Convenções
  8. Erros que você vai encontrar
  9. Relacionados

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 basehttps://app.filmsquare.ai/v1
FormatoJSON sobre HTTPS
AutenticaçãoAuthorization: Bearer <chave de API ou token de sessão>
Referênciahttps://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) #

  1. No estúdio, abra o menu do espaço de trabalho no alto da barra lateral, e escolha Settings, depois Claude.
  2. Escolha Use a personal key instead (usar uma chave pessoal), dê um nome e escolha Create a personal key.
  3. 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 #

AssuntoRegra
Nomes de campoRespostas 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 arquivadasFicam fora das listas, a menos que includeArchived=true
ApagarAs linhas são arquivadas (POST …/{id}/archive), não apagadas. Versões, escolhas, aprovações e custos nunca mudam
IdempotênciaPedidos de geração aceitam um cabeçalho Idempotency-Key (ou idempotencyKey no corpo): a mesma chave devolve a geração existente
DinheiroOs 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"]}}}
StatusCódigoQuandodetails
400validation_errorO corpo, a query ou um parâmetro de caminho não bate com o schemaA lista de problemas de validação
400bad_request, invalid_valueA rota recusa o pedido, ou o banco de dados não consegue ler um valor (como um id malformado)—
400url_not_allowedUma URL de webhook ou de importação não é um endereço http(s) público—
401unauthenticatedSem token, ou um revogado ou expirado—
402out_of_creditsCréditos livres para gastar insuficientes para este takeneeded, available (créditos)
402plan_limitA assinatura não inclui isto: um final no plano Grátis, uma segunda produção, armazenamento, licenças, pacotes sem uma assinaturalimit (final, productions, storage, seats, packs), plan
402budget_exceededO orçamento do episódio (budgetCredits no episódio) seria ultrapassadoepisodeId, budgetCredits, spent, inFlight, needed (créditos)
403insufficient_roleA sua função está abaixo do mínimo da rotarequired, actual
403not_a_signerVocê não é aprovador(a) deste departamento—
403role_exceeds_callerUm convite ou uma chave com uma função acima da sua—
403not_a_personGerenciar chaves com uma chave pessoal ou uma conexão do Claude—
404not_foundA linha não existe, ou você não pode vê-la—
409gate_closedUm final antes de a liberação abrirepisode_id, waiting_on (departamentos, ou placement para um plano que não está em nenhum episódio)
409changed_sinceVocê aprovou uma versão que não é mais a atualversion (a atual)
409already_signed_offA etapa já está aprovada—
409element_version_frozenUma referência acrescentada a uma versão que um take já usou—
409conflictJá existe uma linha com estes valores—
422foreign_key_violation, check_violation, not_null_violationUma linha referenciada não existe (ou está em outro espaço de trabalho), ou uma regra do banco de dados recusou os valoresconstraint, 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}}}

Esta página em Markdown: /docs/pt-br/api/overview.md