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

Modelos e créditos

Liste os modelos de IA de uma instância do Nodaro, consulte seu saldo de créditos, veja o preço de um modelo antes de executá-lo e leia planos e sua assinatura.

client.models retorna o catálogo de modelos de IA que uma instância do Nodaro oferece, e client.credits retorna seu saldo de créditos e o preço de qualquer modelo. client.billing retorna os planos à venda e a sua assinatura. Use os dois juntos para mostrar aos usuários quais modelos eles podem escolher e quanto custa cada execução. Os métodos chamam os mesmos endpoints da API REST de créditos. Preços e saldos existem no Nodaro Cloud; as instalações auto-hospedadas Community e Business não têm sistema de créditos. Veja Créditos.

Métodos

MétodoO que faz
models.list(opts?)Lista os modelos, agrupados por tipo e por fabricante
credits.balance()Lê seu saldo de créditos e seu nível
credits.modelCosts(ids)Consulta o preço em créditos de até 50 modelos ou variações
credits.transactions(options?)Lê as suas transações de créditos, uma página por vez
credits.usageSummary(options?)Soma o seu uso de créditos em um período, para uma tela de cobrança
credits.history(options?)Lê cada movimento do seu saldo, uma página por vez
credits.exportHistory(filters?)Exporta todo o histórico filtrado em CSV
credits.claimWelcomeOffer(input?)Aceita a oferta de boas-vindas em um app web próprio do Nodaro
credits.markWelcomeOfferSeen()Informa que o popup de boas-vindas abriu sozinho, ou que o usuário respondeu Talvez depois
billing.plans() e outrosLê os planos e os pacotes de créditos à venda, a sua assinatura e como a implantação cobra. Em um app próprio, também as compras, as faturas, o cartão, a recarga automática e a finalização de compra

client.models

models.list(opts?)

Retorna o catálogo de modelos (GET /v1/models), agrupado por tipo (imagem, vídeo, áudio) e por fabricante. Cada modelo traz seus recursos, seus preços em créditos no Nodaro Cloud e dicas curtas de prompt. O endpoint é público, e o servidor guarda a resposta em cache por 5 minutos. A ferramenta list_models do MCP retorna os mesmos dados.

list(opts?: {
  kind?: "image" | "video" | "audio"
  mode?: string
  family?: string
  featuredOnly?: boolean
}): Promise<ModelsListResult>

Propriedade

Tipo

const catalog = await client.models.list({ kind: "video", mode: "i2v" })

for (const section of catalog.sections) {
  for (const family of section.families) {
    for (const model of family.models) {
      console.log(family.family, model.id, model.durations, model.pricing?.[0]?.credits)
    }
  }
}

O resultado tem sections, uma por tipo, cada uma com families de modelos; recommendations, listas de IDs de modelos para tarefas comuns; e totalModels. Cada modelo tem estes campos:

CampoTipoDescrição
idstringO ID do modelo, para o parâmetro provider de uma execução de nó.
label, descriptionstringO nome de exibição e uma descrição curta.
modesstring[]O que o modelo faz, como t2i, i2i, t2v ou i2v.
useCasesstring[]As tarefas para as quais o modelo é indicado.
aspectRatios, resolutions, qualities, durationsarraysOs valores que o modelo aceita, quando se aplicam.
featuresstring[]Recursos extras.
pricing{ identifier, credits, note? }[]O preço em créditos de cada variação: o preço cobrado por uma execução, o mesmo número do botão Executar. Apenas no Nodaro Cloud.
featuredbooleanSe o modelo está em destaque.
promptTipsstring[]Dicas curtas de prompt para o modelo.
doctrineCoveredbooleantrue apenas quando o Nodaro obteve orientações de prompt para a família do modelo. Mostre um selo de “orientação do fabricante” apenas quando o valor for true.
maker{ id, name }A empresa que criou o modelo. id é estável, um por empresa, como "google" ou "black-forest-labs", então você pode usá-lo como chave para os seus próprios recursos visuais. Um servidor mais novo pode acrescentar fabricantes, então trate um id que você não conhece. O fabricante nem sempre é a family em que o modelo está agrupado. Um modelo que a instância oferece com a própria marca não tem maker.
logoUrlstring | nullA marca oficial do fabricante, um SVG na própria CDN de mídia da instância. null quando a instância não publica nenhuma marca para esse fabricante: mostre o nome ou a inicial do fabricante no lugar. Ele também é null para um modelo que a instância oferece com a própria marca. Use o endereço como foi informado, porque uma marca substituída chega com um novo endereço. A ferramenta MCP o omite.

Um servidor mais antigo omite maker e logoUrl.

defaultDuration é a duração que um duration não definido renderiza e cobra. autoDuration indica que duration: -1 deixa o modelo escolher a duração. referenceTaskTypes lista os valores que referenceTaskType aceita nesse modelo: ["reference", "edit", "extend"] no seedance-2-5, e ausente nos outros.

Regras de tamanho e formatos de arquivo

Um modelo cujos tamanhos dependem da proporção ou do fundo, ou que declara o próprio tamanho padrão, traz estes campos. Todos os outros modelos os omitem, e um servidor mais antigo também.

