NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
API REST

Créditos

Leia saldo e histórico de créditos, liste planos e preços, calcule o preço de modelos e execuções antes de iniciá-las e entenda reservas e reembolsos.

Disponível em Nodaro Cloud

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étodoCaminhoO que faz
GET/v1/credits/balanceO seu saldo: créditos totais, de assinatura e de recarga, e o seu nível.
GET/v1/user/creditsUm registro de saldo mais completo, com os gastos do dia.
GET/v1/credits/transactionsO seu histórico de créditos, em páginas.
GET/v1/credits/usage-summaryO seu uso de créditos em um período, somado para uma tela de cobrança.
GET/v1/credits/historyCada movimento do seu saldo, em páginas ou como um arquivo CSV.
POST/v1/credits/model-costsPública. O preço em créditos de até 50 IDs de modelo.
GET/v1/credits/model-costPública. O preço em créditos de um ID de modelo, enviado como ?model=.
POST/v1/credits/video-pro-estimateO preço de uma execução do Gerar vídeo Pro. Veja Tarefas.
POST/v1/credits/seedance-ref-estimateO preço de uma execução do Seedance 2, do Kling 4.0 ou do Kling 4.0 Flash com vídeos de referência. Veja Estimativas do Seedance com vídeos de referência.
GET/v1/billing/plansPública. Os planos e os pacotes de créditos à venda, com os preços.
GET/v1/billing/subscriptionA sua própria assinatura e o nível que a sua conta segue.
GET/v1/billing/surfacePública. Como esta implantação mede o uso.
GET/v1/billing/accountO resumo da sua conta segundo a cobrança da implantação.
GET, POST, PUT/v1/billing/…Compras, faturas, o cartão, a recarga automática e a finalização de compra, só para uma sessão com login feito. Veja Comprar e gerenciar a cobrança.
POST/v1/jobs/cost-summaryOs créditos de um lote de tarefas.

As rotas públicas não precisam de token. As rotas de cobrança que compram e gerenciam a cobrança só respondem a uma sessão com login feito. 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:

CampoSignificado
total, subscription, topupOs seus créditos, como acima.
dailySpentOs créditos gastos hoje.
dailyLimitO seu limite diário de gastos, ou null quando não há limite.
monthlyAllocationOs créditos que o seu plano concede a cada ciclo de cobrança.
tier, effectiveTierO seu nível armazenado e o nível aplicado.
featuresOs recursos do seu nível.
periodEndQuando o período de cobrança termina.
appCreditsAllowanceOs 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 voltam à cota mensal do plano todo mês, também em um plano anual, e os créditos da assinatura não usados não se acumulam. Os créditos de recarga valem por 12 meses a partir da compra.

Se o pagamento de uma renovação falhar, os créditos da assinatura que restam nesse período ficam retidos. Eles voltam quando a renovação é paga. Quando uma assinatura termina, os créditos restantes do plano terminam com ela: a conta passa para o plano gratuito com 0 crédito de assinatura e mantém os créditos de recarga. Encerrar um plano não adiciona créditos gratuitos, mas uma conta que nunca resgatou o bônus gratuito único ainda pode resgatá-lo. Os créditos gratuitos ainda não gastos quando a conta assina passam para os créditos de recarga, onde continuam válidos por 12 meses, como qualquer recarga.

Uma implantação pode mostrar a própria unidade em vez de créditos. Nela, GET /v1/user/credits também traz display: os mesmos números, convertidos pelo servidor. Ele contém unit (o rótulo da unidade), decimals (as casas decimais dos números) e total, subscription, topup, dailySpent, dailyLimit, monthlyAllocation e appCreditsAllowance. Ele acrescenta allowance: { granted, remaining }, externalWallet: { available } e welcomeOffer: { credits } exatamente quando as chaves originais estão presentes. Mostre esses números como vieram e nunca converta créditos você mesmo. null significa indisponível. Quando a implantação dá um nome à unidade em cada idioma da interface, display também traz unitLabels: { "<locale id>": "<word>" }: mostre a entrada do idioma da sua interface, ou então unit. display não vem quando não há unidade configurada, nem na leitura da própria conta de cobrança em uma implantação com uma só conta de cobrança, cujo saldo continua em créditos. Todos os campos originais ficam iguais.

Enquanto a implantação mantém uma oferta de boas-vindas, GET /v1/user/credits também traz welcomeOffer: { popupDue, popupSeen, consentPending, credits }. credits é o número de créditos que um resgate concede: mostre esse número em vez de um valor fixo. Com consentPending: true, credits é o que a conta recebeu, que pode ser mais do que um resgate concede hoje, porque um bônus anterior e maior é mantido. A chave não aparece enquanto nenhuma oferta está ativa.

popupDue diz se a janela de boas-vindas deve abrir sozinha agora, e quem decide é o servidor. A janela está pendente enquanto o bônus não foi resgatado, Talvez depois nunca foi respondido e a janela abriu sozinha menos de três vezes, nenhuma delas nas últimas 24 horas. Só Talvez depois responde à janela. Um fechamento sem resposta (o ×, Escape, um clique fora) deixa que ela abra sozinha de novo em uma visita posterior. Não a abra sozinha duas vezes na mesma visita. A contagem fica na conta, então todos os apps a compartilham. popupSeen é !popupDue, mantido para apps escritos antes de popupDue.

