# Predefinições

> Leia via REST as suas predefinições de nós, as pastas e o catálogo integrado de predefinições, aplique uma predefinição a um nó e gerencie os favoritos.

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

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](https://nodaro.ai/docs/developers/api/authentication) e, para saber o que as predefinições fazem no editor, [Predefinições](https://nodaro.ai/docs/concepts/presets).

## Endpoints
| Método | Caminho | O que faz |
| --- | --- | --- |
| `GET` | `/v1/node-presets` | As suas predefinições personalizadas, da mais nova para a mais antiga. Filtro `nodeType` opcional. |
| `GET` | `/v1/node-preset-groups` | As suas pastas e seções de predefinições. Filtro `nodeType` opcional. |
| `GET` | `/v1/node-presets/factory` | O catálogo integrado de um tipo de nó. `nodeType` é obrigatório. |
| `GET` | `/v1/node-presets/favorites` | Os IDs das predefinições que você marcou com estrela para um tipo de nó. `nodeType` é obrigatório. |
| `POST` | `/v1/node-presets/favorites` | Marca uma predefinição com estrela. Só com a sessão do navegador. |
| `DELETE` | `/v1/node-presets/favorites` | Remove uma estrela. Só com a sessão do navegador. |

## 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**

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

**TypeScript SDK**

```ts

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

```json
{
"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"
}
]
}
```

| Campo | O que guarda |
| --- | --- |
| `id` | O uuid da predefinição. |
| `nodeType` | O tipo de nó ao qual a predefinição pertence. |
| `name`, `description` | O nome da predefinição e uma descrição opcional. |
| `data` | A configuração de nó capturada. É isso que você aplica. |
| `groupId` | A pasta em que a predefinição está, de `GET /v1/node-preset-groups`, ou `null`. |
| `tags`, `sortOrder` | As suas tags e a posição da predefinição na lista dela. |
| `createdAt`, `updatedAt` | Timestamps. |

## 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**

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

**TypeScript SDK**

```ts
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.

```ts
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](https://nodaro.ai/docs/concepts/prompt-pre-post-text).

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](https://nodaro.ai/docs/mcp/tools).

## 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.

| Método | Caminho | Consulta ou corpo | Retorna |
| --- | --- | --- | --- |
| `GET` | `/v1/node-presets/favorites` | `nodeType` (obrigatório) | `{ data: string[] }`, do mais recente para o mais antigo |
| `POST` | `/v1/node-presets/favorites` | Corpo `{ nodeType, presetId }` | `{ data: { success: true } }`. Adicionar um favorito duas vezes não muda nada. |
| `DELETE` | `/v1/node-presets/favorites` | `nodeType` e `presetId` (ambos obrigatórios) | `{ data: { success: true } }` |

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

```bash
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](https://nodaro.ai/docs/developers/api/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:

```json
{
"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"
}
```

| Campo | Valores aceitos |
| --- | --- |
| `segmentSec` | `max`, `scenes-max` (Longos) ou `scenes` (Curtos). |
| `resolution` | `480p`, `720p`, `1080p` ou `4k`. |
| `renderMethod` | `extend` ou `keyframes`. |
| `anchorMode` | `upfront`, `progressive` ou `none`. |
| `citeStyle` | `bare` ou `rich`. |
| `musicSource` | `generated`, `original` ou `upload`. |
| `promptTiming`, `textOnly`, `interactive`, `anchorGates`, `musicGates` | `true` ou `false`. |

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
| Status | Código | Significado |
| --- | --- | --- |
| `400` | `validation_error` | `nodeType` está ausente onde é obrigatório, ou um campo é inválido. |
| `401` | `unauthorized` | O token está ausente, é inválido ou foi revogado. |
| `403` | `forbidden` | Uma gravação foi enviada com um token de API ou um token de app OAuth. As gravações precisam da sessão do navegador. |
| `403` | `insufficient_scope` | Um token de app OAuth não tem `presets:read`. |
| `409` | `conflict` | A predefinição mudou desde `expectedUpdatedAt`. Leia a predefinição de novo. |

## Frequently asked questions

### Posso criar ou editar predefinições com um token de API?

Não. Pela API, as predefinições são somente leitura para tokens de API e tokens de app OAuth. Você cria, renomeia e exclui predefinições no editor, onde a sua sessão do navegador está conectada.

### Como aplico uma predefinição a um nó pelo código?

Leia a predefinição e mescle o objeto data dela nos dados do nó ao montar ou atualizar um workflow. Pelo MCP, passe presetId para uma ferramenta de geração, como generate_image, e a predefinição é aplicada no servidor.

### Qual é a diferença entre uma predefinição personalizada e uma predefinição de fábrica?

Uma predefinição personalizada é uma que você salvou, identificada por um uuid. Uma predefinição de fábrica faz parte do catálogo integrado de um tipo de nó, identificada por um ID como generate-image/character-board.

### De qual escopo OAuth as rotas de predefinições precisam?

Os tokens de app OAuth precisam de presets:read. Os tokens de API pessoais e os tokens de sessão não precisam de escopo, porque as predefinições são suas.