CampoTipoDescrição
defaultResolutionstringO tamanho em que cai uma requisição que não indica resolution, escrito como em resolutions, quando o modelo declara um: 1K no FLUX 3 Klein, 2K no Seedream 5.5 e no MiniMax H3 Image, 720p no PixVerse V6 Max. Leia este campo em vez de supor que a primeira entrada de resolutions é o padrão.
resolutionsByAspectRatioRecord<string, string[]>As proporções em que o modelo renderiza menos tamanhos que resolutions, cada uma com os tamanhos que renderiza nela. Uma proporção fora da lista renderiza todos os tamanhos de resolutions. Uma requisição de um tamanho que a proporção não renderiza é executada, e cobrada, no maior tamanho que a proporção renderiza até ele. adjustments informa a mudança.
transparentResolutionstringO único tamanho em que um fundo transparente é renderizado. Uma requisição transparente em outro tamanho é executada, e cobrada, neste.
backgroundOnlyAtTransparentResolutiontrueO modelo aceita a configuração de fundo só em transparentResolution. Em qualquer outro tamanho nenhuma é enviada, então opaque é renderizado como auto.

O GPT Image 2.5 (gpt-image-2-5-flare, gpt-image-2-5-sunburst e os modelos de edição -i2i deles) renderiza só 1K em 27:16, 16:27, 9:8 e 8:9. Ele renderiza um fundo transparente só em 1K e aceita a configuração de fundo só nesse tamanho. O GPT Image 2.6 Flare e o Sunburst também renderizam um fundo transparente só em 1K.

Um modelo que grava mais de um tipo de arquivo traz outputFormats, com o padrão primeiro. Quando grava GIF ou SVG, traz também gifFrameSize (512), gifFrames ({ min, max, default, values? }), gifFrameDurationMs ({ min, max, step, default }) e svgLevels. Veja Formatos de arquivo de imagem.

const { sections } = await client.models.list({ kind: "image" })
const m = sections.flatMap((s) => s.families.flatMap((f) => f.models)).find((x) => x.id === "gpt-image-2-5-flare")!
// The sizes to offer at the chosen ratio:
const sizesAt = (ratio: string) => m.resolutionsByAspectRatio?.[ratio] ?? m.resolutions ?? []
sizesAt("27:16") // ["1K"]
sizesAt("16:9")  // ["1K", "2K", "4K"]

Para desenhar as marcas dos fabricantes sem o catálogo, chame GET /v1/model-makers. A rota responde { makers: [{ id, name, logoUrl }] }, com todos os fabricantes que a plataforma conhece, e os mesmos campos do catálogo. Ela é pública e fica em cache por 5 minutos. Veja Descobrir modelos.

for (const section of catalog.sections)
  for (const family of section.families)
    for (const m of family.models)
      console.log(m.id, m.maker?.name ?? family.family, m.logoUrl ?? "(no mark)")

O mesmo catálogo está nas páginas de Modelos. Para saber qual modelo usar, leia Como escolher um modelo.

client.credits

credits.balance()

Retorna seu saldo de créditos e seu nível (GET /v1/user/credits). Lança UnauthorizedError quando não há nenhum usuário conectado.

balance(): Promise<UserBalance>
const balance = await client.credits.balance()
console.log(`${balance.total} credits (${balance.effectiveTier})`)
CampoTipoDescrição
totalnumberOs créditos que você pode gastar agora.
subscriptionnumberOs créditos da assinatura que restam neste mês. Eles voltam a monthlyAllocation todo mês, também em um plano anual, e os não usados não se acumulam.
topupnumberOs créditos que você comprou à parte.
dailySpentnumberOs créditos gastos hoje.
dailyLimitnumber | nullO limite diário de gastos, ou null quando não há limite.
monthlyAllocationnumberOs créditos que o plano concede todo mês, tanto na cobrança mensal quanto na anual.
tierstringO nível de assinatura armazenado, como "free" ou "pro".
effectiveTierstringO nível realmente aplicado. "payg" significa pagamento conforme o uso: sem assinatura, mas com créditos comprados, com todos os modelos, sem marca d'água e sem limite diário.
featuresRecord<string, unknown>Os recursos do nível.
periodEndstring | nullO fim do período de cobrança atual, como data ISO 8601. Em um plano anual, fica a um ano de distância, mas os créditos da assinatura continuam voltando todo mês.
appCreditsAllowancenumberOs créditos ganhos com a execução de apps, no nível gratuito.
freeGrantStateFreeGrantStateA situação do bônus gratuito de cadastro: "unclaimed", "granted", "withheld" ou "revoked". "withheld" significa que a conta funciona, mas o bônus não foi concedido, então mostre o caminho de ativação. Ausente onde a implantação não tem bônus de cadastro.
freeGrantNotice"browser_unmeasured"Só com "withheld", quando o resgate não mostrou nenhum sinal de navegador. O seu app pode dizer que os créditos gratuitos precisam de um navegador comum e de um recarregamento da página.
welcomeOfferWelcomeOfferStatePresente só enquanto a implantação estiver com a oferta de boas-vindas ligada. Ausente significa sem popup, sem banner e sem bloqueio. Veja claimWelcomeOffer().
externalWallet{ available: number | null }Presente quando a implantação usa uma carteira externa compartilhada. null significa que o valor não está disponível. Não mostre total no lugar dele. Veja Carteiras externas.
allowanceBalanceAllowance | nullSó em uma implantação em que uma conta de cobrança paga por todos os usuários: { granted, remaining, enforced }, a sua própria cota em créditos. Mostre-a ali, porque total é o seu saldo pessoal, que não paga execuções em uma implantação assim. enforced: false significa que ela é mostrada, não aplicada. null para a própria conta de cobrança ou quando não pôde ser lida, nunca 0.
displayBalanceDisplayEm uma implantação que mostra a própria unidade em vez de créditos: os mesmos números, convertidos pelo servidor. Ausente quando não há unidade configurada.

