Predefinições

A API de predefinições lê as predefinições de nós que você salvou no editor e o catálogo integrado de predefinições de cada tipo de nó. Uma predefinição é uma configuração de nó com nome, por exemplo um modelo, um prompt, uma proporção e uma qualidade, que você aplica a um nó em um passo. Para tokens de API, as rotas são somente leitura: você cria e edita predefinições no editor.

As rotas funcionam em todas as edições. Elas recebem um bearer token: um token de API pessoal (ndr_…), um token de app OAuth com o escopo presets:read ou o seu token de sessão. Veja Autenticação e, para saber o que as predefinições fazem no editor, Predefinições.

Endpoints

Ler as suas predefinições

GET /v1/node-presets retorna { data: NodePreset[] }, da mais nova para a mais antiga. Envie nodeType, por exemplo generate-image, para listar as predefinições de um tipo de nó.

curl "https://app.nodaro.ai/v1/node-presets?nodeType=generate-image" \
  -H "Authorization: Bearer $NODARO_API_KEY"

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

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

const presets = await client.presets.list('generate-image')
const cinematic = presets.find((p) => p.name === 'Cinematic Portrait')
const groups = await client.presets.listGroups('generate-image')

{
  "data": [
    {
      "id": "7e2c4a9f-1b3d-4f6a-8c5e-2d9b7a1f3c4e",
      "nodeType": "generate-image",
      "name": "Cinematic Portrait",
      "description": "Warm key light, shallow depth of field",
      "data": {
        "provider": "nano-banana-pro",
        "aspectRatio": "3:4",
        "resolution": "2K",
        "prompt": "cinematic portrait, warm key light, 85mm, shallow depth of field"
      },
      "groupId": null,
      "tags": ["portrait"],
      "sortOrder": 0,
      "createdAt": "2026-09-14T08:12:40Z",
      "updatedAt": "2026-09-14T08:12:40Z"
    }
  ]
}

Ler o catálogo integrado

GET /v1/node-presets/factory?nodeType=generate-image retorna { data: FactoryPreset[] }, as predefinições que vêm com o Nodaro para esse tipo de nó. Cada entrada é { id, name, description?, group?, groupKind?, data }. Um ID de fábrica tem o formato <node-type>/<name>, por exemplo generate-image/character-board ou generate-video/orbit-360.

curl "https://app.nodaro.ai/v1/node-presets/factory?nodeType=generate-video" \
  -H "Authorization: Bearer $NODARO_API_KEY"

const { data } = await client.presets.listFactory('generate-video')
const orbit = data.find((p) => p.id === 'generate-video/orbit-360')

Aplicar uma predefinição

O data de uma predefinição é uma configuração de nó capturada. Para aplicar uma predefinição, mescle o data dela nos dados do nó ao criar ou atualizar um workflow. Os valores que você define no nó depois da mesclagem prevalecem.

const node = {
  id: 'portrait-1',
  type: 'generate-image',
  data: { ...cinematic.data, prompt: 'a lighthouse keeper at dawn' },
}

Uma predefinição também pode trazer promptPrefix e promptSuffix: texto adicionado antes e depois do prompt quando o nó é executado. Veja Texto antes e depois do prompt.

Pelo MCP, encontre uma predefinição com list_node_presets e leia-a com get_node_preset, ou passe o presetId dela direto para uma ferramenta de geração, como generate_image. O servidor então aplica a predefinição, envolve o seu prompt com o prefixo e o sufixo da predefinição e deixa qualquer campo que você passa explicitamente substituí-la. Veja a Referência das ferramentas MCP.

Favoritos

Os favoritos colocam as predefinições marcadas com estrela no topo da lista de predefinições do editor. Um ID de favorito é um ID de predefinição de fábrica ou o uuid de uma predefinição personalizada. As leituras aceitam tokens de app OAuth com presets:read; as gravações aceitam só uma sessão do navegador, e nenhum escopo OAuth dá acesso a elas.

Os IDs de fábrica contêm uma /, então codifique presetId para URL na query string do DELETE:

curl -X DELETE "https://app.nodaro.ai/v1/node-presets/favorites?nodeType=generate-image&presetId=generate-image%2Fcharacter-board" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Criar e editar predefinições

Criar, renomear e excluir predefinições só é possível com a própria sessão conectada do app web do Nodaro: POST /v1/node-presets cria uma predefinição, PATCH /v1/node-presets/:id renomeia a predefinição ou substitui os dados dela, e DELETE /v1/node-presets/:id a exclui. Um token de API ou um token de app OAuth recebe 403 forbidden.

Essas gravações aceitam um expectedUpdatedAt opcional: no corpo de um PATCH e como parâmetro de consulta de um DELETE. Envie o timestamp que a biblioteca de predefinições retornou. Quando a predefinição mudou desde então, a rota retorna 409 conflict; leia a predefinição de novo antes de tentar outra vez.

Predefinições de renderização do Recast

A mesma biblioteca guarda configurações de geração do Recast no namespace recast-render. Ele não é um tipo de nó: ele salva um conjunto completo de configurações de renderização do Recast para que você possa reutilizá-las. As entradas de fábrica são somente leitura, e as suas próprias entradas ficam privadas para você em todos os dispositivos.

O data de uma predefinição recast-render é um snapshot estrito e completo:

{
  "schemaVersion": 1,
  "provider": "seedance-2-5",
  "resolution": "480p",
  "segmentSec": "max",
  "renderMethod": "extend",
  "anchorMode": "upfront",
  "citeStyle": "bare",
  "promptTiming": true,
  "textOnly": false,
  "interactive": true,
  "anchorGates": false,
  "musicGates": true,
  "musicSource": "generated"
}

Campos e versões de schema desconhecidos são recusados. O snapshot nunca contém mídia de origem, referências do elenco, prompts, faixas enviadas, confirmações de direitos nem resultados. Aplicar uma predefinição altera as configurações e atualiza a cotação de preço; isso nunca inicia uma geração. Uma escolha de música Original ou Upload usa a mídia do próprio projeto de destino. Verifique os recursos atuais do modelo escolhido antes de gerar.

Erros