POST /v1/credits/welcome-offer/seen recebe { event?: "shown" | "later" }. "shown" informa que a janela abriu sozinha: conta uma exibição enquanto a janela está pendente, e nada nos outros casos. "later" informa Talvez depois: a janela não abre mais sozinha. Sem corpo, ou com qualquer outro event, a chamada é lida como "later". Para informar um fechamento sem resposta, não chame a rota. A oferta é resgatada no app web do Nodaro: as duas rotas dela, POST /v1/credits/welcome-offer/claim e POST /v1/credits/welcome-offer/seen, aceitam apenas uma sessão de navegador com login e respondem 403 forbidden a um token de API ou a um token de app OAuth.

Como os créditos são cobrados

  • Reservados quando uma tarefa 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. Em uma execução de workflow, cada nó reserva o próprio preço quando começa, e um nó que o seu saldo não cobre falha.
  • Cobrados quando a tarefa entrega o resultado. A reserva vira uma cobrança.
  • Reembolsados quando a tarefa 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 as tarefas canceladas. Uma chamada de LLM medida é a exceção: o uso que o provedor já cobrou é cobrado.
  • As chamadas de LLM são medidas. Uma chamada a um modelo de linguagem primeiro reserva créditos e depois é cobrada pelos tokens que usou, pela tarifa do modelo. Veja Chamadas de LLM.
  • 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 uma tarefa e o status de uma transação seguem as mesmas etapas: reserved e, depois, committed ou refunded. Assim, você sabe pela própria tarefa se os créditos dela voltaram. Veja Créditos de uma tarefa.

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 consultaSignificado
limitDe 1 a 50. O padrão é 20.
cursorO nextCursor da página anterior. É o horário created_at da última linha.
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_charged": 50,
      "credits_reserved": 50,
      "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"
}
CampoSignificado
credits_chargedQuanto a execução custou para você, depois de liquidada. Pode ser menor que a reserva, é 0 quando a reserva foi reembolsada e é null enquanto a reserva ainda está aberta (status: "reserved"). Some este campo para obter o seu gasto.
credits_reservedA reserva feita quando a execução foi aceita. Ela nunca muda.
credits_usedA mesma reserva de credits_reserved, com o nome original, mantida para as integrações existentes. Ela não muda depois de uma liquidação parcial, então fica acima da cobrança nessas execuções. Prefira credits_charged.
action, providerO que foi executado e em qual modelo.
statusreserved, committed ou refunded.
payeruser para o seu próprio saldo, workspace para o orçamento de uma turma ou de uma equipe.
workspaceIdO espaço de trabalho pagante, ou null.
metadataComo a execução foi cobrada. Sempre um objeto: {} quando nada se aplica.

Qual valor ler. Primeiro, uma execução reserva créditos: a reserva. Depois, a execução é liquidada: ela é cobrada por toda a reserva ou por parte dela, e o resto volta para o seu saldo. Algumas execuções costumam ser liquidadas abaixo da reserva, por exemplo, uma reserva que cobre uma possível nova renderização, uma duração medida depois da execução ou uma execução medida por uso. Por isso, a reserva não é o que você pagou. Por exemplo, uma execução que reservou 888 créditos e foi cobrada em 444 mostra credits_charged: 444, credits_reserved: 888, credits_used: 888 e status: "committed". Os outros 444 créditos voltaram para o seu saldo.

status é o ciclo de vida da reserva: reserved (créditos reservados, ainda não resolvidos), committed (cobrados, porque a execução entregou o resultado; a cobrança é credits_charged) ou refunded (a reserva foi liberada, por exemplo, depois de um bloqueio de segurança). As respostas de tarefa mostram o mesmo ciclo de vida como credit_status, com o valor liquidado como credits_charged. Assim, você não precisa da transação para saber quanto uma tarefa custou. Veja Créditos de uma tarefa.

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.

Resumo de uso

GET /v1/credits/usage-summary soma o uso de créditos de um período, da forma como uma tela de cobrança o mostra. Ele conta só o seu dinheiro pessoal: uma execução paga por um espaço de trabalho e os créditos de uma organização são outra carteira. A resposta é { data: UsageSummary }.

ConsultaSignificado
from, toUm timestamp ISO, ou só uma data: 2026-10-01 é aquele dia UTC inteiro. Os dois são inclusivos. O padrão são os últimos 30 dias até agora. Eles podem ter no máximo um ano de distância, senão a chamada responde 400.
bucketday, week ou month, para a série ao longo do tempo. O padrão é day.
CampoSignificado
period{ from, to, bucket }, como o servidor os recebeu.
totals{ used, purchased, granted, refunded, runs, avgPerRun }. Veja abaixo.
mostUsedA primeira linha de byModel, ou null sem execuções.
byModelLinhas { model, provider, credits, runs, share }, por gasto. share é a parte de used, de 0 a 1.
byCategoryLinhas { category, credits, runs }, em que category é image, video, audio ou other.
overTimeUma linha por intervalo do período, incluindo os vazios, do mais antigo para o mais recente: { bucket, used, purchased, runs }. bucket é o dia UTC (2026-10-26), a segunda-feira da semana ou o mês (2026-10). O primeiro intervalo pode ser uma semana ou um mês parcial.
bySession, byWorkflowLinhas { id, name, tool, credits, runs, models, lastAt }, por gasto: quanto cada sessão ou workflow custou. name é null quando não há nome ou o item não existe mais, e tool só aparece em uma sessão.
truncatedtrue quando uma leitura atingiu o limite de 5.000 linhas do servidor, então os valores ficam abaixo do real. Peça um período mais curto.
partialtrue quando uma leitura auxiliar falhou, então um agrupamento está faltando ou sem nome. Os totais continuam completos.