Prefira effectiveTier a tier quando decidir o que mostrar. Em uma implantação em que uma conta de cobrança paga por todos os usuários, tier e effectiveTier são o plano da implantação, o nível da conta de cobrança.

BalanceDisplay contém unit (o rótulo da unidade), decimals (as casas decimais dos números, de 0 a 4) e então total, subscription, topup, dailySpent, dailyLimit, monthlyAllocation e appCreditsAllowance nessa unidade. Cada um é number | null, em que null significa indisponível: mostre um travessão, nunca 0. Ele acrescenta allowance: { granted, remaining } | null, externalWallet: { available } e welcomeOffer: { credits }, cada um presente exatamente quando a chave original está. Quando a implantação dá um nome à unidade em cada idioma da interface, ele também traz unitLabels (id de localidade para nome): mostre unitLabels[locale] ?? unit. Mostre esses números como vieram e nunca converta créditos você mesmo. display não vem na leitura da própria conta de cobrança em uma implantação com uma só conta de cobrança, porque o saldo dela é o conjunto de créditos da implantação, mantido em créditos.

credits.modelCosts(ids)

Consulta o preço em créditos de modelos e das variações deles em uma única chamada (POST /v1/credits/model-costs). Verifica no máximo os 50 primeiros identificadores.

modelCosts(ids: string[]): Promise<{
  data: Record<string, number>
  missing: string[]
  errors: string[]
  estimates?: string[]
  errorCodes?: Record<string, { code: string; message: string }>
  display?: ModelCostsDisplay
}>

Propriedade

Tipo

const { data, missing } = await client.credits.modelCosts([
  "nano-banana-pro",
  "nano-banana-pro:4K",
  "seedance-2-fast:8s:720p",
])
console.log(data["nano-banana-pro:4K"])
if (missing.length) console.warn("No price for:", missing)
  • data associa cada identificador que tem preço ao seu preço em créditos.
  • missing lista os identificadores que não têm preço. Mostre um traço para eles.
  • errors lista os identificadores cuja consulta falhou. Os outros preços chegam mesmo assim.
  • estimates lista os identificadores em data cujo valor é uma estimativa, e não um preço fixo. São chaves de preço de LLM medidas. Mostre-os como ≈N. O campo não aparece quando não há nenhum.
  • errorCodes diz por que cada identificador em errors não tem preço. Hoje o código é llm_model_unpriced: um modelo sem tarifa na via em que seria atendido, que não pode ser executado. O campo não aparece quando errors está vazio.
  • display vem em uma implantação que mostra a própria unidade em vez de créditos: { unit, decimals, data }, em que data associa os mesmos identificadores ao preço deles nessa unidade, convertido pelo servidor (null significa indisponível). Um identificador em estimates também é uma estimativa aqui. Mostre unitLabels[locale] ?? unit como nome da unidade quando unitLabels estiver presente. GET /v1/credits/model-cost acrescenta display: { unit, decimals, creditCost } ali. Veja Preços na unidade da própria implantação.

Os identificadores de cada modelo estão no campo pricing de models.list() e na página de cada modelo. Configurações como qualidade, resolução e duração mudam o preço, então informe a variação que a execução vai usar. O preço é verificado de novo quando a execução começa, então esta chamada é uma prévia.

Os modelos de fala têm o preço definido pelo tamanho do texto. O identificador deles para cada bloco iniciado de 100 caracteres é <model>:per-100-chars, por exemplo elevenlabs-v4:per-100-chars. Ele cai em missing em uma instalação que não cobra a fala pelo tamanho, então a resposta também mostra por qual regra o servidor cobra.

Uma requisição é precificada como um todo e arredondada uma única vez. Por isso, o preço exato de uma requisição de N blocos iniciados é o identificador <model>:per-100-chars:<N>u, com N de 8 até o limite do modelo por requisição. N vezes o preço do bloco pode dar mais. O mesmo formato de ID precifica toda execução cobrada por unidade: <row>:<N>u é o preço exato de N unidades dessa linha, por exemplo apply-edl:4u, trim-video:5u, ltx-2.3-pro-retake:per-second:2.5u ou elevenlabs-dubbing:3u. Uma conversão completa do Modificador de voz Pro é voice-changer-pro:<slot>,<slot>,…, que voiceChangerProQuoteCreditId(slots) do @nodaro/shared monta. Veja Preços exatos de execuções cobradas por unidade. 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. A chave de preço dela é <feature>:<model>, mais :direct na própria API do provedor, ou :effort-<level> em um modelo cujo preço depende do Esforço, e llmPriceKey de @nodaro/shared/llm-models a monta. A resposta é uma estimativa de uma chamada típica:

import { llmPriceKey } from "@nodaro/shared/llm-models"

const key = llmPriceKey("llm-chat", "claude-fable-5") // "llm-chat:claude-fable-5"
const { data, estimates } = await client.credits.modelCosts([key])
const shown = estimates?.includes(key) ? `~${data[key]}` : String(data[key])

