# Créditos

> Leia saldo e histórico de créditos pela API, calcule o preço de modelos e execuções antes de iniciá-las e entenda reservas, reembolsos e pagamento por uso.

Source: https://nodaro.ai/pt-BR/docs/developers/api/credits

Os **créditos** são a unidade com que você paga no Nodaro Cloud, e a API sempre os informa em créditos, nunca em dinheiro. Os endpoints de créditos retornam o seu saldo e o seu histórico de créditos e calculam o preço de modelos e execuções antes de você iniciá-los. Eles também informam a um cliente se a implantação com que ele se comunica mede o uso de alguma forma.

Os endpoints de créditos existem só no Nodaro Cloud. A Community Edition e a Business edition não têm sistema de créditos, então essas rotas respondem `404` nelas. `GET /v1/billing/surface` é a exceção: essa rota responde em todas as edições.

## Endpoints
| Método | Caminho | O que faz |
| --- | --- | --- |
| `GET` | `/v1/credits/balance` | O seu saldo: créditos totais, de assinatura e de recarga, e o seu nível. |
| `GET` | `/v1/user/credits` | Um registro de saldo mais completo, com os gastos do dia. |
| `GET` | `/v1/credits/transactions` | O seu histórico de créditos, em páginas. |
| `POST` | `/v1/credits/model-costs` | Pública. O preço em créditos de até 50 IDs de modelo. |
| `GET` | `/v1/credits/model-cost` | Pública. O preço em créditos de um ID de modelo, enviado como `?model=`. |
| `POST` | `/v1/credits/video-pro-estimate` | O preço de uma execução do **Gerar vídeo Pro** (Generate Video Pro). Veja [Jobs](https://nodaro.ai/docs/developers/api/jobs#estimate-a-run). |
| `GET` | `/v1/billing/surface` | Pública. Como esta implantação mede o uso. |
| `GET` | `/v1/billing/account` | O resumo da sua conta segundo a cobrança da implantação. |
| `POST` | `/v1/jobs/cost-summary` | Os créditos de um lote de jobs. |

As rotas públicas não precisam de token. As demais aceitam os mesmos tokens que qualquer outra rota: um token de API pessoal, um token OAuth ou um JWT de sessão.

## Ler o seu saldo
**curl**

```bash
curl -s https://app.nodaro.ai/v1/credits/balance \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

```json
{ "total": 1250, "subscription": 1000, "topup": 250, "tier": "pro", "effectiveTier": "pro" }
```

**TypeScript SDK**

```ts
const balance = await client.credits.balance()
console.log(`${balance.total} credits (${balance.effectiveTier})`)
```

`total` é `subscription` mais `topup`. `tier` é o nível de assinatura armazenado, como `free` ou `pro`. `effectiveTier` é o nível que o Nodaro realmente aplica: `payg` significa sem assinatura, mas com créditos comprados, todos os modelos liberados, sem marca d’água e sem limite diário.

`GET /v1/user/credits`, que o `client.credits.balance()` do SDK lê, retorna mais campos:

| Campo | Significado |
| --- | --- |
| `total`, `subscription`, `topup` | Os seus créditos, como acima. |
| `dailySpent` | Os créditos gastos hoje. |
| `dailyLimit` | O seu limite diário de gastos, ou `null` quando não há limite. |
| `monthlyAllocation` | Os créditos que o seu plano concede a cada ciclo de cobrança. |
| `tier`, `effectiveTier` | O seu nível armazenado e o nível aplicado. |
| `features` | Os recursos do seu nível. |
| `periodEnd` | Quando o período de cobrança termina. |
| `appCreditsAllowance` | Os créditos ganhos com o uso de apps, só no plano gratuito. |

Os gastos usam primeiro os créditos da assinatura. Os créditos da assinatura são redefinidos a cada ciclo de cobrança, e os créditos de recarga valem por 12 meses a partir da compra.

## Como os créditos são cobrados
- **Reservados quando um job começa.** Uma geração reserva o próprio preço antes de ser executada. Quando o seu saldo não cobre esse valor, a chamada responde `402 insufficient_credits` com `required` e, na maioria das contas, `balance`. Uma execução de workflow precisa de créditos suficientes para o custo no pior caso.
- **Cobrados quando o job entrega o resultado.** A reserva vira uma cobrança.
- **Reembolsados quando o job não entrega.** Uma geração bloqueada pelo filtro de segurança de um modelo ou pela política de uma implantação é sempre reembolsada, assim como os jobs cancelados.
- **Precificados pelo que realmente é executado.** Quando o servidor corrige uma configuração para o modelo escolhido, a reserva segue o valor corrigido. Veja [Correções de parâmetros](https://nodaro.ai/docs/developers/api/workflows#parameter-corrections).

O `credit_status` de um job e o `status` de uma transação seguem as mesmas etapas: `reserved` e, depois, `committed` ou `refunded`. Assim, você sabe pelo próprio job se os créditos dele voltaram. Veja [Créditos de um job](https://nodaro.ai/docs/developers/api/jobs#credits-of-a-job).

## Histórico de transações
`GET /v1/credits/transactions` retorna o seu histórico de créditos, do mais recente para o mais antigo:

| Parâmetro de consulta | Significado |
| --- | --- |
| `limit` | De 1 a 50. O padrão é 20. |
| `cursor` | O `nextCursor` da página anterior. É o horário `created_at` da última linha. |

```bash
curl -s "https://app.nodaro.ai/v1/credits/transactions?limit=2" \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

```json
{
"data": [
{
"id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"created_at": "2026-09-26T14:03:11.284Z",
"credits_used": 50,
"action": "generate-image",
"provider": "nano-banana-pro",
"status": "committed",
"metadata": { "model": "nano-banana-pro", "from_sub": 50, "from_topup": 0 },
"payer": "user",
"workspaceId": null
}
],
"nextCursor": "2026-09-26T14:03:11.284Z"
}
```

| Campo | Significado |
| --- | --- |
| `credits_used` | Os créditos deste lançamento. |
| `action`, `provider` | O que foi executado e em qual modelo. |
| `status` | `reserved`, `committed` ou `refunded`. |
| `payer` | `user` para o seu próprio saldo, `workspace` para o orçamento de uma turma ou de uma equipe. |
| `workspaceId` | O espaço de trabalho pagante, ou `null`. |
| `metadata` | Como a execução foi cobrada. Sempre um objeto: `{}` quando nada se aplica. |

`metadata` contém só estas chaves, quando elas se aplicam: `model`, `from_sub` e `from_topup` (qual dos seus saldos pagou), `is_app_run`, `allowance_delta`, `web_free_mode`, `status`, `loop_trim_refunded` e `surround_refine_refunded`.

`nextCursor` é `null` quando não há mais linhas.

## Calcular o preço de uma execução antes de iniciá-la
| Ferramenta | O que ela precifica |
| --- | --- |
| `POST /v1/credits/model-costs` | Até 50 IDs de modelo de uma vez. |
| `GET /v1/credits/model-cost` | Um ID de modelo. |
| `GET /v1/models` | Todos os modelos, com uma entrada `pricing` por variante. Veja [Descobrir modelos](https://nodaro.ai/docs/developers/api/nodes#discover-models). |
| `GET /v1/nodes/:type` | O `creditCost` de um nó: um preço único ou uma faixa. |
| `GET /v1/api/schema` | Um workflow inteiro, como `estimatedCredits`. Veja [Workflows](https://nodaro.ai/docs/developers/api/workflows#run-a-workflow-with-new-input-values). |
| `POST /v1/credits/video-pro-estimate` | Uma execução do Gerar vídeo Pro, sem reservar nada. Veja [Jobs](https://nodaro.ai/docs/developers/api/jobs#estimate-a-run). |
| `POST /v1/recast/estimate` | Uma execução do Recast. Veja [Recast](https://nodaro.ai/docs/developers/api/recast). |
| `POST /v1/pro-3d-render/quote` | Uma execução da **Renderização 3D Pro** (3D Render Pro). Veja [Cenas 3D](https://nodaro.ai/docs/developers/api/3d-scenes). |

Os preços dos modelos e dos nós, e o `estimatedCredits`, são os preços cobrados por uma execução: os mesmos números do botão **Executar** no editor. No **Cortar vídeo** (Trim Video), no **Vídeo em loop** (Loop Video) e no **Combinar vídeos** (Combine Videos), o `creditCost` do nó é, em vez disso, o preço de um bloco de 5 segundos. Uma execução desses nós custa um certo número de blocos. No `estimatedCredits`, um nó [**Efeitos sonoros para vídeo** (Video SFX)](https://nodaro.ai/docs/nodes/video/video-sfx#credits) conta pelo preço de 8 segundos, porque o clipe dele só é medido quando a execução começa. A execução cobra o preço da duração medida.

O preço de um modelo pode depender das configurações dele, por isso os IDs das variantes trazem essas configurações, como `nano-banana-pro:4K` ou `gpt-image-2:2K`:

**curl**

```bash
curl -s -X POST https://app.nodaro.ai/v1/credits/model-costs \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"models": ["nano-banana-pro", "nano-banana-pro:4K", "gpt-image-2:2K"]}'
```

```json
{
"data": { "nano-banana-pro": 50, "nano-banana-pro:4K": 66, "gpt-image-2:2K": 42 },
"missing": [],
"errors": []
}
```

**TypeScript SDK**

```ts
const { data, missing } = await client.credits.modelCosts(['nano-banana-pro', 'nano-banana-pro:4K'])
console.log(data['nano-banana-pro:4K'])
if (missing.length) console.warn('No price for:', missing)
```

Um ID sem preço vai para `missing`, e um ID cuja consulta de preço falhou vai para `errors`, então um ID ruim nunca derruba a requisição inteira. Mostre um traço para esses IDs, não zero. Os preços acima são um exemplo: leia a resposta em tempo real ou veja a página de cada modelo em [Modelos](https://nodaro.ai/docs/models).

A CLI não tem comandos de créditos, mas `nodaro models list` mostra os níveis de créditos de cada modelo.

## Pagamento por uso
Você não precisa de assinatura para usar a API.

- **Qualquer compra ativa o pagamento por uso.** Comprar um pacote de créditos, ou fazer uma recarga de qualquer valor inteiro em dólares de US$ 5 a US$ 1.000 na página Cobrança, muda a conta para o pagamento por uso. Recargas maiores têm um preço melhor por crédito.
- **Tudo liberado.** `effectiveTier` passa a ser `payg`: todos os modelos ficam disponíveis, os resultados não têm marca d’água e não há limite diário de gastos.
- **Os créditos valem por 12 meses** a partir da compra.
- **Para as interfaces para desenvolvedores.** Os créditos do pagamento por uso funcionam pela API, pelo SDK, pela CLI e pelo MCP. O editor web exige uma assinatura, e uma conta de pagamento por uso que tenta gastar créditos por ele recebe `403 subscription_required`. As chamadas com token nunca recebem esse erro.
- **As assinaturas custam menos por crédito** com um volume constante.

Duas coisas para saber:

- **Os resultados são públicos por padrão.** Resultados privados são um recurso de assinatura, a partir do plano Standard, então os resultados do pagamento por uso aparecem na galeria pública. Os jobs criados pelo MCP são sempre privados.
- **A mídia é mantida enquanto a conta está ativa.** Depois de cerca de 3 meses sem compras e sem gasto de créditos, os arquivos com mais de 60 dias podem ser removidos. Voltar a gastar créditos interrompe a limpeza.

As compras em si acontecem no app web: as rotas `/v1/billing/*` de finalização de compra, recargas, recarga automática, histórico de compras e portal de pagamento recusam tokens de API e tokens OAuth. Gerencie a cobrança em [app.nodaro.ai/billing](https://app.nodaro.ai/billing).

## Saber como uma implantação mede o uso
Duas rotas permitem que um cliente monte visões de custo e de uso sem presumir como a implantação cobra:

**`GET /v1/billing/surface`** não precisa de token e retorna a mesma resposta para todos:

```json
{
"data": {
"contract": 2,
"providerId": "…",
"displayUnit": "credits",
"canReport": true,
"canQuote": true,
"canAccount": true,
"mountCostTab": true,
"deploymentPayer": false
}
}
```

- `displayUnit` é a unidade que uma visão de custo deve mostrar por padrão, como `credits` ou `usd`.
- Em uma instalação da Community Edition sem créditos, `providerId` é `none` e `mountCostTab` é `false`: não mostre nenhuma visão de custo.
- `deploymentPayer` é `true` quando uma conta de cobrança paga por todos os usuários. A identidade dessa conta nunca é mostrada.

**`GET /v1/billing/account`** retorna o resumo da sua conta como `{ "data": … }`. Quando o serviço de cobrança não consegue responder, `data` é `null`: mostre isso como indisponível, nunca como saldo zero. O resumo sempre tem:

| Campo | Significado |
| --- | --- |
| `plan` | O seu plano, como string. `unknown` é uma resposta válida. |
| `balance` | O seu saldo, ou `null`. |
| `dailyAllowance` | O seu limite de uso diário, ou `null`. |
| `unit` | A unidade desses valores. |

Uma implantação pode adicionar campos opcionais, e um cliente mostra só os que recebe: `periodStart`, `generations`, `spent`, `payg`, `daily`, `reserveValue` e `byCategory`. Os valores em dinheiro são objetos `{ amount, currency }`. Em `daily`, um `limit` igual a `0` significa bloqueado, não ilimitado, e `daily` prevalece sobre `dailyAllowance` quando os dois estão presentes. Todo `null` significa indisponível, nunca zero: mostre um traço.

**`POST /v1/jobs/cost-summary`** soma os créditos de um lote de jobs. `total_credits`, no nível superior e em cada linha do detalhamento, é um número ou `null`. A resposta indica a sua `unit` e conta em `unavailable` os jobs que não conseguiu precificar. Um total `null` significa que nenhum job do lote tinha uma cobrança conhecida. Não significa zero.

## Espaços de trabalho e cobrança compartilhada
- **Orçamentos de espaço de trabalho.** O trabalho feito dentro do espaço de trabalho de uma organização é pago pelo orçamento do espaço de trabalho, não pelo seu saldo, e as transações dele trazem `payer: "workspace"`. Uma execução acima do orçamento responde `402 budget_exceeded`, e uma execução acima do seu próprio limite nesse espaço de trabalho responde `402 member_cap_exceeded`. Veja [Espaços de trabalho e organizações](https://nodaro.ai/docs/developers/api/workspaces#budgets-and-usage).
- **Implantações com uma única conta de cobrança.** Em uma implantação em que uma conta de cobrança paga por todos os usuários, `GET /v1/user/credits` adiciona `allowance: { granted, remaining, enforced }`, o seu próprio limite de uso em créditos. `enforced: false` significa que o limite aparece, mas não bloqueia execuções. `allowance` é `null` para a própria conta de cobrança ou quando não pôde ser lido, então nunca interprete `null` como zero. Quando a implantação aplica os limites de uso, uma execução acima do seu limite responde `402 user_allowance_exceeded`. A conta de cobrança gerencia o saldo compartilhado só pela própria sessão do navegador: as leituras de saldo dela feitas com um token respondem `403 payer_balance_jwt_only`. Veja [Carteiras externas](https://nodaro.ai/docs/developers/external-wallet) para as implantações que autorizam gastos pela própria carteira.

## Frequently asked questions

### Como verifico meu saldo de créditos pela API?

Envie GET /v1/credits/balance. Ele retorna os créditos total, subscription e topup, além de tier e effectiveTier. No SDK, client.credits.balance() retorna um registro mais completo, que também inclui os seus gastos do dia.

### Quando os créditos de uma geração pela API são cobrados?

Os créditos são reservados quando o job começa e cobrados quando ele entrega o resultado. Quando um job é bloqueado por um filtro de segurança ou por uma política, ou é cancelado antes de ser executado, a reserva é reembolsada. O credit_status do job mostra o que aconteceu.

### Posso usar a API do Nodaro sem assinatura?

Sim. Comprar qualquer pacote de créditos ativa o pagamento por uso, com todos os modelos liberados, sem marca d’água e sem limite diário. Os créditos do pagamento por uso funcionam pela API, pelo SDK, pela CLI e pelo MCP, e valem por 12 meses.

### Como sei quanto uma execução vai custar antes de iniciá-la?

POST /v1/credits/model-costs retorna o preço em créditos de até 50 IDs de modelo, GET /v1/models lista os níveis de preço de cada modelo e GET /v1/api/schema estima um workflow inteiro. O Gerar vídeo Pro tem uma rota própria de estimativa.

### Os endpoints de créditos funcionam em uma instalação self-hosted?

Não. A Community Edition e a Business edition não têm sistema de créditos, então as rotas de créditos respondem 404 nelas, e os descritores de nós e de modelos omitem os preços em créditos. Você paga diretamente aos provedores dos modelos.