# Visão geral da API REST

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

Source: https://nodaro.ai/pt-BR/docs/developers/api

A **API REST do Nodaro** é a interface HTTP do Nodaro: ela executa workflows e nós avulsos, informa o status dos jobs 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 self-hosted, e o [SDK para TypeScript](https://nodaro.ai/docs/developers/sdk) e a [CLI](https://nodaro.ai/docs/developers/cli) são clientes leves dela.

## URL base
| Onde o Nodaro roda | URL base |
| --- | --- |
| Nodaro Cloud | `https://app.nodaro.ai` |
| Uma instalação self-hosted | O 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](https://nodaro.ai/docs/developers/api/authentication) 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 um job, e você consulta o job periodicamente até ele ser concluído.

**curl**

```bash
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"
```

```json
{
"data": {
"id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
"status": "completed",
"progress": 100,
"output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
"error_message": null
}
}
```

**TypeScript SDK**

```ts

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)
```

**CLI**

```bash
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 do job. Veja [Executar um único nó](https://nodaro.ai/docs/developers/api/nodes).

## 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 um job.** `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 job 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](https://nodaro.ai/docs/developers/api/errors).

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

| Cabeçalho | O que faz |
| --- | --- |
| `X-Nodaro-Workspace` | Age 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](https://nodaro.ai/docs/developers/api/workspaces). |
| `X-Nodaro-Client` | Registra qual cliente criou um job: `sdk/<version>`, `cli/<version>` ou `extension/<name>`. Veja [Identificar o seu cliente](https://nodaro.ai/docs/developers/api/authentication#identify-your-client). |

## 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 o [job](https://nodaro.ai/docs/developers/api/jobs) ou a [execução](https://nodaro.ai/docs/developers/api/executions), 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](https://nodaro.ai/docs/developers/api/workflows#sync-or-async) para ver os detalhes.

## Endpoints por área
### Executar
| Página | O que cobre | Principais endpoints |
| --- | --- | --- |
| [Workflows](https://nodaro.ai/docs/developers/api/workflows) | Executar um workflow salvo, com ou sem entradas, e gerenciar workflows | `POST /v1/workflows/:id/run`, `POST /v1/api/run`, `GET /v1/api/schema` |
| [Nós](https://nodaro.ai/docs/developers/api/nodes) | Executar um nó sem workflow e descobrir nós, modelos e seletores | `POST /v1/<node-type>`, `GET /v1/nodes`, `GET /v1/models` |
| [Jobs](https://nodaro.ai/docs/developers/api/jobs) | Status e resultados de jobs, consulta periódica em lote, cancelamento e controle das execuções do **Gerar vídeo Pro** (Generate Video Pro) | `GET /v1/jobs/:id/status`, `POST /v1/jobs/batch-status` |
| [Execuções](https://nodaro.ai/docs/developers/api/executions) | O status e o histórico das execuções de workflow | `GET /v1/workflow-executions/:id`, `GET /v1/workflows/:id/executions` |
| [Envio de arquivos](https://nodaro.ai/docs/developers/api/uploads) | Enviar imagens, vídeo e áudio, ou copiar uma URL para o armazenamento | `POST /v1/upload`, `POST /v1/save-to-storage` |
| [Webhooks](https://nodaro.ai/docs/developers/api/webhooks) | Iniciar um workflow por uma chamada HTTP ou por um agendamento, e enviar resultados para fora | `POST /v1/webhooks/:token`, `POST /v1/workflow-triggers` |

### Recursos
| Página | O que cobre | Principais endpoints |
| --- | --- | --- |
| [Personagens](https://nodaro.ai/docs/developers/api/characters) | Personagens, candidatos a retrato, expressões, poses e movimento | `/v1/characters`, `POST /v1/generate-character` |
| [Objetos](https://nodaro.ai/docs/developers/api/objects) | Adereços, produtos e veículos, com a imagem principal e as variações | `/v1/objects`, `POST /v1/generate-object` |
| [Locais](https://nodaro.ai/docs/developers/api/locations) | Lugares, com a imagem principal e as variações | `/v1/locations`, `POST /v1/generate-location` |
| [Criaturas](https://nodaro.ai/docs/developers/api/creatures) | Criaturas, com a imagem principal e as variações | `/v1/creatures` |
| [Predefinições](https://nodaro.ai/docs/developers/api/presets) | As suas predefinições de nós e o catálogo integrado, somente leitura | `GET /v1/node-presets`, `GET /v1/node-presets/factory` |
| [Comunidade](https://nodaro.ai/docs/developers/api/community) | Explorar e clonar personagens, locais e objetos compartilhados | `GET /v1/community/browse` |
| [Pipelines](https://nodaro.ai/docs/developers/api/pipelines) | Pipelines de **História → vídeo** (Story → Video) | `POST /v1/pipelines/:id/branch` |
| [Assistente de prompt](https://nodaro.ai/docs/developers/api/prompt-wizard) | Melhorar o prompt de um nó de geração | `POST /v1/prompt-helper/wizard` |
| [Recast](https://nodaro.ai/docs/developers/api/recast) | Gerar de novo um vídeo analisado com o seu próprio elenco | `POST /v1/recast` |
| [Produções do Studio](https://nodaro.ai/docs/developers/api/studio-productions) | Produções tomada a tomada | `/v1/studio/productions` |
| [Voz e mídia](https://nodaro.ai/docs/developers/api/voice-and-media) | Vozes, modificação de voz, dublagem, importação de mídia e ferramentas de áudio | `/v1/voices`, `/v1/download-video`, `/v1/transcribe` |
| [Treinamento de personagem](https://nodaro.ai/docs/developers/api/character-training) | Treinar um modelo com um personagem | `POST /v1/characters/:id/train` |
| [Cenas 3D](https://nodaro.ai/docs/developers/api/3d-scenes) | Cenas 3D editáveis e a **Renderização 3D Pro** (3D Render Pro) | `POST /v1/3d-scene/generate`, `POST /v1/pro-3d-render` |

### Conta
| Página | O que cobre | Principais endpoints |
| --- | --- | --- |
| [Espaços de trabalho e organizações](https://nodaro.ai/docs/developers/api/workspaces) | Agir em um espaço de trabalho, organizações, membros, convites e uso | `/v1/orgs`, `/v1/workspaces` |
| [Créditos](https://nodaro.ai/docs/developers/api/credits) | Saldo, transações e consultas de custo | `GET /v1/credits/balance`, `GET /v1/credits/transactions` |

### Referência
| Página | O que cobre |
| --- | --- |
| [Erros](https://nodaro.ai/docs/developers/api/errors) | O envelope de erro, todos os códigos de erro e as dicas de falha dos jobs |
| [Limites de taxa](https://nodaro.ai/docs/developers/api/rate-limits) | Limites por token, limites por rota e como lidar com o `429` |
| [Especificação OpenAPI](https://nodaro.ai/docs/developers/api/openapi) | A 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](https://nodaro.ai/docs/developers/api/rate-limits) e [Erros](https://nodaro.ai/docs/developers/api/errors).

## Clientes para a sua linguagem
- **TypeScript e JavaScript:** `npm install @nodaro/sdk`. O [SDK](https://nodaro.ai/docs/developers/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](https://nodaro.ai/docs/developers/cli) executa workflows, apps e nós avulsos, com `--watch` e `--json`.
- **Qualquer outra linguagem:** gere um cliente a partir da [especificação OpenAPI](https://nodaro.ai/docs/developers/api/openapi) ou envie requisições HTTPS simples.
- **Assistentes de IA:** conecte o [servidor MCP](https://nodaro.ai/docs/mcp) em vez de escrever código.

## Frequently asked questions

### 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 self-hosted, 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 um job, uma execução de workflow retorna o ID de uma execução, e você consulta o job 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 self-hosted 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.