Em totals, used soma a cobrança de cada execução: uma execução ainda em andamento conta pela reserva, e uma execução reembolsada não conta. purchased são os pacotes, as recargas e as concessões da assinatura. granted são os créditos gratuitos, menos qualquer concessão retirada. refunded é o que voltou por uma execução reembolsada ou pelo Stripe. Uma reserva liberada quando uma execução foi liquidada abaixo dela não é um reembolso. runs conta as execuções cobradas ou ainda em andamento.

No SDK, é client.credits.usageSummary(), e na CLI, nodaro billing summary.

Cada movimento do seu saldo

GET /v1/credits/history lista cada movimento do seu saldo, do mais recente para o mais antigo, como { data: HistoryEntry[], nextCursor }: execuções, compras, concessões, reembolsos, ajustes e expirações.

ConsultaSignificado
limitDe 1 a 100. O padrão é 50.
cursorO nextCursor da página anterior. É opaco: qualquer outro texto responde 400.
kindusage, purchase, grant, refund, app, adjustment ou expiry.
modelUm identificador de modelo, exato.
from, toTimestamps ISO, inclusivos.
qPalavras na descrição.
formatjson, ou csv para todo o histórico filtrado como um arquivo, com no máximo 5.000 linhas e sem paginação.
CampoSignificado
id, atA linha e quando ela aconteceu.
kind, sourceO que foi. kind: "app" são créditos ganhos com um app publicado ou pagos por ele, e adjustment é a correção de um administrador e todo o resto. source é a palavra do próprio registro, como usage, one_time_purchase, subscription_renewal, signup_grant, refund, app_earnings ou expiry.
amountO movimento, com sinal: a reserva de uma execução é negativa, uma compra é positiva.
balanceAfterO saldo logo depois dele.
poolsubscription, topup ou mixed.
descriptionA observação do registro.
model, providerEm uma linha com tarefa, o modelo que foi executado.
charge, statusSó na linha de reserva de uma tarefa, a reserva feita quando a execução foi aceita. charge é quanto a execução custou no fim: a cobrança liquidada, a reserva enquanto ela está em andamento, ou 0 depois do reembolso. status é reserved, committed ou refunded.
jobEm uma linha com tarefa: { id, type, status, startedAt, completedAt, durationMs, workflowId, sessionId }. type e o resto são null quando a tarefa não existe mais.
receiptUrlO recibo do Stripe, em uma compra que tem um.

Uma linha de reembolso, ou uma linha de excedente medido da mesma tarefa, tem charge: null. Assim, somar charge em uma lista conta cada tarefa uma vez. Leia charge, não amount, para o gasto.

O CSV tem os mesmos campos, uma linha por movimento, com números como números. A última linha diz quando a lista foi cortada em 5.000 linhas. No SDK, é client.credits.history() e client.credits.exportHistory(), e na CLI, nodaro billing history, com --csv para o arquivo.

Em uma implantação em que uma conta de cobrança paga por todos os usuários, o resumo de uso e o histórico só respondem à sessão da própria conta de cobrança, como toda leitura de saldo. Os tokens dela recebem 403 payer_balance_jwt_only.

E-mail de extrato mensal

Uma pessoa que ativa monthlyStatementEmail em GET / PATCH /v1/user/settings recebe um e-mail curto no dia 1º de cada mês, quando fez algum pagamento no mês anterior. Ele vem desativado por padrão. O e-mail lista os documentos de pagamento do mês anterior:

  • O que foi pago, em dólares, descontados os reembolsos.
  • Quantas faturas e quantos recibos houve.
  • Um link para o documento mais recente que tenha um. É o PDF da fatura do Stripe, ou a página do recibo, entre os documentos pagos que GET /v1/billing/invoices lista.
  • O saldo.

Os meses são meses do calendário UTC. Um mês sem pagamento não envia nada.

O e-mail de extrato existe só no Nodaro Cloud, e só onde a implantação tem um e-mail de extrato configurado. Uma implantação sem ele não envia nada.

Configurações do usuário

GET /v1/user/settings retorna as configurações da própria pessoa com login: { data: { tier, publicOutputs, promptTemplates, textTemplates, preferredLocale, mcpPreferences, showRecentNodes, showMostUsedNodes, variableDisplayMode, nodeDoubleClickAction, monthlyStatementEmail } }.

PATCH /v1/user/settings altera os campos que você envia, qualquer um desses campos menos tier, e os retorna como foram salvos.

  • promptTemplates e textTemplates substituem o valor armazenado por inteiro. mcpPreferences é mesclado um eixo de cada vez: image, video, audio e flows. Um campo que você omite mantém o valor armazenado, e um campo enviado como null é apagado, então as ferramentas MCP usam o próprio padrão delas para ele, por exemplo { "mcpPreferences": { "image": { "model": null } } }.
  • publicOutputs: false exige o plano Standard ou superior no Nodaro Cloud. Caso contrário, a resposta é 403.
  • Um valor inválido é 400 validation_error, e um patch sem nada para alterar é 400. Um perfil ausente é 404.

No SDK, é client.userSettings: get() e update(patch).

Calcular o preço de uma execução antes de iniciá-la

FerramentaO que ela precifica
POST /v1/credits/model-costsAté 50 IDs de modelo de uma vez.
GET /v1/credits/model-costUm ID de modelo.
GET /v1/modelsTodos os modelos, com uma entrada pricing por variante. Veja Descobrir modelos.
GET /v1/nodes/:typeO creditCost de um nó: um preço único ou uma faixa.
GET /v1/api/schemaUm workflow inteiro, como estimatedCredits. Veja Workflows.
POST /v1/credits/estimate-workflowUm workflow que você envia como { nodes, edges? }. Responde { data: { totalCredits, … } }.
POST /v1/credits/video-pro-estimateUma execução do Gerar vídeo Pro, sem reservar nada. Veja Tarefas.
POST /v1/credits/seedance-ref-estimateUma execução do Seedance 2, do Kling 4.0 ou do Kling 4.0 Flash com vídeos de referência, medida como a execução. Veja abaixo.
POST /v1/recast/estimateUma execução do Recast. Veja Recast.
POST /v1/pro-3d-render/quoteUma execução da Renderização 3D Pro. Veja Cenas 3D.

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, no Vídeo em loop e no Combinar vídeos, 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 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.