Uma chave medida em missing significa que o servidor não calcula o preço das chamadas de LLM por modelo, então não mostre preço para ela. GET /v1/credits/model-cost?model=<id> responde um identificador como { model, creditCost, estimate?: true, display? }. Veja Chamadas de LLM e Como as chamadas de LLM são cobradas.

credits.transactions(options?)

Retorna uma página das suas transações de créditos, das mais recentes para as mais antigas (GET /v1/credits/transactions). Só na edição Cloud: uma instalação auto-hospedada responde 404.

transactions(options?: { limit?: number; cursor?: string }): Promise<CreditTransactionsPage>

Propriedade

Tipo

A página é { data: CreditTransaction[], nextCursor }. nextCursor é null quando não há mais linhas.

CampoTipoDescrição
idstringO ID da transação.
created_atstringUma data ISO 8601.
credits_chargednumber | nullO custo da execução depois de liquidada. Pode ser menor que a reserva, é 0 quando a reserva foi reembolsada e é null enquanto a reserva ainda está aberta.
credits_reservednumber | nullA reserva feita quando a execução foi aceita. Ela nunca muda.
credits_usednumber | nullA mesma reserva com o nome original, mantida para as integrações existentes. Prefira credits_charged.
actionstring | nullO modelo ou a operação a que os créditos se referem.
statusstring | null"reserved", "committed" ou "refunded".
metadataRecord<string, unknown>Os detalhes de cobrança da própria execução.
payer"user" | "workspace""workspace" significa que pagou o orçamento de uma turma ou de uma equipe, não o seu saldo.
workspaceIdstring | nullO espaço de trabalho que pagou, quando payer é "workspace".

Qual valor ler. Uma execução primeiro reserva créditos e depois é liquidada: ela é cobrada por toda a reserva ou por parte dela, e o restante volta para o seu saldo. Some credits_charged para saber o seu gasto. Veja Créditos.

let cursor: string | undefined
let spent = 0
do {
  const page = await client.credits.transactions({ limit: 50, cursor })
  for (const t of page.data) spent += t.credits_charged ?? 0
  cursor = page.nextCursor ?? undefined
} while (cursor)
console.log(`${spent} credits charged`)

credits.usageSummary(options?)

Retorna o uso de créditos de um período, somado da forma como uma tela de cobrança o mostra (GET /v1/credits/usage-summary). Ele conta só o seu dinheiro pessoal: uma execução que um espaço de trabalho pagou não entra. Só no Nodaro Cloud.

usageSummary(options?: { from?: string; to?: string; bucket?: "day" | "week" | "month" }): Promise<UsageSummary>

Propriedade

Tipo

Em uma implantação em que uma conta de cobrança paga por todos os usuários, só a sessão da própria conta de cobrança pode chamá-lo. Os tokens dela recebem ForbiddenError com o código payer_balance_jwt_only.

CampoTipoDescrição
period{ from, to, bucket }O período como o servidor o recebeu.
totalsUsageSummaryTotals{ used, purchased, granted, refunded, runs, avgPerRun }. Veja abaixo.
mostUsedUsageByModel | nullO modelo com o maior gasto, ou null sem execuções.
byModelUsageByModel[]{ model, provider, credits, runs, share }, por gasto. share é a parte de used, de 0 a 1.
byCategoryUsageByCategory[]{ category, credits, runs }, em que category é "image", "video", "audio" ou "other".
overTimeUsageOverTime[]Uma linha por intervalo, 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, byWorkflowUsageByGroup[]Quanto cada sessão ou workflow custou, por gasto: { id, name, tool, credits, runs, models, lastAt }. name é null quando a sessão ou o workflow não tem nome ou não existe mais. tool só aparece em uma sessão.
truncatedbooleantrue 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.
partialbooleantrue 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. avgPerRun é used dividido por runs, com uma casa decimal.
const s = await client.credits.usageSummary({ bucket: "week" })
console.log(s.totals.used, "credits used;", s.mostUsed?.model, "most used")
for (const w of s.overTime) console.log(w.bucket, w.used)

credits.history(options?)

Retorna uma página com cada movimento do seu saldo, do mais recente para o mais antigo (GET /v1/credits/history): execuções, compras, concessões, reembolsos, ajustes e expirações, cada um com o saldo depois dele. transactions() lista só as execuções, enquanto history() é o extrato completo que uma tela de cobrança mostra. Só no Nodaro Cloud, com a mesma regra de usageSummary() em uma implantação com uma única conta de cobrança.

history(options?: CreditHistoryOptions): Promise<CreditHistoryPage>

Propriedade

Tipo

A página é { data: CreditHistoryEntry[], nextCursor }. nextCursor é null no fim.

