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é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. |
GET | /v1/credits/usage-summary | O seu uso de créditos em um período, somado para uma tela de cobrança. |
GET | /v1/credits/history | Cada movimento do seu saldo, em páginas ou como um arquivo CSV. |
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. Veja Tarefas. |
POST | /v1/credits/seedance-ref-estimate | O 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/plans | Pública. Os planos e os pacotes de créditos à venda, com os preços. |
GET | /v1/billing/subscription | A sua própria assinatura e o nível que a sua conta segue. |
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. |
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-summary | Os 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:
| 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 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_creditscomrequirede, 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 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. |
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"
}| Campo | Significado |
|---|---|
credits_charged | Quanto 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_reserved | A reserva feita quando a execução foi aceita. Ela nunca muda. |
credits_used | A 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, 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. |
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 }.
| Consulta | Significado |
|---|---|
from, to | Um 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. |
bucket | day, week ou month, para a série ao longo do tempo. O padrão é day. |
| Campo | Significado |
|---|---|
period | { from, to, bucket }, como o servidor os recebeu. |
totals | { used, purchased, granted, refunded, runs, avgPerRun }. Veja abaixo. |
mostUsed | A primeira linha de byModel, ou null sem execuções. |
byModel | Linhas { model, provider, credits, runs, share }, por gasto. share é a parte de used, de 0 a 1. |
byCategory | Linhas { category, credits, runs }, em que category é image, video, audio ou other. |
overTime | Uma 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, byWorkflow | Linhas { 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. |
truncated | true 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. |
partial | true 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.
| Consulta | Significado |
|---|---|
limit | De 1 a 100. O padrão é 50. |
cursor | O nextCursor da página anterior. É opaco: qualquer outro texto responde 400. |
kind | usage, purchase, grant, refund, app, adjustment ou expiry. |
model | Um identificador de modelo, exato. |
from, to | Timestamps ISO, inclusivos. |
q | Palavras na descrição. |
format | json, ou csv para todo o histórico filtrado como um arquivo, com no máximo 5.000 linhas e sem paginação. |
| Campo | Significado |
|---|---|
id, at | A linha e quando ela aconteceu. |
kind, source | O 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. |
amount | O movimento, com sinal: a reserva de uma execução é negativa, uma compra é positiva. |
balanceAfter | O saldo logo depois dele. |
pool | subscription, topup ou mixed. |
description | A observação do registro. |
model, provider | Em uma linha com tarefa, o modelo que foi executado. |
charge, status | Só 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. |
job | Em 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. |
receiptUrl | O 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/invoiceslista. - 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.
promptTemplatesetextTemplatessubstituem o valor armazenado por inteiro.mcpPreferencesé mesclado um eixo de cada vez:image,video,audioeflows. Um campo que você omite mantém o valor armazenado, e um campo enviado comonullé apagado, então as ferramentas MCP usam o próprio padrão delas para ele, por exemplo{ "mcpPreferences": { "image": { "model": null } } }.publicOutputs: falseexige 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
| 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. |
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. |
POST /v1/credits/estimate-workflow | Um workflow que você envia como { nodes, edges? }. Responde { data: { totalCredits, … } }. |
POST /v1/credits/video-pro-estimate | Uma execução do Gerar vídeo Pro, sem reservar nada. Veja Tarefas. |
POST /v1/credits/seedance-ref-estimate | Uma 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/estimate | Uma execução do Recast. Veja Recast. |
POST /v1/pro-3d-render/quote | Uma 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ção | Unidade | ID de exemplo |
|---|---|---|
| Uma requisição de fala | Cada 100 caracteres iniciados, de 8 até o limite do modelo por requisição | elevenlabs-v4:per-100-chars:12u |
| Uma renderização do Aplicar EDL ou do Visão de falantes | Cada minuto | apply-edl:4u |
| Cortar vídeo, Vídeo em loop, Combinar vídeos, Montar vídeo narrado e Composição por máscara | Cada 5 segundos | trim-video:5u |
| Uma extensão ou refação do LTX 2.3 Pro | Cada segundo; N pode ser fracionário | ltx-2.3-pro-retake:per-second:2.5u |
| Uma dublagem | Cada minuto iniciado, de 1 a 30 | elevenlabs-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:directquando a chamada é executada na própria API do provedor, ou:effort-<level>em um modelo cujo preço depende do Esforço. Exemplos sãollm-chat:gemini-3.6-flashedescribe-to-picker:claude-opus-5.5:direct.llmPriceKey(feature, model, reasoningEffort?, advancedMode?)de@nodaro/shared/llm-modelsmonta a chave. - A resposta é uma estimativa, uma chamada típica daquele recurso com aquele modelo.
POST /v1/credits/model-costslista esses IDs emestimates, eGET /v1/credits/model-costacrescentaestimate: trueaodatadele. Mostre uma estimativa como≈N. Um lote só com preços fixos não tem o campoestimates. - Um modelo sem tarifa na via em que seria atendido não pode ser executado. O lote lista a chave dele em
errors, comerrorCodes: { "<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
missingsignifica 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.scrapeAnalysisQuoteIdde@nodaro/shared/socialo 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,displaytambém trazunitLabels: { "<locale id>": "<word>" }. Mostre a entrada do idioma da sua interface, ou entãounit. O servidor não sabe qual é o idioma da sua interface, então ele envia os nomes e você escolhe.- Nas outras implantações,
displaynã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"] }| Campo | Tipo | Significado |
|---|---|---|
provider | string | seedance-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. |
resolution | string, opcional | Como a execução a envia. Omitido significa o padrão do modelo. |
duration | number, opcional | Segundos 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. |
draft | boolean, opcional | O Rascunho do Seedance 2.5, com preço de 480p. |
referenceTaskType | string, opcional | Seedance 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. |
referenceVideoUrls | string[] | Os clipes de referência que a execução vai enviar, em ordem. |
unknownReferenceVideos | number, opcional | Clipes 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
}| Campo | Significado |
|---|---|
data | Os planos: primeiro o plano gratuito, depois os planos pagos, do menor para o maior. O id é estável: free, basic, standard, pro ou business. |
prices | null 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.*.credits | O 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. |
signupCredits | A concessão única do plano gratuito no cadastro. null em um plano pago, cujos créditos vêm com cada preço. |
parallelism | Quantos nós de um workflow são executados ao mesmo tempo. |
storageBytes | O armazenamento para a sua mídia, em bytes. |
topUps | Os 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. |
stripePublishableKey | A 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. |
| Status | Código | Quando |
|---|---|---|
403 | self_serve_disabled | A implantação não vende para os usuários dela, e quem chama não é a conta de cobrança dela. |
503 | stripe_not_configured | A implantação não aceita pagamentos com cartão. |
503 | plan_prices_unavailable | Nã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, ounullquando ela nunca assinou. Contémtier,status(active,trialing,past_due,unpaid(as novas tentativas de pagamento terminaram sem pagamento),paused,canceled,incomplete,incomplete_expiredouexpired),current_period_start,current_period_end,cancel_at_period_end,cancel_atecanceled_at.effectiveTieré o nível que os recursos da conta seguem. Normalmente é umidde plano deGET /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étodo | Caminho | O que faz |
|---|---|---|
POST | /v1/billing/create-checkout-session | Abre 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-session | Abre 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/:sessionId | O status de uma das suas sessões do Checkout. Veja Pagar dentro da sua própria página. |
POST | /v1/billing/change-plan | Move uma assinatura ativa para outro plano: { newPriceId } retorna { data: { subscriptionId, tier } }. Veja Mudar de plano. |
POST | /v1/billing/manage-subscription | Um link para o Portal do Cliente do Stripe: { returnPath? } retorna { data: { url } }. Responde 404 antes da primeira compra. |
GET | /v1/billing/auto-recharge | A configuração da recarga automática: { data: { enabled, thresholdCredits, amountUsd, failureCount, lastAttemptAt, hasSavedCard } }. |
PUT | /v1/billing/auto-recharge | Muda a configuração: { enabled, thresholdCredits?, amountUsd? }. Para ativar, os dois valores são necessários. |
GET | /v1/billing/transactions | O 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-method | O 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/invoices | Cada 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,pdfUrle aurlhospedada são do Stripe.kind: "receipt"é um pacote de créditos ou uma recarga, com oscreditsconcedidos e o recibo hospedado comourl, sem PDF. Um reembolso é um recibo comstatus: "refunded", e oamounte oscreditsdele são negativos.statusépaid,open,void,uncollectibleourefunded.- 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
returnPatheembeddednão são usados. Eles ainda são verificados: umreturnPathinválido ainda responde400. - 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 } }:
| Campo | Significado |
|---|---|
status | open, complete ou expired. |
paymentStatus | paid, unpaid ou no_payment_required. |
mode | payment ou subscription. |
granted | true 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. |
paymentUnderWay | true 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 depois | 409 checkout_already_complete. Não peça de novo. |
| Em pagamento: o pagamento foi enviado e ainda está sendo confirmado | 409 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 andamento | Ela expira, e a nova sessão é criada. |
| Expirada | A nova sessão é criada. |
| Não é sua, não foi encontrada, ou não é da mesma compra | 404 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 é
409com{ 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:
409quando a assinatura não está ativa, por exemplo depois de um pagamento de renovação recusado.404quando a conta não tem assinatura.429depois 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.
effectiveTierpassa a serpayg: 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
nullem 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, comocreditsouusd.- Em uma instalação da Community Edition sem créditos,
providerIdénoneemountCostTabéfalse: não mostre nenhuma visão de custo. deploymentPayerétruequando 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 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 responde402 budget_exceeded, e uma execução acima do seu próprio limite nesse espaço de trabalho responde402 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/creditsadicionaallowance: { granted, remaining, enforced }, o seu próprio limite de uso em créditos.enforced: falsesignifica que o limite aparece, mas não bloqueia execuções.allowanceénullpara a própria conta de cobrança ou quando não pôde ser lido, então nunca interpretenullcomo zero. Quando a implantação aplica os limites de uso, uma execução acima do seu limite responde402 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 respondem403 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,tiereeffectiveTiersã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/subscriptioncontinua respondendo a sua própria assinatura emdata, normalmentenull. - Os créditos gratuitos de cadastro não valem ali.
POST /v1/credits/claim-signup-grante as duas rotas da oferta de boas-vindas respondem409 not_applicablee não registram nada, nem o consentimento.GET /v1/user/creditsnão trazwelcomeOffer.
- O plano ali é o da implantação. Nas leituras de saldo, nas configurações do usuário e em
- 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.
Páginas relacionadas
Créditos
Tarefas
Erros
Espaços de trabalho e organizações
Modelos de IA no Nodaro
Última atualização
Espaços de trabalho e organizações
Atue no espaço de trabalho de uma organização pela API do Nodaro (X-Nodaro-Workspace), vincule tokens e gerencie membros, convites, compartilhamento e uso.
Erros
Todo erro da API do Nodaro tem status HTTP e código estável em um envelope. Veja o que cada código significa, quais repetir e como tarefas relatam falhas.