Um total que inclui um nó de LLM medido é uma estimativa. O estimate-workflow então acrescenta estimate: true, e o GET /v1/api/schema acrescenta estimatedCreditsIsEstimate: true. Mostre esse total como ≈N. Ele é a soma das estimativas e dos preços fixos, nunca uma reserva.

Para uma cotação exata de uma etapa cobrada pela duração do clipe, um nó upload-video no corpo do estimate-workflow pode trazer a duration (em segundos) e o fps do clipe no data dele, ao lado da url. A Máscara de vídeo é então cotada pela duração do clipe nessa taxa de quadros, a regra pela qual a execução dela é cobrada. Isso também funciona depois de um Cortar vídeo ou de um Vídeo em loop, e depois de um Combinar vídeos cujos clipes declaram todos a mesma taxa de quadros.

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)

Preços exatos de execuções cobradas por unidade

Algumas execuções são cobradas por unidade, e uma execução é precificada como um todo e arredondada uma única vez. Por isso, o preço da unidade vezes o número de unidades pode dar mais do que a execução custa. Para cotar uma execução assim, peça o identificador <row>:<N>u, o preço exato de N unidades dessa linha. POST /v1/credits/model-costs e GET /v1/credits/model-cost respondem a ele.

ExecuçãoUnidadeID de exemplo
Uma requisição de falaCada 100 caracteres iniciados, de 8 até o limite do modelo por requisiçãoelevenlabs-v4:per-100-chars:12u
Uma renderização do Aplicar EDL ou do Visão de falantesCada minutoapply-edl:4u
Cortar vídeo, Vídeo em loop, Combinar vídeos, Montar vídeo narrado e Composição por máscaraCada 5 segundostrim-video:5u
Uma extensão ou refação do LTX 2.3 ProCada segundo; N pode ser fracionárioltx-2.3-pro-retake:per-second:2.5u
Uma dublagemCada minuto iniciado, de 1 a 30elevenlabs-dubbing:3u, hebraico elevenlabs-dubbing-v2:3u

Uma linha que não é cobrada por unidade, ou um número de unidades que nenhuma execução dela pode ter, vai para missing. Em uma instalação que não cobra a fala pela duração, todo ID <model>:per-100-chars:<N>u também vai para missing. Nesse caso, cote a linha fixa do modelo.

Uma conversão completa do Modificador de voz Pro tem um identificador próprio: voice-changer-pro:<slot>,<slot>,…, com uma posição por voz trocada. Uma posição é sts-<seconds> para uma voz com Conversão, pela duração do stem dela. Uma voz com Releitura é respeak-<characters> na v3, respeak-v4-<characters> na v4 e respeak-v4t-<characters> na v4 falando uma tradução. Para uma tradução, envie os caracteres da transcrição: o servidor soma a margem de uma fala gerada de novo. Use só o tipo quando a medida é desconhecida. Por exemplo, voice-changer-pro:sts-26.76,respeak-v4-1200,respeak-v4t-800. Os dois endpoints respondem a ele com os créditos que a conversão reserva. Os preços por voz não somam esse valor, porque a conversão é cobrada pela soma, arredondada uma única vez. Mais de 8 posições, um stem com mais de uma hora ou uma posição malformada vão para missing. O pacote @nodaro/shared monta o identificador com voiceChangerProQuoteCreditId(slots), em que uma posição de Releitura aceita um engine opcional ("v3" ou "v4") e uma flag translated.

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.

Na CLI, nodaro models cost <id…> calcula o preço dos identificadores da mesma forma, e nodaro models list mostra os níveis de créditos de cada modelo.

Chamadas de LLM

Uma chamada de LLM não tem preço fixo. Ela é cobrada pelos tokens que realmente usou, pela tarifa do modelo na via que a atendeu. Veja Como as chamadas de LLM são cobradas.

  • A chave de preço é <feature>:<model>, mais :direct quando a chamada é executada na própria API do provedor, ou :effort-<level> em um modelo cujo preço depende do Esforço. Exemplos são llm-chat:gemini-3.6-flash e describe-to-picker:claude-opus-5.5:direct. llmPriceKey(feature, model, reasoningEffort?, advancedMode?) de @nodaro/shared/llm-models monta a chave.
  • A resposta é uma estimativa, uma chamada típica daquele recurso com aquele modelo. POST /v1/credits/model-costs lista esses IDs em estimates, e GET /v1/credits/model-cost acrescenta estimate: true ao data dele. Mostre uma estimativa como ≈N. Um lote só com preços fixos não tem o campo estimates.
  • Um modelo sem tarifa na via em que seria atendido não pode ser executado. O lote lista a chave dele em errors, com errorCodes: { "<key>": { code: "llm_model_unpriced", message } }. A própria execução é recusada antes de qualquer reserva. Veja Um modelo ainda sem preço.
  • Uma chave medida em missing significa que o servidor não calcula o preço das chamadas de LLM por modelo. Não mostre preço para ela.
  • Uma coleta do Anúncios da Meta com Análise com IA reserva o preço fixo da coleta mais uma chamada de análise por anúncio. Peça a análise inteira como um único ID, <analysis key>:<items>u. scrapeAnalysisQuoteId de @nodaro/shared/social o monta. A resposta é o valor da execução, arredondado para cima uma vez, então a estimativa de uma chamada vezes os itens pode dar mais.
{
  "data": { "llm-chat:gemini-3.6-flash": <credits>, "nano-banana-pro": <credits> },
  "missing": [],
  "errors": [],
  "estimates": ["llm-chat:gemini-3.6-flash"]
}