CampoTipoDescrição
idstringO id da linha.
atstringQuando aconteceu, como uma data ISO 8601.
kindCreditHistoryKindO que foi. "app" são créditos ganhos com um app publicado ou pagos por ele. "adjustment" é a correção de um administrador e todo o resto.
sourcestringA palavra do próprio registro, como usage, one_time_purchase, subscription_renewal, signup_grant, refund, app_earnings ou expiry.
amountnumberO movimento, com sinal: a reserva de uma execução é negativa, uma compra é positiva.
balanceAfternumberO saldo logo depois dele.
pool"subscription" | "topup" | "mixed"Qual parte do saldo se moveu.
descriptionstring | nullA observação do registro.
model, providerstring | nullO modelo que foi executado e o provedor dele, em uma linha com tarefa.
chargenumber | nullA cobrança da tarefa, só na linha de reserva dela, a reserva feita quando a execução foi aceita. É a cobrança liquidada, a reserva enquanto a execução está aberta, ou 0 depois do reembolso. Todas as outras linhas têm null, então somar charge conta cada tarefa uma vez. Leia este campo para o gasto, não amount.
statusstring | nullAo lado de charge: "reserved", "committed" ou "refunded".
jobCreditHistoryJob | nullEm 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.
receiptUrlstring | nullO recibo do Stripe, em uma compra que tem um.
const page = await client.credits.history({ kind: "usage", limit: 50 })
for (const e of page.data) console.log(e.at, e.model, e.charge ?? e.amount, "→", e.balanceAfter)

credits.exportHistory(filters?)

Retorna todo o histórico filtrado como texto CSV (GET /v1/credits/history?format=csv). Tem os mesmos campos e filtros de history(), uma linha por movimento, do mais recente para o mais antigo, sem paginação. Tem no máximo 5.000 linhas, e a última linha diz quando a lista foi cortada: restrinja from e to para o resto.

exportHistory(filters?: CreditHistoryFilters): Promise<string>
const csv = await client.credits.exportHistory({ from: "2026-10-01T00:00:00Z" })
const href = URL.createObjectURL(new Blob([csv], { type: "text/csv" }))

credits.claimWelcomeOffer(input?)

Registra o “sim” do usuário à oferta de boas-vindas em uma só ação (POST /v1/credits/welcome-offer/claim). Registra o consentimento para e-mails de marketing e depois resgata o bônus gratuito de cadastro com esse consentimento. As verificações contra abuso continuam decidindo, então leia grant. Uma conta cujo bônus já foi decidido só tem o consentimento registrado. Só no Nodaro Cloud: uma instância auto-hospedada responde 404.

claimWelcomeOffer(input?: WelcomeOfferClaimInput): Promise<WelcomeOfferClaimResult>

Este método precisa de uma sessão de navegador com login, de supabaseAuth(), porque o consentimento é uma escolha de uma pessoa. Um token de API ou um token de app OAuth recebe 403. Enquanto a implantação estiver com a oferta desligada, a chamada responde 409 welcome_offer_disabled, então mostre a oferta só quando balance().welcomeOffer estiver presente. Em uma implantação em que uma conta de cobrança paga por todos os usuários, os créditos gratuitos de cadastro não valem: a chamada responde 409 not_applicable, não registra nada, nem o consentimento, e balance() não traz welcomeOffer.

WelcomeOfferClaimInput é o SignupKeys de collectSignupKeys() mais sourceApp, o slug do seu app, com até 40 letras minúsculas, dígitos e hifens. Um slug malformado é armazenado como ausente, nunca recusado. Ele também aceita locale, o idioma da interface em que o usuário respondeu. É o ID de um idioma que o Nodaro oferece, como "en", "ja" ou "pt-BR". A comparação é exata e diferencia maiúsculas de minúsculas, então "en-US" ou "pt-br" é armazenado como ausente. Ele é registrado com o consentimento como o idioma do consentimento mais recente.

CampoTipoDescrição
consent"granted"O consentimento de e-mail foi registrado.
grantFreeGrantState"granted": o bônus foi concedido agora ou antes. "withheld": as verificações contra abuso o recusaram. "revoked": o bônus foi retirado antes. "unclaimed": nada mudou, então trate como falha e deixe o usuário tentar de novo.
creditsnumberO valor do bônus, o mesmo de balance().welcomeOffer.credits. Um bônus completa os créditos da assinatura até esse valor. Ele não é somado por cima.

WelcomeOfferState tem quatro campos:

CampoTipoDescrição
popupDueboolean (opcional)Abrir o popup de boas-vindas sozinho agora. Quem decide é o servidor: o bônus não foi resgatado, Talvez depois nunca foi respondido e o popup abriu sozinho menos de três vezes, nenhuma delas nas últimas 24 horas. Um servidor lançado antes deste campo não o envia: então abra o popup enquanto popupSeen for false.
popupSeenboolean!popupDue, mantido para apps escritos antes de popupDue. Leia popupDue no lugar dele.
consentPendingbooleanA conta tem os créditos, mas ainda deve o consentimento de e-mail.
creditsnumberO que um resgate concede. Com consentPending, o que a conta recebeu, que pode ser mais do que um resgate concede hoje.

Mostre o valor de credits na oferta em vez de um número fixo, porque ele segue o servidor.

credits.markWelcomeOfferSeen()

Diz ao servidor o que aconteceu com o popup de boas-vindas (POST /v1/credits/welcome-offer/seen). O servidor decide welcomeOffer.popupDue a partir disso, em todos os apps.

eventQuandoEfeito
"shown"O popup abriu sozinho, porque popupDue era true.Conta uma das três exibições da conta. Nada é contado quando o popup não estava pendente, então uma chamada repetida não causa problema.
"later"O usuário respondeu Talvez depois.O popup não abre mais sozinho.

