SDK para TypeScript

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 runtimes de edge, e todo erro da API chega como uma classe de erro tipada que você pode capturar.

Instalação

npm install @nodaro/sdk

• O pacote é open source, sob a licença Apache-2.0. Veja o @nodaro/sdk no npm e o código-fonte no GitHub.
• Ele traz builds 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 runtime 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 os helpers de prompt.
• @supabase/supabase-js e @supabase/ssr são dependências peer 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

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 self-hosted, 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 do job: imageUrl para imagens, videoUrl para vídeo e audioUrl para áudio. A primeira chamada executa o nó Gerar imagem (Generate Image) no Nano Banana 2. A segunda anima essa imagem com o nó Gerar vídeo (Generate Video) 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 um job em um worker e retorna na hora. O resultado chega segundos ou minutos depois.

Alguns tipos de nó, como o Combinar texto (Combine Text), 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 Jobs 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 do job a cada consulta, com progress de 0 a 100 quando o modelo informa o progresso. Abortar o sinal só interrompe a espera. O job continua em execução até você cancelá-lo com client.jobs.cancel(jobId), o que também reembolsa os créditos que ele 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

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().

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.

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.