Preços na unidade da própria implantação

Em uma implantação que mostra a própria unidade em vez de créditos, POST /v1/credits/model-costs também responde display: { unit, decimals, data }. data associa os mesmos identificadores ao preço deles nessa unidade, convertido pelo servidor, e null significa indisponível. GET /v1/credits/model-cost acrescenta display: { unit, decimals, creditCost } ao seu data. Um identificador listado em estimates é uma estimativa nos dois.

  • Mostre esses números como vieram. Não converta créditos você mesmo.
  • unitLabels. Quando a implantação dá um nome à unidade em cada idioma da interface, display também traz unitLabels: { "<locale id>": "<word>" }. Mostre a entrada do idioma da sua interface, ou então unit. O servidor não sabe qual é o idioma da sua interface, então ele envia os nomes e você escolhe.
  • Nas outras implantações, display não vem, e todos os outros campos ficam iguais.

Cancelamento. Cancelar uma tarefa de LLM medida nunca cobra a reserva inteira. Uma tarefa cuja chamada já começou é cobrada pelo que usou, e o resto é reembolsado. Uma tarefa cancelada antes de a chamada começar é reembolsada, exceto pelo que uma tentativa anterior da mesma tarefa já usou. Um único POST /v1/jobs/:id/cancel de uma tarefa em execução responde inFlight: true e a deixa terminar. Veja Cancelar ou excluir uma tarefa.

Estimativas do Seedance com vídeos de referência

Uma execução do Seedance 2 com vídeos de referência é cobrada pelos segundos dos clipes de referência mais os segundos de saída. Uma execução do Kling 4.0 (kling-4) ou do Kling 4.0 Flash (kling-4-flash) é cobrada pela saída mais o maior valor entre a saída e os clipes. Nos dois casos, o preço depende da duração real dos clipes. Isso vale para o Gerar vídeo com vídeos de referência conectados e para a opção Seedance 2.5 Edit do Vídeo para vídeo, cujo clipe de origem é o vídeo de referência 1. POST /v1/credits/seedance-ref-estimate mede os clipes e calcula o preço exatamente como a reserva da execução faz. A rota não cria tarefa e não reserva nada. Ela exige um token e aceita 60 requisições por minuto.

{ "provider": "seedance-2-5", "resolution": "720p", "duration": 8, "referenceVideoUrls": ["https://example.com/clip.mp4"] }
CampoTipoSignificado
providerstringseedance-2, seedance-2-fast, seedance-2-mini, seedance-2-5, kling-4 ou kling-4-flash. Qualquer outro modelo responde 400 validation_error, com uma mensagem que nomeia os modelos aceitos.
resolutionstring, opcionalComo a execução a envia. Omitido significa o padrão do modelo.
durationnumber, opcionalSegundos de saída. -1 significa Automático, com o preço que a execução reserva: a duração do clipe mais longo arredondada para cima até um segundo inteiro, mais um segundo, nunca acima do clipe mais longo do modelo. Enquanto um clipe não foi medido ou é desconhecido, ou quando referenceTaskType é reference, o Automático tem o preço do clipe mais longo do modelo. Omitido significa o padrão do modelo.
draftboolean, opcionalO Rascunho do Seedance 2.5, com preço de 480p.
referenceTaskTypestring, opcionalSeedance 2.5: o tipo de tarefa de referência que a execução vai enviar, auto (padrão), reference, edit ou extend, decidido como a execução decide. reference com duration Automática tem o preço da saída mais longa do modelo. edit e extend têm o preço da duração com que rodam. Um clipe ainda não criado conta como o clipe mais longo do modelo. Um rascunho é cotado como a mesma solicitação em 480p. Os outros modelos o ignoram, e um valor desconhecido é ignorado.
referenceVideoUrlsstring[]Os clipes de referência que a execução vai enviar, em ordem.
unknownReferenceVideosnumber, opcionalClipes conectados cujo arquivo ainda não existe, porque o nó anterior ainda não os criou.

A resposta é { "data": { "credits", "min", "exact" } }. Com todos os clipes informados, credits é exatamente o que a execução reserva, e min é igual a ele. Um clipe que não pode ser medido conta como o clipe mais longo que o modelo aceita, como a execução o conta. Com unknownReferenceVideos, exact é false: credits calcula cada clipe desconhecido pelo clipe mais longo que o modelo aceita. min é o mínimo que a execução pode reservar, seja qual for a duração dos clipes desconhecidos. Com um referenceTaskType, um clipe mais longo pode tornar a execução mais barata, e min leva isso em conta. Os dois números são reservas: uma execução cuja duração o modelo decide é cobrada pelo que fizer, o que pode ficar abaixo de min. Um clipe que a execução recusaria é recusado aqui com o mesmo 400 video_too_long da execução. O editor mostra a mesma faixa no nó enquanto um clipe conectado ainda não foi criado.

Planos e preços

