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

SDK para TypeScript

Instale o @nodaro/sdk, use um token de API e execute nós e workflows do Nodaro em TypeScript, no Node.js, no navegador e em ambientes de execução de borda.

O SDK do Nodaro para TypeScript é o cliente tipado da API REST do Nodaro, publicado no npm como @nodaro/sdk. Ele executa nós avulsos e workflows inteiros, espera os resultados e gerencia personagens, vozes, mídias e muito mais. Funciona no Node.js, no navegador e em ambientes de execução de borda, e todo erro da API chega como uma classe de erro tipada que você pode capturar.

Instalação

npm install @nodaro/sdk
  • O pacote é de código aberto, sob a licença Apache-2.0. Veja o @nodaro/sdk no npm e o código-fonte no GitHub.
  • Ele traz compilações em ES module e CommonJS, com definições de tipo do TypeScript.
  • Ele precisa do Node.js 20 ou mais recente. Também roda em qualquer ambiente de execução com fetch e URL globais: navegadores modernos, React Native, Cloudflare Workers, Deno e Bun.
  • Ele instala junto outros dois pacotes do Nodaro: @nodaro/shared, com os tipos de dados da API e o catálogo de modelos, e @nodaro/prompts, com as funções auxiliares de prompt.
  • @supabase/supabase-js e @supabase/ssr são dependências pares opcionais. Instale-os apenas para um app de navegador que faz o login dos usuários com o Supabase, por meio de supabaseAuth ou @nodaro/sdk/supabase.
  • A CLI do Nodaro é construída sobre este SDK, então um comando da CLI e uma chamada do SDK chegam aos mesmos endpoints.

Obter um token de API

Criar o token

Entre no Nodaro, abra Configurações › Tokens de API e clique em Criar token.

Copiar o token na hora

O token começa com ndr_ e é mostrado apenas uma vez. O Nodaro guarda apenas um hash dele, então um token perdido não pode ser mostrado de novo. Nesse caso, crie um novo.

Manter o token fora do código

Guarde o token em uma variável de ambiente, como NODARO_TOKEN, ou no seu gerenciador de segredos. Nunca o coloque em código do lado do cliente.

Um token pessoal age como você. Para agir em nome de outras pessoas, por exemplo em um app ao qual muitos usuários se conectam, use OAuth em vez disso. A página Autenticação compara todas as opções.

Fazer a primeira chamada

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
})

const { data: nodes } = await client.nodes.list()
console.log(`${nodes.length} node types available`)

client.nodes.list() não custa nada e não precisa de escopos, então é um bom primeiro teste da conexão. Em uma instalação auto-hospedada, defina baseUrl como o endereço da sua instância. Em um app de navegador servido pela mesma origem que o Nodaro, use uma string vazia. A página Cliente lista todas as opções de createClient.

Gerar uma imagem e depois um vídeo

const image = await client.nodes.runAndWait("generate-image", {
  prompt: "A snow leopard resting on a rock at sunrise",
  provider: "nano-banana-2",
})
console.log(image.imageUrl)

const video = await client.nodes.runAndWait("generate-video", {
  prompt: "The snow leopard slowly turns its head toward the camera",
  imageUrl: image.imageUrl,
  provider: "seedance-2-fast",
  duration: 4,
})
console.log(video.videoUrl)

runAndWait inicia a execução, consulta-a periodicamente e resolve com a saída da tarefa: imageUrl para imagens, videoUrl para vídeo e audioUrl para áudio. A primeira chamada executa o nó Gerar imagem no Nano Banana 2. A segunda anima essa imagem com o nó Gerar vídeo no Seedance 2 Fast.

Omita provider para usar o modelo padrão do nó. A página de cada nó lista os modelos que ele pode executar e os preços em créditos deles, e client.models.list() retorna o mesmo catálogo pelo código. Veja Modelos e créditos.

Como as execuções funcionam

A geração é assíncrona. Uma requisição inicia uma tarefa em um worker e retorna na hora. O resultado chega segundos ou minutos depois.

Você chamaVocê recebeO que fazer em seguida
client.nodes.run(type, params){ jobId }Consulte client.jobs.getStatus(jobId) periodicamente até o status ser completed, failed ou cancelled.
client.nodes.runAndWait(type, params, opts)A saída da tarefaNada. O SDK consulta o status a cada 2 segundos, por até 15 minutos.
client.nodes.runMany(type, paramsList, opts)Um { jobId, output } por requisiçãoNada. As execuções começam juntas e resolvem na ordem da entrada.
client.workflows.run(id){ executionId, status }Consulte client.executions.get(executionId) periodicamente até a execução terminar.

