Conceitos

Escopos

Lista completa dos escopos da API v1, o que cada um libera e como escolhê-los na criação do token.

Cada token carrega um conjunto de escopos que definem exatamente o que ele pode acessar. Uma requisição com token válido mas sem o escopo exigido pelo endpoint recebe 403 FORBIDDEN.

Escopos disponíveis

Escopo	Acesso	Endpoints
`read:profile`	Dados do perfil do usuário	`GET /api/v1/profile`
`read:usage`	Saldo e uso de créditos	`GET /api/v1/credits`
`read:tasks`	Tasks de geração e seus resultados	`GET /api/v1/tasks` (filtro `?status=`), `GET /api/v1/tasks/:id`
`read:subscriptions`	Assinatura atual	`GET /api/v1/subscriptions`
`read:orders`	Histórico e status de cobranças	`GET /api/v1/orders`, `GET /api/v1/orders/:id`
`generate:image`	Geração e edição de imagens	`POST /api/v1/generate/image`, `image-edit`, `character-replace`, `background-remove`, `skin-enhance`, `image-upscale`, `influencer`
`generate:video`	Geração de vídeos	`POST /api/v1/generate/video-creative`, `video-ugc`, `video-imitate`
`generate:audio`	Síntese e conversão de voz	`POST /api/v1/generate/voice`, `voice-change`
`create:credits`	Compra de créditos avulsos (PIX)	`POST /api/v1/credits`
`create:subscriptions`	Criação de assinatura	`POST /api/v1/subscriptions`

GET /api/v1/plans é público — não exige token nem escopo. Não existe escopo read:plans. Ver Autenticação.

Token sem o escopo

Se o token não tiver o escopo exigido pelo endpoint, a resposta é 403 FORBIDDEN:

JSON

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Token sem o escopo necessário."
  }
}

Ver a tabela completa de erros em Erros.

Como escolher escopos

A gestão de tokens — criação, escolha dos escopos, expiração e revogação — é feita pelo usuário logado no painel, em /account/tokens, não pela própria API. Conceda apenas os escopos necessários para cada integração (princípio do menor privilégio).