GET /v1/billing/plans lista os planos e os pacotes de créditos à venda, com o preço de cada um. A rota é pública: nenhum token é exigido, então uma página de preços pode chamá-la antes de alguém entrar, e todos recebem a mesma resposta, enviada com Cache-Control: public, max-age=300. Ela responde a quem o checkout deixa passar. Em uma implantação que não vende para os usuários dela, só a conta de cobrança dela, com login, recebe a lista, com Cache-Control: private, max-age=300, e qualquer outra pessoa recebe 403 self_serve_disabled. Toda resposta traz Vary: Authorization. Ela só responde no Nodaro Cloud. No SDK, é client.billing.plans(), e na CLI, nodaro billing plans, sem precisar de login.

{
  "data": [
    { "id": "free", "name": "Free", "prices": null,
      "signupCredits": <credits>, "parallelism": <n>, "storageBytes": <bytes> },
    { "id": "basic", "name": "Basic",
      "prices": {
        "monthly": { "priceId": "price_…", "amount": <amount>, "currency": "USD",
                     "credits": { "amount": <credits>, "per": "month" } },
        "yearly":  { "priceId": "price_…", "amount": <amount>, "currency": "USD", "perMonth": <amount>,
                     "credits": { "amount": <credits>, "per": "month" } }
      },
      "signupCredits": null, "parallelism": <n>, "storageBytes": <bytes> }
  ],
  "topUps": [
    { "id": "topup-10", "credits": <credits>, "price": { "amount": <amount>, "currency": "USD" }, "priceId": "price_…" }
  ],
  "topUpRange": { "min": <amount>, "max": <amount>, "currency": "USD" },
  "stripePublishableKey": "<key>" | null
}
CampoSignificado
dataOs planos: primeiro o plano gratuito, depois os planos pagos, do menor para o maior. O id é estável: free, basic, standard, pro ou business.
pricesnull no plano gratuito. Nos outros, monthly e yearly: priceId, o ID de preço do Stripe que a finalização de compra e a mudança de plano recebem, amount na unidade principal da moeda, currency como um código ISO 4217, e yearly.perMonth, o valor anual dividido pelos meses. Um preço que não pode ser vendido agora é null: mostre-o como indisponível, nunca como gratuito.
prices.*.creditsO que o preço concede: { amount, per }, em que per é "month" ou "year". Um preço anual concede os créditos do plano todo mês, como um preço mensal. null quando o preço não informa isso.
signupCreditsA concessão única do plano gratuito no cadastro. null em um plano pago, cujos créditos vêm com cada preço.
parallelismQuantos nós de um workflow são executados ao mesmo tempo.
storageBytesO armazenamento para a sua mídia, em bytes.
topUpsOs pacotes de créditos, { id, credits, price, priceId }, do menor para o maior. Os créditos de recarga valem por 12 meses. price é null quando não pode ser informado agora, e priceId, o ID de preço do Stripe para a finalização de compra, é null junto com ele.
topUpRange{ min, max, currency }: qualquer valor inteiro nessa faixa pode ser carregado como créditos no app, com a mesma taxa dos pacotes.
stripePublishableKeyA chave publicável do Stripe para o formulário de pagamento dentro da página, o Checkout incorporado do Stripe. É null quando a implantação não tem uma: envie a pessoa para a página do Checkout. Veja Pagar dentro da sua própria página.
StatusCódigoQuando
403self_serve_disabledA implantação não vende para os usuários dela, e quem chama não é a conta de cobrança dela.
503stripe_not_configuredA implantação não aceita pagamentos com cartão.
503plan_prices_unavailableNão foi possível ler os preços. Tente de novo em instantes.

Para vender um plano, envie o usuário para a página de preços do app do Nodaro, ou inicie uma finalização de compra em um app próprio. Veja Comprar e gerenciar a cobrança.

O seu plano

GET /v1/billing/subscription responde a uma sessão com login, a um token de API pessoal sem limite de workflow ou ao token OAuth de um app. Um token limitado a um workflow recebe 403 forbidden. A resposta é { data, effectiveTier }:

  • data é a assinatura mais recente da conta, ou null quando ela nunca assinou. Contém tier, status (active, trialing, past_due, unpaid (as novas tentativas de pagamento terminaram sem pagamento), paused, canceled, incomplete, incomplete_expired ou expired), current_period_start, current_period_end, cancel_at_period_end, cancel_at e canceled_at.
  • effectiveTier é o nível que os recursos da conta seguem. Normalmente é um id de plano de GET /v1/billing/plans. Também pode ser "payg", para uma conta sem assinatura e com créditos comprados, ou um nível que não está à venda, como "enterprise".

Compare effectiveTier com data[].id da lista de planos para marcar o plano atual. Nenhuma correspondência significa pagamento por uso ou um nível que não está à venda. No SDK, é client.billing.subscription(), e na CLI, nodaro billing subscription.

Comprar e gerenciar a cobrança

As rotas que compram e gerenciam a cobrança só respondem a uma sessão com login feito: o JWT do Supabase que um app web próprio tem. Elas recusam tokens de API e tokens de apps OAuth com 403 forbidden. Uma pessoa gerencia a cobrança em app.nodaro.ai/billing, ou em um app próprio que chama estas rotas pelo client.billing do SDK.

