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

Visão geral da API REST

A API REST do Nodaro executa workflows e nós avulsos, consulta tarefas periodicamente, envia mídia e gerencia entidades por HTTPS, com JSON e um token Bearer.

A API REST do Nodaro é a interface HTTP do Nodaro: ela executa workflows e nós avulsos, informa o status das tarefas deles, armazena a sua mídia e gerencia personagens, predefinições e espaços de trabalho. Requisições e respostas são JSON por HTTPS, e toda requisição leva um token Bearer. A mesma API atende o Nodaro Cloud e as instalações auto-hospedadas, e o SDK para TypeScript e a CLI são clientes leves dela.

URL base

Onde o Nodaro rodaURL base
Nodaro Cloudhttps://app.nodaro.ai
Uma instalação auto-hospedadaO endereço da própria instalação, por exemplo http://localhost:3000 em uma instalação padrão da Community Edition

Todo caminho começa com /v1/, por exemplo https://app.nodaro.ai/v1/nodes. Alguns endpoints existem só no Nodaro Cloud, como os de créditos e de organizações, e respondem 404 nas outras edições. Cada página informa quando um endpoint é limitado.

Autenticação

Envie Authorization: Bearer <token> em toda requisição. Use um token de API pessoal (ndr_…) de Configurações › Tokens de API para a sua própria conta. Use um token de acesso OAuth (ndr_app_…) quando o seu produto age em nome de outros usuários do Nodaro, ou o JWT da sua sessão em uma instalação da Community Edition. Alguns endpoints de descoberta, como GET /v1/nodes e GET /v1/models, não precisam de token. Leia Autenticação para criar um token.

A sua primeira chamada

Este exemplo gera uma imagem com um nó e lê o resultado. A geração é assíncrona: a primeira chamada retorna o ID de uma tarefa, e você consulta a tarefa periodicamente até ela ser concluída.

export NODARO_API_KEY="ndr_..."

# 1. Start the job
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "a snow leopard on a mountain ridge at dawn",
        "provider": "nano-banana-pro",
        "aspectRatio": "16:9"
      }'
# {"jobId":"0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10"}

# 2. Poll the job until its status is "completed"
curl -s https://app.nodaro.ai/v1/jobs/0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10/status \
  -H "Authorization: Bearer $NODARO_API_KEY"
{
  "data": {
    "id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
    "status": "completed",
    "progress": 100,
    "output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
    "error_message": null
  }
}
import { createClient, StaticTokenAuth } from '@nodaro/sdk'

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

// Starts the job and polls it until it finishes.
const output = await client.nodes.runAndWait('generate-image', {
  prompt: 'a snow leopard on a mountain ridge at dawn',
  provider: 'nano-banana-pro',
  aspectRatio: '16:9',
})
console.log(output.imageUrl)
nodaro nodes run generate-image \
  --param prompt="a snow leopard on a mountain ridge at dawn" \
  --param provider=nano-banana-pro \
  --param aspectRatio=16:9 \
  --watch --json | jq -r '.output_data.imageUrl'

O mesmo padrão executa qualquer nó de geração: POST /v1/<node-type> com as configurações do nó e, depois, a consulta periódica da tarefa. Veja Executar um único nó.

Convenções de requisição e resposta

  • Entra JSON, sai JSON. Envie os corpos como JSON com Content-Type: application/json. Os uploads de arquivos são a exceção: eles usam multipart/form-data.
  • Os IDs são UUIDs. Um ID malformado responde 400 validation_error.
  • A maioria das respostas vem dentro de data. Uma leitura retorna { "data": … }, e uma exclusão ou um cancelamento retorna { "success": true }. Os endpoints legados de workflow em /v1/api/ retornam o payload diretamente.
  • As gerações retornam o ID de uma tarefa. POST /v1/<node-type> responde com { "jobId": "…" }, às vezes com adjustments ou warnings ao lado.
  • As listas usam cursores. Uma lista retorna um cursor, normalmente nextCursor (next em GET /v1/jobs). Envie esse cursor de volta como ?cursor= para obter a próxima página. Um cursor null significa que não há mais linhas. Os cursores são opacos: nunca analise nem monte um.
  • Dois estilos de campo. Os objetos de tarefa usam snake_case, como output_data e created_at. Workflows, execuções e a maioria dos outros recursos usam camelCase.
  • As respostas crescem. Novos campos aparecem com o tempo. Ignore os campos que você não conhece em vez de falhar por causa deles.
  • Os erros têm um só formato. Uma chamada com falha retorna um status HTTP e { "error": { "code": "…", "message": "…" } }. Decida o tratamento por code. Veja Erros.