Um fechamento sem resposta (o ×, Escape, um clique fora) é informado não chamando o método. O popup pode então abrir sozinho de novo em uma visita posterior, no máximo uma vez por dia e três vezes no total. Abrir o popup pelo seu próprio botão também não é uma exibição. Chamado sem evento, o método não envia corpo, o que o servidor lê como "later". Uma chamada que falha só significa que o popup pode aparecer mais uma vez, então você pode ignorar os erros. As regras são as de claimWelcomeOffer(). Em uma implantação em que uma conta de cobrança paga por todos os usuários, ela também responde 409 not_applicable.

markWelcomeOfferSeen(event?: "shown" | "later"): Promise<{ ok: true }>
import { collectSignupKeys } from "@nodaro/sdk/signup-signals"

const { welcomeOffer } = await client.credits.balance()
// An older server sends popupSeen alone: the popup is due while it is false.
const due = welcomeOffer ? (welcomeOffer.popupDue ?? welcomeOffer.popupSeen === false) : false
if (due && !openedByItselfThisVisit()) {
  showPopup({ credits: welcomeOffer.credits }) // the server's figure, never a constant
  rememberOpenedByItselfThisVisit()            // for example, a sessionStorage mark
  void client.credits.markWelcomeOfferSeen("shown").catch(() => {})
}

// On "Maybe later":
void client.credits.markWelcomeOfferSeen("later").catch(() => {})
// On the ×, Escape or a click outside: close the popup and call nothing.

// On "Yes":
const keys = await collectSignupKeys()
const { grant, credits } = await client.credits.claimWelcomeOffer({ ...keys, sourceApp: "my-app", locale: "en" })
if (grant === "granted") showToast(`Your ${credits} free credits are ready`)

client.billing

client.billing lê os planos e os preços à venda, a assinatura de quem chama e como a implantação cobra. Em um app próprio com login feito pela sessão da própria pessoa (supabaseAuth), ele também cobre toda a tela de cobrança. São as compras, as faturas, o cartão registrado, a recarga automática e a passagem para o Stripe Checkout e o Portal do Cliente. Os métodos marcados como só sessão respondem só a uma sessão com login feito. Uma chave de API ou o token OAuth de um app recebe ForbiddenError, então envie esse tipo de cliente para a página de cobrança do app.

// A pricing screen: works signed out.
const { data: plans, topUps } = await client.billing.plans()