MétodoCaminhoO que faz
POST/v1/billing/create-checkout-sessionAbre o Stripe Checkout para um plano ou um pacote de créditos: { priceId, mode?, embedded?, returnPath?, uiMode?, replacesSessionId?, gaClientId?, gaSessionId? } retorna { data: { url } }. O Checkout de um plano aceita códigos promocionais, e o de um pacote de créditos não. Uma compra de pacote liquidada por zero não concede créditos. A rota responde 409 para um plano enquanto a conta já tem uma assinatura, ativa ou com pagamento em atraso. Mude esse plano com change-plan.
POST/v1/billing/create-load-sessionAbre o Stripe Checkout para carregar um valor inteiro como créditos: { amountUsd, embedded?, returnPath?, uiMode?, replacesSessionId?, gaClientId?, gaSessionId? } retorna { data: { url, credits } }.
GET/v1/billing/checkout-session/:sessionIdO status de uma das suas sessões do Checkout. Veja Pagar dentro da sua própria página.
POST/v1/billing/change-planMove uma assinatura ativa para outro plano: { newPriceId } retorna { data: { subscriptionId, tier } }. Veja Mudar de plano.
POST/v1/billing/manage-subscriptionUm link para o Portal do Cliente do Stripe: { returnPath? } retorna { data: { url } }. Responde 404 antes da primeira compra.
GET/v1/billing/auto-rechargeA configuração da recarga automática: { data: { enabled, thresholdCredits, amountUsd, failureCount, lastAttemptAt, hasSavedCard } }.
PUT/v1/billing/auto-rechargeMuda a configuração: { enabled, thresholdCredits?, amountUsd? }. Para ativar, os dois valores são necessários.
GET/v1/billing/transactionsO histórico de compras, da mais recente para a mais antiga, as últimas 50: { data: [{ id, stripe_transaction_id, type, amount_usd, credits_granted, tier, created_at, receipt_url }] }. type é subscription, topup ou refund, em que credits_granted é negativo.
GET/v1/billing/payment-methodO que está registrado no Stripe: { data: { card, billingDetails } }. card é { brand, last4, expMonth, expYear } ou null, e billingDetails é { name, email, country } ou null. Uma conta que ainda não comprou recebe os dois como null, nunca um erro.
GET/v1/billing/invoicesCada pagamento como um documento, do mais recente para o mais antigo, os últimos 100 de cada origem. Veja abaixo.

Cada documento de GET /v1/billing/invoices é { id, kind, number, at, amount: { amount, currency }, credits, status, description, pdfUrl, url }:

  • kind: "invoice" é um pagamento de assinatura. number, pdfUrl e a url hospedada são do Stripe.
  • kind: "receipt" é um pacote de créditos ou uma recarga, com os credits concedidos e o recibo hospedado como url, sem PDF. Um reembolso é um recibo com status: "refunded", e o amount e os credits dele são negativos.
  • status é paid, open, void, uncollectible ou refunded.
  • Todo documento que o Stripe gera, o PDF da fatura, a página da fatura e o recibo, está em inglês, seja qual for o idioma em que a pessoa pagou.

returnPath, na finalização de compra, na recarga e no portal, é um caminho na origem que fez a chamada, para onde o Stripe manda a pessoa de volta, como /billing ou /settings/credits?tab=history. Assim, um app próprio na própria origem volta para a própria tela. Ele tem uma única / no início, pode ter uma consulta, e não tem host, barra invertida nem #. Qualquer outra coisa responde 400. A finalização de compra e a recarga adicionam checkout=success ou checkout=cancelled à consulta, e returnPath tem prioridade sobre embedded. Sem ele, as páginas /billing e /pricing do próprio app são usadas.

gaClientId e gaSessionId, na finalização de compra e na recarga, são opcionais: os ids de cliente e de sessão do Google Analytics do visitante, lidos dos cookies _ga. Eles ficam guardados no pagamento, para que, quando ele for liquidado, seja informado às métricas do site junto com a visita que o iniciou. Um valor malformado é ignorado, nunca recusado.

Pagar dentro da sua própria página

uiMode, no checkout e no load, é "hosted", o padrão, que abre a página do Checkout do Stripe, ou "embedded". Com "embedded", o formulário do Checkout do Stripe abre dentro da sua própria página, e a resposta é { data: { url: null, clientSecret, sessionId } }, mais credits em um load. Monte o formulário com o Stripe.js, o clientSecret e a stripePublishableKey de GET /v1/billing/plans. Qualquer outro valor de uiMode responde 400.

  • O formulário nunca redireciona. Formas de pagamento que precisam de redirecionamento não são oferecidas, então returnPath e embedded não são usados. Eles ainda são verificados: um returnPath inválido ainda responde 400.
  • Sem formulário nesta implantação. Quando a implantação não tem chave publicável, a resposta é 503 embedded_checkout_unavailable. Use a página do Checkout.
  • A compra é concedida como sempre, quando o Stripe avisa a plataforma que ela foi paga. Leia o status da sessão para saber quando.

GET /v1/billing/checkout-session/:sessionId lê uma das suas sessões do Checkout. A resposta é { data: { status, paymentStatus, mode, granted, paymentUnderWay } }:

CampoSignificado
statusopen, complete ou expired.
paymentStatuspaid, unpaid ou no_payment_required.
modepayment ou subscription.
grantedtrue quando os créditos da compra, ou o plano, estão na conta. Isso costuma acontecer segundos depois do pagamento, e mais tarde para uma forma de pagamento que é liquidada depois. Depois de granted, leia o saldo de novo, porque o granted de um plano pode chegar um instante antes dos créditos dele.
paymentUnderWaytrue quando a sessão está aberta e o pagamento dela foi enviado, então uma substituição seria recusada com 409 checkout_in_progress. false quando nenhum pagamento enviado é visto. Mesmo assim, uma substituição pode ser recusada.

Uma sessão que não é sua, ou não existe, responde 404 checkout_session_not_found. Mais de 60 leituras por minuto respondem 429.

Substituir uma sessão anterior do Checkout

replacesSessionId, no checkout e no load, indica uma sessão do Checkout sua que esta requisição substitui. Por exemplo, a pessoa desiste do formulário incorporado e abre a página do Checkout. Assim, nunca é possível pagar as duas sessões. Antes de criar qualquer coisa, a plataforma lê a sessão anterior:

