---
title: "Visão geral da API e chaves"
description: "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."
url: https://www.filmsquare.ai/docs/pt-br/api/overview/
lang: pt-BR
section: api
updated: 2026-11-10
---

# Visão geral da API e chaves

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](https://www.filmsquare.ai/docs/pt-br/api/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).

```bash
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:

```bash
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](https://www.filmsquare.ai/docs/pt-br/working-together/crew-and-roles/).

## Uma primeira sessão

```bash
# 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](https://www.filmsquare.ai/docs/pt-br/api/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](https://www.filmsquare.ai/docs/pt-br/concepts/credits-and-costs/) |

## Erros que você vai encontrar

Todo erro tem o mesmo formato:

```json
{"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:

```json
{"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](https://www.filmsquare.ai/docs/pt-br/api/webhooks/)
- [Referência OpenAPI](https://www.filmsquare.ai/docs/pt-br/api/openapi/)
- [O que o Claude faz](https://www.filmsquare.ai/docs/pt-br/claude/tools/): a mesma API via MCP