Dois cabeçalhos opcionais mudam como uma requisição é tratada:

CabeçalhoO que faz
X-Nodaro-WorkspaceAge em um espaço de trabalho de uma organização: define em qual espaço de trabalho uma lista lê e onde uma criação vai parar. Veja Espaços de trabalho.
X-Nodaro-ClientRegistra qual cliente criou uma tarefa: sdk/<version>, cli/<version> ou extension/<name>. Veja Identificar o seu cliente.

Síncrono ou assíncrono

A maior parte do trabalho no Nodaro leva de segundos a minutos, então a API é assíncrona. Uma rota de geração responde na hora com um jobId, e uma execução de workflow responde 202 Accepted com um executionId. Depois, você consulta periodicamente a tarefa ou a execução, a cada 2 a 5 segundos, até chegar a um status final. Para um workflow que deve terminar em menos de um minuto, POST /v1/api/run?wait=true mantém a conexão aberta por até 600 segundos e retorna o resultado. Algumas rotas respondem de forma síncrona, como os nós de texto inline, o processamento de mídia gratuito e a chamada de LLM com saída estruturada. Leia Síncrono ou assíncrono para ver os detalhes. Para não precisar consultar as tarefas periodicamente, registre um endpoint de webhook: o Nodaro passa a enviar ao seu servidor um evento assinado sempre que uma das suas tarefas é concluída ou falha.

Endpoints por área

Executar

PáginaO que cobrePrincipais endpoints
WorkflowsExecutar um workflow salvo, com ou sem entradas, e gerenciar workflowsPOST /v1/workflows/:id/run, POST /v1/api/run, GET /v1/api/schema
NósExecutar um nó sem workflow, sessões de geração, paletas e painéis de inspiração, e descobrir nós, modelos e seletoresPOST /v1/<node-type>, /v1/sessions, GET /v1/models
TarefasStatus e resultados de tarefas, avaliações e favoritos, consulta periódica em lote, cancelamento e controle das execuções do Gerar vídeo ProGET /v1/jobs/:id/status, POST /v1/jobs/batch-status
ExecuçõesO status e o histórico das execuções de workflowGET /v1/workflow-executions/:id, GET /v1/workflows/:id/executions
Envio de arquivosEnviar imagens, vídeo e áudio, copiar uma URL para o armazenamento e buscar na sua biblioteca de mídiaPOST /v1/upload, GET /v1/library
WebhooksReceber eventos de tarefa assinados no seu servidor, iniciar um workflow por uma chamada HTTP ou por um agendamento, e enviar resultados para fora/v1/webhook-endpoints, POST /v1/webhooks/:token

Recursos

PáginaO que cobrePrincipais endpoints
PersonagensPersonagens, candidatos a retrato, expressões, poses e movimento/v1/characters, POST /v1/generate-character
ObjetosAdereços, produtos e veículos, com a imagem principal e as variações/v1/objects, POST /v1/generate-object
LocaisLugares, com a imagem principal e as variações/v1/locations, POST /v1/generate-location
CriaturasCriaturas, com a imagem principal e as variações/v1/creatures
PredefiniçõesLer e gravar as suas predefinições de nós, e ler o catálogo integrado público/v1/node-presets, GET /v1/node-presets/factory
ComunidadeExplorar e clonar personagens, locais e objetos compartilhadosGET /v1/community/browse
PipelinesPipelines de História → vídeoPOST /v1/pipelines/:id/branch
Assistente de promptMelhorar o prompt de um nó de geraçãoPOST /v1/prompt-helper/wizard
RecastGerar de novo um vídeo analisado com o seu próprio elencoPOST /v1/recast
Video RemakeSubstituir as pessoas, os pets, os produtos ou o lugar de um vídeo curto pelas suas próprias imagensPOST /v1/video-remake
TrendsExecutar uma receita pronta do Video Remake com as suas próprias imagensPOST /v1/trends/:slug/runs
Produções do StudioProduções tomada a tomada/v1/studio/productions
Voz e mídiaVozes, modificação de voz, dublagem, importação de mídia e ferramentas de áudio/v1/voices, /v1/download-video, /v1/transcribe
Direitos de conteúdoA declaração que uma pessoa confirma antes de um link ser importado/v1/content-rights
Treinamento de personagemTreinar um modelo com um personagemPOST /v1/characters/:id/train
Cenas 3DCenas 3D editáveis e a Renderização 3D ProPOST /v1/3d-scene/generate, POST /v1/pro-3d-render

