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
fetcheURLglobais: 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-jse@supabase/ssrsã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 desupabaseAuthou@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ê chama | Você recebe | O 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 tarefa | Nada. O SDK consulta o status a cada 2 segundos, por até 15 minutos. |
client.nodes.runMany(type, paramsList, opts) | Um { jobId, output } por requisição | Nada. 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
| Provedor | Use quando | Origem do token |
|---|---|---|
StaticTokenAuth | Código de servidor com um token fixo | Um token de API (ndr_...) ou um token de acesso OAuth (ndr_app_...) |
CallbackAuth | Você mesmo renova ou rotaciona os tokens | A sua função, chamada antes de cada requisição |
supabaseAuth | Um app de navegador cujos usuários entram na mesma instância do Nodaro | A 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.aie 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
Cliente
createClient, todas as opções, os espaços de trabalho e a lista completa de recursos.
Autenticação
StaticTokenAuth, CallbackAuth, supabaseAuth e sessões compartilhadas do navegador.
Erros
Todas as classes de erro, o status e o código de cada uma, e como se recuperar.
Executar nós
run, runAndWait e runMany, com parâmetros tipados.
Workflows e projetos
Criar, atualizar, compartilhar, exportar e executar workflows.
Tarefas e execuções
Consultar periodicamente, listar, cancelar e excluir execuções.
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.
Páginas relacionadas
Cliente
Autenticação
Executar nós
Erros
Visão geral da API REST
Última atualização
Especificação OpenAPI
Baixe a especificação OpenAPI 3.1 do Nodaro em /v1/openapi.json, veja os endpoints que ela cobre e gere clientes tipados em Go, Rust, Python e mais.
Cliente
Crie um cliente do SDK do Nodaro com createClient, defina URL base, autenticação, tempo limite e espaço de trabalho, e veja todos os recursos do cliente.