Predefinições
Crie, atualize, importe, reordene e exclua predefinições de nós via REST, leia o catálogo integrado público com imagens de exemplo e gerencie os favoritos.
A API de predefinições lê e grava as suas predefinições de nós, as pastas delas e os seus favoritos, e lê 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. O data de uma predefinição é a configuração de nó capturada: mescle-o nos dados de um nó para aplicá-la.
As rotas funcionam em todas as edições. Elas recebem um bearer token: um token de API pessoal (ndr_…), um token de app OAuth ou o seu token de sessão. Um token de app OAuth precisa de presets:read para as leituras e de assets:write para as gravações. O catálogo integrado, GET /v1/node-presets/factory, não exige nenhum token. Um token pessoal limitado a alguns workflows não alcança as suas próprias predefinições (403 forbidden), mas lê o catálogo como qualquer pessoa. Veja Autenticação e, para saber o que as predefinições fazem no editor, Predefinições.
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-presets/factory | O catálogo integrado de um tipo de nó. nodeType é obrigatório. Não exige token. |
GET | /v1/node-presets/factory/groups | As categorias do catálogo integrado de um tipo de nó, sem as predefinições. nodeType é obrigatório. Não exige token. |
GET | /v1/node-presets/favorites | Os IDs das predefinições que você marcou com estrela para um tipo de nó. nodeType é obrigatório. |
GET | /v1/node-preset-groups | As suas pastas e seções de predefinições. Filtro nodeType opcional. |
POST | /v1/node-presets | Cria uma predefinição. |
PATCH | /v1/node-presets/:id | Renomeia uma predefinição, substitui os dados dela, move-a ou define a imagem dela. |
DELETE | /v1/node-presets/:id | Exclui uma predefinição e as entradas de favorito dela. |
POST | /v1/node-presets/import | Cria até 500 predefinições de uma vez. |
POST | /v1/node-presets/reorder | Define posições e move predefinições entre pastas. |
POST | /v1/node-presets/favorites | Marca uma predefinição com estrela. |
DELETE | /v1/node-presets/favorites | Remove uma estrela. |
POST | /v1/node-preset-groups | Cria uma pasta ou uma seção. |
PATCH | /v1/node-preset-groups/:id | Renomeia ou move uma pasta. |
DELETE | /v1/node-preset-groups/:id | Exclui uma pasta. As predefinições dela saem da pasta, e nenhuma é excluída. |
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,
"minReferences": 0,
"needsImage": false,
"previewUrl": null,
"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. |
minReferences | Quantas imagens de referência conectadas a predefinição usa. 0 significa nenhuma. |
needsImage | true quando minReferences é pelo menos 1. |
previewUrl | A cópia própria da predefinição da imagem de exemplo que você deu a ela, ou null. |
createdAt, updatedAt | Timestamps. Envie updatedAt de volta como expectedUpdatedAt em uma gravação. |
Fotos que uma predefinição usa
Execute uma predefinição cujo minReferences é maior que 0 com essa quantidade de imagens de referência anexadas. Sem elas, o prompt da predefinição descreve uma foto que não está lá. Com presetId em POST /v1/generate-image, envie as imagens como referenceImageUrls.
As predefinições Folha de referência, Elenco e consistência, Edição por nome, Privacidade facial, Edições, Transformações de retrato e Assunto estilizado precisam de uma imagem, e a Megagrade do elenco precisa de duas. O mesmo vale para todo template cujo prompt usa tokens {image:N}: a contagem dele é o maior N. Uma predefinição sua é contada do mesmo jeito, a partir dos tokens {image:N} e {image:N:label} no prompt, no texto antes e depois dele e no prompt negativo.
Ler o catálogo integrado
GET /v1/node-presets/factory?nodeType=generate-image retorna { data: [...] }, as predefinições que vêm com o Nodaro para esse tipo de nó. Cada entrada é { id, name, description?, group?, groupKind?, section?, platforms?, data, minReferences, needsImage, previewUrl, previewSrcSet?, previewWidth?, previewHeight? }. Um ID de fábrica tem o formato <node-type>/<name>, por exemplo generate-image/character-board ou generate-video/orbit-360.
O catálogo não exige token. Ele é igual para todos e não contém dados de usuários, então um app cliente pode mostrá-lo a visitantes que não entraram na conta e pedir o login só quando eles gerarem algo. A resposta é enviada com Cache-Control: public, max-age=300, e um token inválido ou expirado enviado com a requisição é ignorado.
O previewUrl de uma predefinição de fábrica é uma imagem de exemplo no servidor que você consultou, no formato https://<host>/preset-previews/<nodeType>/<slug>.<hash>.webp, ou null enquanto a predefinição não tem imagem. O nome do arquivo muda sempre que a imagem muda, então você pode guardar uma URL em cache para sempre.
Uma predefinição que a própria implantação inclui traz a imagem que a implantação indicou. Ela é uma URL absoluta, ou um caminho no site da implantação, como /brand/presets/harbor.webp, para um arquivo que ela publica ali. As rotas REST, /factory e os previewUrl e previewUrls de /factory/groups informam esse caminho como ele é. Uma página que o site serve o usa como veio. Qualquer outro cliente o resolve a partir do endereço em que chamou a API. As ferramentas MCP o informam como uma URL absoluta.
# The presets that need a photo, and their example pictures. No token needed.
curl -s "https://app.nodaro.ai/v1/node-presets/factory?nodeType=generate-image" \
| jq '.data[] | select(.needsImage) | {id, minReferences, previewUrl}'const { data } = await client.presets.listFactory('generate-video')
const orbit = data.find((p) => p.id === 'generate-video/orbit-360')Onde uma predefinição de fábrica fica
groupé a pasta, como"YouTube","Shorts · TikTok","Social & Ads","Business","Life & Events","Layout"ou"Text".section, quando presente, é um subtítulo dentro do grupo: um tema do YouTube, como"Finance & Crypto", ou"Instagram feed".platforms, quando presente, é onde o resultado deve ser publicado, do mais adequado ao menos:["TikTok", "Reels", "Shorts"],["LinkedIn"]ou["Print", "Etsy"].
Uma predefinição sem subtítulo ou sem plataforma, como um visual, um layout ou uma pasta de estúdio, omite o campo. Agrupe e filtre por section e platforms só quando eles estiverem presentes.
Listar só as categorias
GET /v1/node-presets/factory/groups?nodeType=generate-image retorna as categorias do catálogo integrado sem as predefinições. A resposta tem poucos KB, para um menu ou uma prateleira que lista as categorias. Ela não exige token. A resposta é { data: [{ group, shelf, count, previewUrl, previewUrls }] }:
| Campo | O que contém |
|---|---|
group | O nome da categoria, o mesmo do group de uma predefinição. |
shelf | A prateleira em que um seletor arquiva a categoria: video, marketing, photos, creative, life, pro, ou more para uma categoria que nenhuma prateleira cita ainda. |
count | Quantas predefinições a categoria tem. |
previewUrl | A imagem de exemplo da primeira predefinição da categoria que tem uma, ou null. |
previewUrls | As três primeiras imagens de exemplo da categoria, na ordem do catálogo, cada uma uma vez. Fica vazio quando nenhuma predefinição tem imagem. |
As categorias vêm na ordem em que um seletor as mostra: prateleira por prateleira e, dentro de uma prateleira, primeiro as categorias nomeadas, na ordem do design, depois as demais, na ordem do catálogo.
Tamanhos da imagem
A imagem de uma predefinição de fábrica vem em dois tamanhos: a imagem do bloco em previewUrl, com 512 px de largura, e uma imagem de tela cheia com até 1024 px de largura, em /preset-previews/1024/…. previewSrcSet informa as duas com as larguras reais, pronto para um <img srcset>, para o navegador escolher pelo espaço que tem:
<img src="{previewUrl}" srcset="{previewSrcSet}" sizes="(min-width: 900px) 80vw, 100vw" alt="{name}">previewSrcSet só está presente em uma predefinição que tem os dois arquivos, e nunca em uma predefinição sua. A listagem do MCP o omite.
previewWidth e previewHeight são a largura e a altura reais da imagem do bloco. Use-as para desenhar cada imagem em uma caixa com o formato dela antes de ela carregar. O data.aspectRatio de uma predefinição é o que ela gera, que nem sempre é o formato da imagem. Estão presentes em uma predefinição integrada com imagem, e nunca em uma predefinição sua.
Aplicar uma predefinição
Para gerar uma imagem com uma predefinição, envie o ID dela como presetId em POST /v1/generate-image. O servidor aplica a predefinição do jeito que o editor a aplica a um nó Gerar imagem, e os campos que você envia a substituem. Veja Aplicar uma predefinição no Gerar imagem.
Para aplicar uma predefinição em um workflow, mescle o data dela nos dados do nó ao criar ou atualizar o 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. A leitura exige presets:read de um token de app OAuth, e as gravações exigem assets:write.
| 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 } }. Remover um favorito duas vezes não muda nada. |
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 $NODARO_API_KEY"Criar e editar predefinições
| Método | Caminho | Corpo ou parâmetros | O que faz |
|---|---|---|---|
POST | /v1/node-presets | { nodeType, name, description?, data, groupId?, tags?, sortOrder?, previewUrl? } | Cria uma predefinição. Responde 201 com a predefinição. |
PATCH | /v1/node-presets/:id | Qualquer um de name, description, data, groupId, tags, sortOrder, previewUrl, e um expectedUpdatedAt opcional | Atualiza os campos que você envia. previewUrl: null remove a imagem. |
DELETE | /v1/node-presets/:id | Parâmetro de consulta expectedUpdatedAt opcional | Exclui uma predefinição e as entradas de favorito dela. |
POST | /v1/node-presets/import | { presets: [{ nodeType, name, description?, data, previewUrl? }] }, até 500 | Cria muitas de uma vez. Retorna { data: { imported } }. |
POST | /v1/node-presets/reorder | { groups?: [{ id, sortOrder }], presets?: [{ id, groupId?, sortOrder }] } | Define posições e move predefinições entre pastas. Retorna { data: { ok: true } }. |
POST | /v1/node-preset-groups | { nodeType, name, kind?, sortOrder? } | Cria uma folder (o padrão, recolhível) ou uma section (um cabeçalho simples). |
PATCH | /v1/node-preset-groups/:id | { name?, sortOrder? } | Renomeia ou move uma pasta. |
DELETE | /v1/node-preset-groups/:id | Nenhum | Exclui uma pasta. As predefinições dela saem da pasta. |
# Save a preset of your own, with one of your images as its picture
curl -s -X POST "https://app.nodaro.ai/v1/node-presets" \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"nodeType": "generate-image", "name": "Studio portrait", "data": {"provider": "gpt-image-2", "aspectRatio": "3:4", "prompt": "{image:1:person}, studio portrait, soft key light"}, "previewUrl": "https://cdn.nodaro.ai/images/<jobId>.png"}'
# Rename it, refusing if it changed since you read it
curl -s -X PATCH "https://app.nodaro.ai/v1/node-presets/<presetId>" \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Studio portrait (warm)", "expectedUpdatedAt": "<updatedAt>"}'const preset = await client.presets.create({
nodeType: 'generate-image',
name: 'Studio portrait',
data: { provider: 'gpt-image-2', aspectRatio: '3:4', prompt: '{image:1:person}, studio portrait' },
})
preset.needsImage // true: the prompt names {image:1}
await client.presets.addFavorite({ nodeType: 'generate-image', presetId: preset.id })A CLI tem as mesmas gravações: nodaro presets create, update, delete, import, export, favorites, favorite, unfavorite, e nodaro presets groups com create, update e delete. Pelo MCP, save_node_preset, delete_node_preset e favorite_node_preset gerenciam predefinições.
Regras das gravações
- Os nomes são únicos por tipo de nó, sem diferenciar maiúsculas de minúsculas. Criar e atualizar respondem
409 name_taken. A importação mantém as duas predefinições e dá à nova o nome “… (imported 2)”. datatem no máximo 64 KB. As chaves de execução, como resultados, IDs de tarefas e o rótulo do nó, são removidas. Uma predefinição importada que fica sem nada é ignorada.groupIdprecisa ser uma das suas pastas, ou a gravação responde400 invalid_group.previewUrlprecisa ser uma das suas próprias imagens no Nodaro: um envio ou o resultado de uma geração concluída, em png, jpg, webp, gif ou avif. O arquivo precisa já existir, então defina-o depois que a tarefa que cria a imagem tiver sido concluída. Qualquer outra coisa responde400 validation_errorindicando o campo, por exemplopresets[3].previewUrlem uma importação.- A predefinição guarda uma cópia própria da imagem. O
previewUrlda resposta é o endereço da cópia, não o que você enviou, então excluir o original da sua biblioteca nunca quebra a predefinição. expectedUpdatedAtfaz uma atualização ou uma exclusão responder409 conflictquando a predefinição mudou desde que você a leu. Leia-a de novo antes de tentar outra vez.- Uma predefinição ou pasta que não é sua, ou um ID que não é um uuid, responde
404 not_found. - Cada conta guarda no máximo 5.000 predefinições, 500 pastas e 2.000 favoritos. Acima disso, uma criação, uma importação ou um favorito responde
409 limit_reachede não grava nada. Uma importação que não cabe inteira não importa nenhuma. - Uma reordenação move no máximo 500 predefinições e 100 pastas a partir de uma chave de API ou de um app OAuth. Mais do que isso responde
400 validation_error: envie o restante em outra chamada. - As gravações são limitadas a 60 por minuto por credencial, e as importações a 10 por minuto. Acima disso, a rota responde
429 rate_limit_exceeded.
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 instantâneo 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"
}| 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. |
Grave-as com as mesmas rotas de qualquer predefinição. Elas não precisam de fotos e não têm imagem (minReferences: 0, previewUrl: null). Campos e versões de schema desconhecidos são recusados na criação, na atualização e na importação. O instantâneo 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. |
400 | invalid_group | groupId não é uma das suas pastas. |
401 | unauthorized | O token está ausente, é inválido ou foi revogado. |
403 | forbidden | Um token pessoal limitado a alguns workflows pediu as suas próprias predefinições. |
403 | insufficient_scope | Um token de app OAuth não tem presets:read para uma leitura, ou assets:write para uma gravação. |
404 | not_found | A predefinição ou a pasta não é sua, ou o ID não é um uuid. |
409 | name_taken | Você já tem uma predefinição com esse nome para este tipo de nó. |
409 | conflict | A predefinição mudou desde expectedUpdatedAt. Leia a predefinição de novo. |
409 | limit_reached | A conta está no limite de predefinições, pastas ou favoritos. |
429 | rate_limit_exceeded | Mais de 60 gravações por minuto, ou 10 importações por minuto. |
Perguntas frequentes
Posso criar ou editar predefinições com um token de API?
Sim. Um token de API pessoal, ou um token de app OAuth com o escopo assets:write, pode criar, atualizar, excluir, importar e reordenar predefinições, e gerenciar pastas e favoritos.
Preciso de um token para ler o catálogo integrado de predefinições?
Não. GET /v1/node-presets/factory é público. Ele não contém dados de usuários, então um app pode mostrar o catálogo, com imagens de exemplo, a visitantes que não entraram na conta.
Como aplico uma predefinição pelo código?
Envie presetId em POST /v1/generate-image, e o servidor aplica a predefinição do jeito que o editor faz. Em um workflow, mescle o objeto data da predefinição nos dados do nó.
O que significa minReferences em uma predefinição?
minReferences é quantas imagens de referência conectadas a predefinição usa, e needsImage é true quando esse número é pelo menos um. Execute uma predefinição assim com essa quantidade de imagens de referência anexadas.
De quais escopos OAuth as rotas de predefinições precisam?
As leituras das suas próprias predefinições precisam de presets:read, e as gravações precisam de assets:write. O catálogo integrado não exige escopo. Os tokens de API pessoais e os tokens de sessão não precisam de escopo.
Páginas relacionadas
Predefinições
Texto antes e depois do prompt
Nós
Recast
Referência das ferramentas MCP
Última atualização
Criaturas
Crie e gerencie animais e criaturas via REST: gere imagens principais, ângulos, poses, variações e clipes de movimento, e dê uma voz à criatura.
Biblioteca da comunidade
Explore, pesquise, favorite e clone personagens, locais e objetos da Biblioteca da comunidade pela API REST, e denuncie uma publicação para moderação.