Conta

PáginaO que cobrePrincipais endpoints
Espaços de trabalho e organizaçõesAgir em um espaço de trabalho, organizações, membros, convites e uso/v1/orgs, /v1/workspaces
CréditosSaldo, planos e preços, transações e consultas de custoGET /v1/credits/balance, GET /v1/credits/transactions

Referência

PáginaO que cobre
ErrosO envelope de erro, todos os códigos de erro e as dicas de falha das tarefas
Limites de taxaLimites por token, limites por rota e como lidar com o 429
Especificação OpenAPIA especificação legível por máquina em GET /v1/openapi.json e clientes em outras linguagens

Limites e erros

Um token de API pessoal permite 30 requisições por minuto por padrão, até no máximo 120, nos endpoints de execução e de listagem de workflows. Algumas rotas têm limites próprios. As consultas periódicas de status não contam para o limite do token. Um 429 significa que você deve diminuir o ritmo e tentar de novo com backoff. Um 4xx significa que você deve corrigir a requisição antes de tentar de novo, e um 5xx costuma ser temporário. Leia Limites de taxa e Erros.

Clientes para a sua linguagem

  • TypeScript e JavaScript: npm install @nodaro/sdk. O SDK encapsula estes endpoints com tipos, erros tipados e funções auxiliares de consulta periódica.
  • Terminal e CI: npm install -g @nodaro/cli. A CLI executa workflows, apps e nós avulsos, com --watch e --json.
  • Qualquer outra linguagem: gere um cliente a partir da especificação OpenAPI ou envie requisições HTTPS simples.
  • Assistentes de IA: conecte o servidor MCP em vez de escrever código.

Perguntas frequentes

Qual é a URL base da API do Nodaro?

No Nodaro Cloud, é https://app.nodaro.ai, e todo caminho começa com /v1/, por exemplo https://app.nodaro.ai/v1/nodes. Em uma instalação auto-hospedada, use o endereço da sua própria instalação.

A API do Nodaro é síncrona ou assíncrona?

Na maior parte, assíncrona. Uma geração retorna o ID de uma tarefa, uma execução de workflow retorna o ID de uma execução, e você consulta a tarefa ou a execução periodicamente até que terminem. Para workflows que terminam em menos de um minuto, POST /v1/api/run?wait=true pode manter a conexão aberta em vez disso.

Quais linguagens de programação posso usar com a API do Nodaro?

Qualquer linguagem que envie requisições HTTPS com JSON. Para TypeScript e JavaScript, existe o pacote @nodaro/sdk, e a especificação OpenAPI 3.1 gera clientes tipados para Go, Rust, Python e outras linguagens.

A API do Nodaro consome créditos?

As gerações consomem. No Nodaro Cloud, cada geração gasta créditos pelo preço do modelo, o mesmo do editor. Uma instalação auto-hospedada da Community Edition não tem sistema de créditos, e você paga diretamente aos provedores dos modelos.

Preciso de uma assinatura para usar a API?

Não. No Nodaro Cloud, comprar qualquer pacote de créditos ativa o pagamento por uso, e os créditos do pagamento por uso funcionam pela API, pelo SDK, pela CLI e pelo MCP. Para usar o editor web, é preciso ter uma assinatura.

Última atualização

Nesta página