A sessão anterior estáResposta
Paga, ou sendo paga por uma forma que é liquidada depois409 checkout_already_complete. Não peça de novo.
Em pagamento: o pagamento foi enviado e ainda está sendo confirmado409 checkout_in_progress. Leia o status da sessão e peça de novo quando ele estiver open com paymentUnderWay: false, ou expired.
Aberta e sem pagamento em andamentoEla expira, e a nova sessão é criada.
ExpiradaA nova sessão é criada.
Não é sua, não foi encontrada, ou não é da mesma compra404 checkout_session_not_found, e a sessão anterior fica como está.

A mesma compra é uma sessão de plano para uma requisição de plano, uma sessão do mesmo pacote, ou uma sessão de load do mesmo valor. Uma substituição ainda pode ser recusada depois de uma leitura de status, então peça de novo só quando a pessoa agir, ou espere mais entre as tentativas. Um replacesSessionId que não é texto, está vazio ou tem mais de 255 caracteres responde 400. Sem replacesSessionId, nada muda.

Mudar de plano

POST /v1/billing/change-plan move uma assinatura ativa para outro plano. O que acontece depende da direção:

  • Upgrade. A diferença de preço pelo resto do período de cobrança é cobrada na hora. O novo plano só se aplica quando esse pagamento é aprovado.
  • Créditos em um upgrade. A conta recebe a diferença entre os créditos mensais dos dois planos, uma vez por período de cobrança. Descer e subir de novo dentro de um mesmo período não acrescenta mais nada. Uma fatura de upgrade liquidada por 0, por exemplo com um cupom de 100% de desconto ou com um saldo que a cobriu, não acrescenta créditos.
  • Um pagamento de upgrade que não é aprovado. O plano continua como estava, e a resposta é 409 com { error: { code: "plan_change_payment_required", message, invoiceUrl } }. invoiceUrl é a página do Stripe para pagar essa fatura. A mudança se aplica se a fatura for paga antes de expirar. A mesma resposta volta enquanto uma mudança anterior ainda espera o pagamento.
  • Downgrade. O tempo não usado é creditado na próxima fatura. Os créditos atuais ficam até o fim do período.
  • De mensal para anual, ou de anual para mensal. A troca reinicia o período de cobrança, mas não acrescenta créditos. Os próximos créditos mensais chegam um mês depois da troca.

Outras respostas:

  • 409 quando a assinatura não está ativa, por exemplo depois de um pagamento de renovação recusado.
  • 404 quando a conta não tem assinatura.
  • 429 depois de 5 pedidos de mudança de plano de uma mesma conta em 24 horas. Os pedidos recusados também contam.

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. As tarefas criadas pelo MCP são sempre privadas.
  • 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. A limpeza remove só os arquivos que uma geração armazenou como o próprio resultado, nunca uma entrada que o resultado repete, e nunca um arquivo que um item da sua biblioteca ainda guarda. Quando um arquivo é removido, o link dele passa a null em todos os resultados de tarefas que o guardam.

As compras exigem a sessão da própria pessoa, com login feito: as rotas de cobrança de finalização de compra, recargas, mudanças de plano, recarga automática, histórico de compras, faturas e portal de pagamento recusam tokens de API e tokens OAuth. Gerencie a cobrança em app.nodaro.ai/billing, ou veja Comprar e gerenciar a cobrança.

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:

CampoSignificado
planO seu plano, como string. unknown é uma resposta válida.
balanceO seu saldo, ou null.
dailyAllowanceO seu limite de uso diário, ou null.
unitA 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 tarefas. 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 as tarefas que não conseguiu precificar. Um total null significa que nenhuma tarefa 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. Ela também pode ativar a recarga automática do saldo pré-pago e criar chaves de integração de cobrança somente leitura. Veja As ferramentas da conta de cobrança.
    • O plano ali é o da implantação. Nas leituras de saldo, nas configurações do usuário e em GET /v1/billing/subscription, tier e effectiveTier são o plano da implantação, o nível da conta de cobrança. dailyLimit é null, porque nenhum limite diário se aplica. GET /v1/billing/subscription continua respondendo a sua própria assinatura em data, normalmente null.
    • Os créditos gratuitos de cadastro não valem ali. POST /v1/credits/claim-signup-grant e as duas rotas da oferta de boas-vindas respondem 409 not_applicable e não registram nada, nem o consentimento. GET /v1/user/credits não traz welcomeOffer.
  • Carteira externa. Veja Carteiras externas para as implantações que autorizam gastos pela própria carteira.

Perguntas frequentes

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 a tarefa começa e cobrados quando ela entrega o resultado. Quando uma tarefa é bloqueada por um filtro de segurança ou por uma política, ou é cancelada antes de ser executada, a reserva é reembolsada. O credit_status da tarefa 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.

Por que um preço de LLM aparece como ≈N?

Uma chamada de LLM é cobrada pelos tokens que realmente usou, pela tarifa do modelo. Antes da chamada, o Nodaro só consegue estimar uma chamada típica com aquele modelo. POST /v1/credits/model-costs lista esses IDs em estimates, então mostre-os como ≈N.

Posso mostrar os planos e preços do Nodaro na minha própria página de preços?

Sim. GET /v1/billing/plans é público e não exige token. Ele lista os planos, os preços mensais e anuais deles, os créditos que cada um concede e os pacotes de créditos. A compra exige a sessão da própria pessoa, com login feito.

Os endpoints de créditos funcionam em uma instalação auto-hospedada?

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.

Última atualização

Nesta página