// Mark the plan the signed-in account is on.
const { effectiveTier } = await client.billing.subscription()
const current = plans.find((p) => p.id === effectiveTier) // undefined: pay-as-you-go, or a tier not on sale
MétodoRetornaObservações
plans()Promise<BillingPlansResult>GET /v1/billing/plans. Público onde a implantação vende para os usuários: não precisa de credencial, e a resposta é a mesma para todos. Onde uma conta de cobrança paga por todos os usuários, só essa conta de cobrança, com sessão iniciada, recebe a lista. Retorna { data: BillingPlan[], topUps, topUpRange, stripePublishableKey }. stripePublishableKey (string | null) é a chave publicável do Stripe para montar o formulário do Checkout incorporado, ou null quando a implantação não tem uma: use então a página do Checkout. Só no Nodaro Cloud: uma instância auto-hospedada lança NotFoundError. Uma implantação que não vende para os seus usuários lança ForbiddenError. Quando os preços não podem ser lidos por um momento, lança um NodaroError com status 503.
subscription()Promise<BillingSubscriptionResult>GET /v1/billing/subscription. Retorna { data: BillingSubscription | null, effectiveTier }. data é null quando a conta nunca assinou. effectiveTier é o nível que os direitos da conta seguem: normalmente o id de um plano, "payg" para créditos comprados sem assinatura, ou um nível que não está à venda, como "enterprise". Precisa de uma sessão de navegador, de um token de API pessoal sem limite de workflow ou de um token de app OAuth. Só no Nodaro Cloud. Em uma implantação em que uma conta de cobrança paga por todos os usuários, effectiveTier é o plano da implantação e data é a sua própria assinatura, normalmente null.
surface()Promise<BillingSurface>GET /v1/billing/surface. Público, em todas as edições. Se a implantação mede o uso (providerId é "none" quando não mede) e em que unidade os custos são mostrados (displayUnit).
account()Promise<BillingAccountSummary | null>GET /v1/billing/account. O plan, o balance e o dailyAllowance de quem chama, como o provedor de cobrança da implantação os informa, na unit dele. null quando o provedor não conseguiu responder, o que não é um saldo zero. Todas as edições.
purchases()Promise<BillingPurchase[]>GET /v1/billing/transactions. Só sessão. As compras de créditos da conta, da mais recente para a mais antiga, as últimas 50: { id, stripe_transaction_id, type, amount_usd, credits_granted, tier, created_at, receipt_url }. type é "subscription", "topup" ou "refund", em que credits_granted é negativo.
invoices()Promise<BillingDocument[]>GET /v1/billing/invoices. Só sessão. Cada pagamento como um documento, do mais recente para o mais antigo. kind é "invoice" para um pagamento de assinatura, com number, pdfUrl e url do Stripe. É "receipt" para um pacote de créditos ou uma recarga, com os credits concedidos e o recibo como url, sem PDF. Um reembolso é um recibo com status "refunded" e amount e credits negativos. status é "paid", "open", "void", "uncollectible" ou "refunded".
paymentMethod()Promise<BillingPaymentMethod>GET /v1/billing/payment-method. Só sessão. { card, billingDetails }: card é { brand, last4, expMonth, expYear } ou null, e billingDetails é { name, email, country } ou null. Os dois são null para uma conta que ainda não comprou, nunca um erro.
autoRecharge()Promise<BillingAutoRecharge>GET /v1/billing/auto-recharge. Só sessão. { enabled, thresholdCredits, amountUsd, failureCount, lastAttemptAt, hasSavedCard }. Quando o saldo fica abaixo do limite, o valor é carregado do cartão salvo.
setAutoRecharge(input)Promise<BillingAutoRechargeSaved>PUT /v1/billing/auto-recharge. Só sessão. { enabled, thresholdCredits?, amountUsd? }. Para ativar, os dois valores são necessários: thresholdCredits de 100 a 100.000, e amountUsd um valor inteiro dentro de topUpRange. Caso contrário, ele lança um NodaroError com status 400. Salvar zera a contagem de falhas.
checkout(input)Promise<BillingCheckoutSession>POST /v1/billing/create-checkout-session. Só sessão. { priceId, mode?, returnPath?, embedded?, uiMode?, replacesSessionId? } retorna { url }, uma página do Stripe Checkout para o preço de um plano ou um pacote de créditos. Envie a pessoa para lá. Códigos promocionais valem só para planos, e uma compra de pacote liquidada por zero não concede créditos. Lança status 409 para um plano enquanto a conta já tem uma assinatura: use changePlan(). Uma implantação que não vende para os seus usuários lança ForbiddenError com o código self_serve_disabled. Com uiMode: "embedded", retorna { url: null, clientSecret, sessionId } para o Checkout incorporado do Stripe, que nunca redireciona. Veja Comprar dentro da sua própria tela. replacesSessionId indica uma sessão anterior do Checkout sua que esta substitui.
loadCredits(input)Promise<BillingLoadSession>POST /v1/billing/create-load-session. Só sessão. { amountUsd, returnPath?, embedded?, uiMode?, replacesSessionId? } retorna { url, credits }: uma página do Checkout que carrega um valor inteiro dentro de topUpRange como créditos, com a taxa dos pacotes. credits é o que ela concede. O cartão é salvo para a recarga automática. Com uiMode: "embedded", retorna { url: null, clientSecret, sessionId, credits }, como checkout().
checkoutStatus(sessionId)Promise<BillingCheckoutStatus>GET /v1/billing/checkout-session/:sessionId. Só sessão. { status, paymentStatus, mode, granted, paymentUnderWay? } de uma das suas sessões do Checkout. granted é true quando os créditos ou o plano dela estão na conta. Uma sessão que não é sua, ou não existe, lança NotFoundError com o código checkout_session_not_found. Mais de 60 leituras por minuto lançam RateLimitedError.
portal(input?)Promise<BillingPortalSession>POST /v1/billing/manage-subscription. Só sessão. { returnPath? } retorna { url }, uma página do Portal do Cliente do Stripe para o cartão, o endereço de cobrança, as faturas e o cancelamento. Lança NotFoundError antes da primeira compra.
changePlan(input)Promise<BillingChangePlanResult>POST /v1/billing/change-plan. Só sessão. { newPriceId } retorna { subscriptionId, tier }. Move a assinatura ativa para o preço de outro plano. Um upgrade cobra na hora a diferença de preço pelo resto do período de cobrança, e só se aplica quando esse pagamento é aprovado. Ele acrescenta a diferença entre os créditos mensais dos dois planos, uma vez por período de cobrança, e uma fatura de upgrade liquidada por 0 não acrescenta nenhum. Um downgrade se aplica na hora, credita o tempo não usado na próxima fatura e mantém os créditos atuais até o fim do período. Uma troca de mensal para anual, ou o contrário, não acrescenta créditos. Lança NotFoundError sem assinatura ativa, status 400 para o preço de um pacote ou o preço atual, e status 409 quando a assinatura não está ativa. Quando o upgrade espera o pagamento, lança um NodaroError com status 409 e o código plan_change_payment_required: o plano não muda, e details.invoiceUrl é a página do Stripe para pagá-lo. Depois de 5 pedidos de mudança de plano de uma mesma conta em 24 horas, lança RateLimitedError. Veja Mudar de plano.

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

// A billing screen in a first-party app, signed in with supabaseAuth.
const [method, docs, auto] = await Promise.all([
  client.billing.paymentMethod(),
  client.billing.invoices(),
  client.billing.autoRecharge(),
])
// Buy a pack and come back to this screen.
const { url } = await client.billing.checkout({ priceId: pack.priceId!, returnPath: "/settings/credits" })
window.location.assign(url!)

// Or buy inside this screen with Stripe's embedded Checkout.
const { stripePublishableKey } = await client.billing.plans()
const { clientSecret, sessionId } = await client.billing.checkout({ priceId: pack.priceId!, uiMode: "embedded" })
// Mount Stripe's embedded Checkout with stripePublishableKey and clientSecret. When it completes:
const { granted } = await client.billing.checkoutStatus(sessionId!)

Um BillingPlan tem estes campos:

