Executar nós

client.nodes lista os tipos de nó que um servidor do Nodaro aceita e executa qualquer um deles diretamente, sem montar um workflow. Uma execução envia os seus parâmetros para o endpoint do nó, POST /v1/<type>, e retorna um job que você pode aguardar. É o mesmo caminho que a CLI usa em nodaro nodes run e que as ferramentas MCP do Nodaro usam. Veja Executar um único nó para a visão REST.

Métodos

client.nodes

list()

Lista todos os tipos de nó que o servidor aceita. O servidor pode manter a resposta em cache por 5 minutos. A chamada não custa nada e não exige escopos.

list(): Promise<{ data: NodeDescriptor[] }>

const { data: nodes } = await client.nodes.list()

const imageGenerators = nodes.filter((n) => n.category === "ai-image")
const takesReferences = nodes.filter((n) => n.capabilities?.includes("supports-reference-image"))

Cada NodeDescriptor tem estes campos:

As instalações self-hosted Community e Business não têm sistema de créditos, então os descritores delas omitem creditCost.

get(type)

Lê o descritor de um tipo de nó.

get(type: string): Promise<{ data: NodeDescriptor }>

const { data: node } = await client.nodes.get("generate-video")
console.log(node.providers)  // every video model id
console.log(node.creditCost) // Nodaro Cloud only

Para mostrar os preços ao lado dos modelos, passe node.providers para client.credits.modelCosts().

run(type, params?, options?)

Inicia um nó e retorna imediatamente. O corpo é enviado para POST /v1/<type>, a rota que todo nó de geração usa. Os nomes dos campos correspondem aos campos de entrada do nó.

run(type: string, params?: Record<string, unknown>, options?: { idempotencyKey?: string }): Promise<RunNodeResult>

const result = await client.nodes.run("generate-image", {
  prompt: "A snow leopard in the mountains",
  provider: "nano-banana-2",
})

if ("jobId" in result) {
  const { data: job } = await client.jobs.getStatus(result.jobId)
  console.log(job.status)
}

O que volta. A maioria dos tipos de nó é assíncrona: o resultado traz um jobId, e um worker faz a geração. Consulte client.jobs.getStatus(jobId) periodicamente até o job terminar, ou use runAndWait(). Alguns tipos de nó inline, como combine-text, retornam o resultado completo imediatamente, sem jobId. Verifique se há um jobId para decidir o que fazer.

Correções de parâmetros. Nos tipos de nó de imagem (generate-image, image-to-image e edit-image), o servidor pode corrigir um valor que o modelo escolhido não aceita. A execução continua com o valor corrigido, e os créditos reservados correspondem a ele. O resultado então traz adjustments, com uma entrada por campo corrigido:

const result = await client.nodes.run("generate-image", {
  prompt: "A snow leopard",
  provider: "gpt-image-2",
  aspectRatio: "3:2",
})
if ("adjustments" in result && result.adjustments?.length) {
  for (const a of result.adjustments) {
    console.warn(`${a.field}: ${a.from} -> ${a.to ?? "(dropped)"} (${a.reason})`)
  }
}

Cada ajuste tem field (aspectRatio, resolution, quality ou duration), from, to e reason. adjustments não aparece quando nada mudou.

Lança InsufficientCreditsError quando a conta não consegue pagar, StorageExceededError quando o armazenamento está cheio e JobBlockedError quando uma política de conteúdo da implantação recusa a requisição. Veja Erros.

runAndWait(type, params?, opts?)

Executa um nó assíncrono até o fim. O método chama run(), pega o jobId e consulta client.jobs.getStatus() periodicamente até o job terminar. Ele resolve com a saída do job quando o status é completed.

runAndWait(type: string, params?: Record<string, unknown>, opts?: RunAndWaitOptions): Promise<NodeJobOutput>

const output = await client.nodes.runAndWait(
  "generate-video",
  { prompt: "Rain falls on a neon street at night", provider: "seedance-2-fast", duration: 4 },
  { onProgress: (s) => console.log(`${s.progress ?? 0}%`) },
)
console.log(output.videoUrl, output.thumbnailUrl)

A saída é um NodeJobOutput: imageUrl para nós de imagem, videoUrl e thumbnailUrl para nós de vídeo, audioUrl para nós de áudio, além de quaisquer outros campos que o nó grave. O nó Separação de áudio (Audio Separation), por exemplo, adiciona uma URL por stem, como vocalUrl e instrumentalUrl.

O método lança estes erros tipados:

Recuperações lentas. Às vezes um modelo entrega o resultado depois que o worker já desistiu dele. O job então fica em processing com recovering: true enquanto a plataforma o recupera, o que pode levar dezenas de minutos em modelos lentos. Se um JobTimeoutError encerrar a sua espera, busque o job mais tarde com client.jobs.get(jobId) ou aumente maxMs.

runMany(type, paramsList, opts?)

Inicia várias execuções de um tipo de nó ao mesmo tempo e aguarda todas, por exemplo para gerar uma grade de candidatos. Cada entrada é executada por runAndWait().

runMany(type: string, paramsList: Record<string, unknown>[], opts?: RunAndWaitOptions): Promise<RunManyResult[]>

const results = await client.nodes.runMany("generate-image", [
  { prompt: "A snow leopard at sunrise" },
  { prompt: "A snow leopard at golden hour" },
  { prompt: "A snow leopard at blue hour" },
])
for (const { jobId, output } of results) console.log(jobId, output.imageUrl)

O método resolve quando todas as execuções terminam, com um { jobId, output } por entrada, na mesma ordem da lista que você passou. Ele rejeita assim que qualquer execução falha, com os mesmos erros de runAndWait(). Para escolher o melhor resultado depois, passe as URLs para client.reduce.run().

Parâmetros tipados

Quatro tipos de nó têm parâmetros tipados, então o seu editor de código completa e verifica os campos deles. Todos os outros tipos de nó recebem um objeto simples; os campos são os campos de entrada do nó, listados em inputSchema e na página do nó na Referência de nós. Os nós de cena 3D também têm parâmetros tipados: veja Cenas 3D.

Todo objeto de parâmetros tipados também aceita outros campos da rota. O servidor valida o corpo completo.

GenerateImageParams

GenerateVideoParams

A via de imagem para vídeo: um quadro inicial, um quadro final opcional e referências.

TextToVideoParams

A via de vídeo só com prompt, POST /v1/text-to-video. O prompt é obrigatório, e os quadros inicial e final ficam com o generate-video. Um modelo sem modo de texto para vídeo responde 400 image_required.

AssembleNarratedVideoParams

Junta blocos de vídeo com narração em um único vídeo. A execução é cobrada pelo número de blocos e custa 44 créditos: 3 unidades, mais uma unidade a cada 6 blocos ou fração de 6. Veja Montar vídeo narrado para saber como cada bloco é ajustado à sua narração.

Referências

generate-image, generate-video e text-to-video aceitam referências do jeito que o editor as conecta. O servidor as transforma em diretivas numeradas no prompt, como @image_1, então você não precisa escrever “Image 1 is...”.

• connectedReferences é uma lista de entradas ConnectedReference, o formato de referência conectada do editor, exportado pelo SDK. O servidor remove duplicatas e mantém quantas o modelo aceitar. referenceOrder define a ordem delas pelo ID.
• Bloqueio de identidade. Uma entrada pode trazer identityLock: { enabled: true, text? }. O servidor então adiciona uma linha curta que diz ao modelo para manter a identidade dessa referência. text substitui o texto padrão, e {ref} dentro dele representa o nome da referência. O bloqueio vem desativado por padrão.
• describedReferences recebe até 10 entradas { name, description } para assuntos que você consegue nomear, mas dos quais não tem imagem, como um papel em um roteiro. Cada uma vira uma linha Name — description. no prompt. Mantenha o nome no texto do prompt, para que o modelo saiba quem é.
• descriptionOverride em uma entrada de referência substitui a descrição armazenada dela só nesta execução.
• Legendas para referências de vídeo e áudio. referenceVideoCaptions e referenceAudioCaptions seguem a ordem de referenceVideoUrls e referenceAudioUrls. Cada legenda aparece no prompt como @video_1: caption. ou @audio_1: caption..
• Mencione uma referência de imagem no prompt. No generate-image, dê um nome a uma referência e mencione-a como @<name>:<index> ou @<name>:<index>:<role>, por exemplo @town:1:background. A menção insere essa referência, ou o papel dela, naquele ponto do prompt. ~lock e ~nolock funcionam como nas menções de personagem.

Veja Papéis de referência para os papéis que você pode usar e Personagens consistentes para trabalhar com identidade.

Direção

generate-image, generate-video e text-to-video aceitam um objeto direction com IDs de seletor em vez de palavras. O Nodaro escreve no prompt um texto testado para cada ID, então o seu código envia IDs e o texto continua sempre atualizado.

