Créditos

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

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 -s https://app.nodaro.ai/v1/credits/balance \
  -H "Authorization: Bearer $NODARO_API_KEY"

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

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:

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.

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.

Histórico de transações

GET /v1/credits/transactions retorna o seu histórico de créditos, do mais recente para o mais antigo:

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

{
  "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"
}

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

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) 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 -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"]}'

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

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.

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.

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:

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

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.
• 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 para as implantações que autorizam gastos pela própria carteira.