CampoTipoDescrição
idstring"free", "basic", "standard", "pro" ou "business".
namestringO nome de exibição.
prices{ monthly, yearly } | nullnull no plano gratuito. monthly é { priceId, amount, currency, credits }. yearly acrescenta perMonth, o valor anual dividido pelos meses. priceId é o ID de preço do Stripe que checkout() e changePlan() recebem, e com o qual o stripe_price_id da assinatura coincide. amount está na unidade principal da moeda (12 significa 12,00), e currency é o código ISO 4217, como "USD". Qualquer um dos preços pode ser null quando não pode ser vendido agora: mostre-o como indisponível, nunca como gratuito.
prices.*.credits{ amount, per } | nullO que o preço concede, sendo per igual a "month" ou "year". Um preço anual concede os créditos do plano todo mês, como um preço mensal.
signupCreditsnumber | nullO bônus único do plano gratuito no cadastro. null em um plano pago.
parallelismnumberQuantos nós de um workflow rodam ao mesmo tempo.
storageBytesnumberO armazenamento para as suas mídias, em bytes.

topUps são os pacotes de créditos, { id, credits, price, priceId }, do menor para o maior. id é o id do próprio pacote, como "topup-25". price é null quando não pode ser informado agora. priceId é o ID de preço do Stripe para checkout(), e é null junto com o preço. Um pacote sempre pode ser comprado como uma recarga de price.amount pelo loadCredits(). topUpRange, { min, max, currency }, é a faixa de valores inteiros que podem ser carregados como créditos, com a mesma taxa dos pacotes. Veja API sem assinatura para comprar créditos sem um plano.

Comprar dentro da sua própria tela

checkout() e loadCredits() aceitam uiMode (BillingUiMode): "hosted", o padrão, retorna a url da página do Checkout, e "embedded" retorna { url: null, clientSecret, sessionId } para o formulário do Checkout incorporado do Stripe. Monte o formulário com o clientSecret e a stripePublishableKey de plans(). O formulário nunca redireciona, então returnPath e embedded não são usados, mas um returnPath inválido ainda lança o status 400. Um NodaroError com o status 503 e o código embedded_checkout_unavailable significa que a implantação não tem formulário incorporado: use a página do Checkout.

Quando o formulário termina, consulte periodicamente checkoutStatus(sessionId) até granted ser true, e então leia o saldo de novo. O granted de um plano pode chegar um instante antes dos créditos dele.

replacesSessionId é o sessionId de uma sessão anterior do Checkout sua que esta substitui, por exemplo quando a pessoa desiste do formulário incorporado e vai para a página do Checkout. Assim, nunca é possível pagar as duas. Um NodaroError com o status 409 e o código checkout_already_complete significa que essa compra está paga, então não peça de novo. checkout_in_progress significa que o pagamento dela está sendo confirmado: leia checkoutStatus() e peça de novo quando o status estiver open com paymentUnderWay: false, ou expired. Um NotFoundError com checkout_session_not_found significa que a sessão não é sua, ou não é da mesma compra: um plano para um plano, o mesmo pacote ou um 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. Veja Substituir uma sessão anterior do Checkout.

Mostrar os modelos com os preços

Monte um seletor de modelos para um nó, com o preço ao lado de cada modelo:

const { data: node } = await client.nodes.get("generate-video")
const { data: prices } = await client.credits.modelCosts(node.providers ?? [])

const options = (node.providers ?? []).map((id) => ({
  id,
  price: prices[id] ?? null, // null: no price on this instance
}))

Omita provider em uma execução para usar o modelo padrão do nó. Quando um usuário escolher um modelo, envie o ID dele como provider para client.nodes.runAndWait().

Perguntas frequentes

Como listar pelo código os modelos que o Nodaro oferece?

Chame client.models.list(). Ele retorna todos os modelos de imagem, vídeo e áudio, agrupados por tipo e por fabricante, com modos, proporções, resoluções, durações e, no Nodaro Cloud, os preços em créditos.

Como descobrir o preço de um modelo antes de executá-lo?

Chame client.credits.modelCosts com os identificadores de preço do modelo, como nano-banana-pro ou nano-banana-pro:4K. O campo data associa cada identificador ao seu preço em créditos.

Como cotar uma chamada de LLM com o SDK?

Monte a chave de preço com llmPriceKey(feature, model) de @nodaro/shared/llm-models, por exemplo llm-chat:claude-fable-5, e passe-a para client.credits.modelCosts. O valor é uma estimativa de uma chamada típica, listada em estimates, então mostre-o como ≈N.

Como consultar meu saldo de créditos com o SDK?

Chame client.credits.balance(). O campo total é o número de créditos disponíveis, divididos entre créditos da assinatura e créditos de recarga.

Como somar o custo das minhas execuções com o SDK?

Percorra as páginas de client.credits.transactions() com o nextCursor de cada página e some credits_charged. A reserva que uma execução fez primeiro, credits_reserved, não é o que você pagou.

Como mostro os planos e os preços do Nodaro no meu app?

Chame client.billing.plans(). Não precisa de login e retorna todos os planos com o preço e os créditos mensais e anuais, além dos pacotes de créditos. A compra exige a sessão da própria pessoa, com login feito, pelo client.billing.checkout().

Como monto uma tela de uso ou de histórico de cobrança com o SDK?

Chame client.credits.usageSummary() para os totais de um período, por modelo, categoria, sessão e workflow. Chame client.credits.history() para cada movimento do saldo, e exportHistory() para a mesma lista em CSV.

As instalações auto-hospedadas têm preços em créditos?

Não. As instalações auto-hospedadas Community e Business não têm sistema de créditos, então os preços dos modelos e os custos em créditos ficam de fora das respostas delas.

Última atualização

Nesta página