Alguns tipos de nó, como o Combinar texto, são executados dentro da própria requisição e retornam o resultado diretamente, sem jobId. A página Executar nós explica todos os métodos de execução, e Tarefas e execuções explica os status.

Mostrar o progresso e deixar o usuário parar de esperar

import { JobAbortedError } from "@nodaro/sdk"

const controller = new AbortController()
stopButton.onclick = () => controller.abort()

try {
  const clip = await client.nodes.runAndWait(
    "generate-video",
    { prompt: "Waves roll onto a black sand beach", provider: "seedance-2-fast", duration: 4 },
    {
      signal: controller.signal,
      onProgress: (status) => setProgressBar(status.progress ?? 0),
    },
  )
  showVideo(clip.videoUrl)
} catch (err) {
  if (err instanceof JobAbortedError && err.jobId) {
    await client.jobs.cancel(err.jobId)
  } else {
    throw err
  }
}

onProgress recebe o status da tarefa a cada consulta, com progress de 0 a 100 quando o modelo informa o progresso. Abortar o sinal só interrompe a espera. A tarefa continua em execução até você cancelá-la com client.jobs.cancel(jobId), o que também reembolsa os créditos que ela tinha reservado.

Mostre cada resultado assim que ele chegar. Em um fluxo de duas etapas, exiba a imagem enquanto a etapa do vídeo ainda está em execução.

Escolher como autenticar

ProvedorUse quandoOrigem do token
StaticTokenAuthCódigo de servidor com um token fixoUm token de API (ndr_...) ou um token de acesso OAuth (ndr_app_...)
CallbackAuthVocê mesmo renova ou rotaciona os tokensA sua função, chamada antes de cada requisição
supabaseAuthUm app de navegador cujos usuários entram na mesma instância do NodaroA sessão ativa do usuário

Cada requisição pede um token ao provedor e o envia como Authorization: Bearer <token>. Quando o provedor retorna null, a requisição sai sem o cabeçalho. Veja Autenticação para conhecer cada provedor e as regras específicas do navegador.

Tratar erros

Todo método lança uma subclasse tipada de NodaroError quando a API responde com um erro. Capture primeiro as classes específicas e NodaroError por último.

import {
  InsufficientCreditsError,
  NodaroError,
  RateLimitedError,
  UnauthorizedError,
} from "@nodaro/sdk"

try {
  await client.workflows.run(workflowId)
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    showPaywall({ required: err.required, available: err.available })
  } else if (err instanceof UnauthorizedError) {
    askForANewToken()
  } else if (err instanceof RateLimitedError) {
    retryLater()
  } else if (err instanceof NodaroError) {
    console.error(`API error ${err.status} (${err.code}): ${err.message}`)
  } else {
    throw err // a network failure, not an API answer
  }
}

Todo NodaroError tem um message, um code estável, como insufficient_credits, e o status HTTP. A página Erros lista todas as classes e quando cada uma é lançada.

Receitas comuns

Executar um workflow e esperar o resultado

client.workflows.run() inicia uma execução, que executa uma vez cada nó do workflow, e retorna na hora. Consulte client.executions.get() periodicamente até o status ser final.

const { executionId } = await client.workflows.run(workflowId)

for (;;) {
  const { data } = await client.executions.get(executionId)
  console.log(`${data.completedNodes}/${data.totalNodes} nodes done`)

  if (["completed", "failed", "cancelled", "timed_out"].includes(data.status)) {
    if (data.status !== "completed") throw new Error(data.errorMessage ?? data.status)
    console.log(`Done. Used ${data.totalCreditsUsed} credits.`)
    break
  }
  await new Promise((resolve) => setTimeout(resolve, 2_000))
}

Passe { nodeIds: [...] } como segundo argumento para executar apenas alguns nós. Veja Workflows e projetos.

Gerar vários candidatos de uma vez

const results = await client.nodes.runMany("generate-image", [
  { prompt: "A lighthouse at dawn, watercolor" },
  { prompt: "A lighthouse at dusk, watercolor" },
  { prompt: "A lighthouse in a storm, watercolor" },
])
for (const { jobId, output } of results) console.log(jobId, output.imageUrl)

runMany rejeita quando qualquer execução falha. Para deixar um modelo escolher o melhor resultado, passe as URLs para client.reduce.run().

Para imagens, uma única chamada faz o mesmo. runBatchAndWait() recebe count (de 1 a 4 imagens) ou models (de 2 a 4 modelos de imagem). O lote é cobrado inteiro, e uma imagem que falha nunca descarta as outras.