await client.nodes.runAndWait("generate-image", {
  prompt: "A detective waits under a street lamp",
  direction: { shotSize: "wide-shot", timeOfDay: "golden-hour", mood: "suspicious" },
})

• As chaves são dimensões de seletor, como shotSize, lightingStyle, style, mood, photographer ou era. As rotas de vídeo adicionam chaves de movimento, como cameraMotion, actionFx, transition, loopSubject e as chaves temporal.
• Os valores são um ID ou um array de IDs. Uma dimensão que aceita vários valores mantém no máximo o próprio limite e descarta o resto. A requisição só é recusada acima de 8 valores por chave ou de 100 caracteres por ID.
• Chaves e IDs desconhecidos são ignorados, não recusados. Um direction vazio deixa o seu prompt inalterado.
• Um único mapa serve para imagens e vídeo. Uma chave só de imagem fixa enviada a uma execução de vídeo é aceita e não adiciona nada.
• extend-video não recebe direction, porque o prompt dele continua um clipe existente.

Leia os IDs válidos em client.pickerCatalogs. Veja Catálogos de seletores para todas as dimensões.

Nós de modelo de linguagem

run(type, params) envia para /v1/<type>. Entre os nós de modelo de linguagem, essa rota só existe para generate-script, image-critic, qa-check e describe-to-picker. Os outros nós de modelo de linguagem usam um caminho mais longo, então chame-os com client.request():

await client.nodes.run("generate-script", {
  prompt: "A 3-scene product launch script for a smart water bottle",
  reasoningEffort: "high",
})

• reasoningEffort é "none", "low", "medium", "high", "xhigh" ou "max", conforme o modelo. Omita-o, ou envie um nível que o modelo não aceita, para usar o padrão do modelo. xhigh e max cobram um nível de créditos acima, até o nível premium. Veja o nó Prompt para os modelos e os níveis de cada um.
• advancedMode: true executa um modelo Gemini diretamente na API do fabricante. Só ali temperature, maxTokens e toda a faixa de esforço têm efeito completo. O modo cobra um nível de créditos acima, somado a qualquer aumento por esforço. O nível de créditos tem como teto o nível premium. Um modelo sem essa opção responde 400 advanced_mode_unsupported.
• O streaming não é encapsulado. O SDK não lê a resposta em streaming do nó Prompt. Para ela, use fetch com um stream legível.

Regras específicas de modelos

Alguns modelos de vídeo aceitam valores que os outros não aceitam. A página de cada modelo lista todas as opções e os preços.

• Seedance 2 aceita resolution: "4k" e aspectRatio: "adaptive" ou "21:9". O Seedance 2 Fast e o Seedance 2 Mini renderizam só em 480p ou 720p.
• Seedance 2.5 renderiza em 480p, 720p ou 1080p, gera até 30 segundos em uma chamada e aceita 30 referências de imagem, 10 de vídeo e 10 de áudio. Com um quadro inicial, ele usa a proporção desse quadro e recusa um aspectRatio explícito.
• MiniMax Hailuo 3 (minimax-h3) aceita 9 referências de imagem, 3 de vídeo e 3 de áudio com resolution: "2K" (o padrão) ou "768P". Qualquer outro valor é renderizado e cobrado como 2K.
• Wan 3.0 (wan-3 e o mais rápido wan-3-prime) aceita 10 referências de imagem, 5 de vídeo e 5 de áudio. As listas de referências não podem ser combinadas com imageUrl nem com endFrameUrl. duration é um número inteiro de 2 a 30, e resolution é 480p, 720p ou 1080p.
• Gemini Omni Flash aceita a mesma requisição que o Gemini Omni: durações de 4, 6, 8 ou 10 segundos, de 720p a 4K, e só 16:9 ou 9:16.

Texto para fala. Quando você omite provider, o nó Texto para fala (Text to Speech) usa o ElevenLabs v3 para textos de até 3.000 caracteres. Textos mais longos passam para o ElevenLabs Turbo v2.5, cujo limite é de 40.000 caracteres, para não serem cortados. Um provider que você indicar é sempre usado.

Scrapers e outros nós de entrada

Os nós de entrada são executados do mesmo jeito. Um scraper, como o nó Extrair da web (Web Scrape), responde imediatamente: o resultado traz um jobId para o seu histórico e os próprios dados, então você pode usá-los sem consultas periódicas. Os campos da requisição são os campos de entrada do nó, listados em inputSchema.