const { results } = await client.nodes.runBatchAndWait("generate-image", {
  prompt: "A lighthouse at dusk, watercolor",
  count: 4,
})
for (const r of results) if (r.status === "completed") console.log(r.output.imageUrl)

Enviar um arquivo e usá-lo

const upload = await client.uploads.upload(file) // a File, in the browser or Node.js
const portrait = await client.nodes.runAndWait("generate-image", {
  prompt: "The same person as a watercolor portrait",
  referenceImageUrls: [upload.url],
})

O upload retorna uma url pública que você pode passar para qualquer nó que receba a URL de uma imagem, de um vídeo ou de um áudio. Veja Mídia e uploads.

Verificar o preço antes de executar

const { total } = await client.credits.balance()
const { data: prices } = await client.credits.modelCosts(["nano-banana-pro", "nano-banana-pro:4K"])

if (total < prices["nano-banana-pro:4K"]) showPaywall()

Preços e saldos existem no Nodaro Cloud. Veja Modelos e créditos e Créditos.

Ser avisado quando uma tarefa termina, em vez de consultar periodicamente

Registre um endpoint https uma vez. A partir daí, o Nodaro envia a ele um POST assinado para cada job.completed e job.failed da sua conta, e tenta de novo até o seu servidor responder com um status 2xx.

const { data: endpoint, secret } = await client.webhooks.create({ url: "https://example.com/nodaro-webhook" })
// `secret` is shown only once: keep it with your server's configuration.
await client.webhooks.test(endpoint.id) // a ping; see client.webhooks.deliveries(endpoint.id)

No lado que recebe, verifique a assinatura no corpo bruto antes de confiar nele:

import { verifyWebhookSignature } from "@nodaro/sdk"

const event = await verifyWebhookSignature({
  payload: rawBody,
  header: request.headers.get("nodaro-signature"),
  secret: process.env.NODARO_WEBHOOK_SECRET!,
})
if (event.type === "job.completed") console.info(event.data.job.output_data)

Veja client.webhooks e Webhooks para os eventos, o corpo e o cronograma de novas tentativas.

Melhorar um prompt antes de gerar

const { prompt } = await client.promptHelper.enhance({
  nodeType: "generate-image",
  prompt: "snow leopard on a rock",
})

O Assistente de prompt reescreve uma ideia rascunhada como um prompt detalhado para o nó que você indicar. Cada chamada custa créditos.

Usar o SDK com um assistente de programação com IA

  • Plugin do Claude Code. Execute /plugin marketplace add nodaroai/app.nodaro.ai e depois /plugin install nodaro. O plugin adiciona uma skill que conhece os padrões, os modelos e os créditos do SDK, e conecta o servidor MCP hospedado do Nodaro. Veja Skills para agentes.
  • Outros assistentes. O README do pacote no npm começa com uma introdução curta escrita para assistentes de programação. Cole-a no Cursor ou em qualquer outro assistente junto com o seu pedido.
  • Sem nenhum código. Para deixar um assistente executar o Nodaro por você, conecte-o por MCP.

Referência

O SDK encapsula os mesmos endpoints da API REST. Para um endpoint que ainda não tem método no SDK, chame-o com client.request(), que mantém a mesma autenticação e os mesmos erros tipados.

Perguntas frequentes

O que é o @nodaro/sdk?

É o cliente oficial em TypeScript da API REST do Nodaro. Ele executa nós e workflows, espera os resultados e gerencia personagens, vozes, mídias e muito mais, com um método tipado e um erro tipado para cada chamada.

Como autenticar o SDK do Nodaro?

Crie um token no Nodaro em Configurações › Tokens de API, guarde-o em uma variável de ambiente e passe-o para createClient como new StaticTokenAuth(token). Apps de navegador e apps OAuth usam supabaseAuth ou CallbackAuth em vez disso.

Quais ambientes de execução o SDK suporta?

Node.js 20 ou mais recente e qualquer ambiente de execução com fetch e URL globais, como navegadores modernos, React Native, Cloudflare Workers, Deno e Bun.

Preciso consultar os resultados periodicamente por conta própria?

Não. client.nodes.runAndWait inicia uma execução, consulta a tarefa dela a cada 2 segundos e resolve com as URLs de saída. Escreva o seu próprio loop com client.jobs.getStatus apenas quando precisar de controle total.

Posso usar o SDK com uma instalação auto-hospedada do Nodaro?

Sim. Defina baseUrl como o endereço da sua instância. Alguns recursos, como as produções do Studio, o Recast e as organizações, só existem no Nodaro Cloud e respondem 404 nas demais instalações.

Última atualização

Nesta página