Seletores, predefinições e prompts

Os seletores são os nós de Controles criativos, como Clima (Mood) ou Lente (Lens), cuja escolha adiciona um texto testado ao prompt. client.pickerCatalogs e client.catalogs retornam as opções válidas de cada seletor, e analyzeText() preenche seletores a partir de uma descrição de cena. client.presets lê as configurações de nó salvas, e client.promptHelper é o Assistente de prompt (Prompt Wizard), que melhora prompts para qualquer nó de geração. Veja Controles criativos e Catálogos de seletores para os conceitos.

Métodos

client.pickerCatalogs

As listas de opções dos nós de seletor. Os dois métodos de leitura são públicos, não precisam de token e podem ser mantidos em cache pelo servidor por 5 minutos. Se o seu código pode importar @nodaro/prompts, os mesmos catálogos vêm nesse pacote como dados tipados; estes métodos são para clientes que não conseguem incluí-lo no bundle.

pickerCatalogs.list()

Lista todos os seletores (GET /v1/picker-catalogs).

list(): Promise<{ data: PickerCatalogSummary[] }>

const { data: pickers } = await client.pickerCatalogs.list()
const mood = pickers.find((p) => p.nodeType === "mood")

Cada entrada tem nodeType, label, catalogId, kind (single ou multi), valueField em um seletor de uma dimensão ou fields em um de várias dimensões, optionCount e imageCount, o número de opções com imagem.

pickerCatalogs.get(nodeType, opts?)

Lê as opções de um seletor (GET /v1/picker-catalogs/:nodeType). Um seletor de uma dimensão, como Clima, tem options. Um seletor de várias dimensões, como Pessoa (Person), tem dimensions, cada uma { field, label, options }. Alguns seletores de uma dimensão também têm configurações extras ao lado da escolha principal: transition e character-fx têm position, duration e intensity, e character-motion tem position e pace.

get(nodeType: string, opts?: { detail?: "compact" | "full"; category?: string; field?: string }): Promise<{ data: PickerCatalog }>

const { data } = await client.pickerCatalogs.get("mood", { detail: "full" })
const serene = data.options?.find((o) => o.id === "serene")
console.log(serene?.term)       // the short phrase, added in Compact mode
console.log(serene?.promptHint) // the full sentence, added in Full mode

Lança NotFoundError para um tipo de nó desconhecido.

Mostre label, adicione term. Toda opção tem um term nos dois níveis de detalhe: a expressão profissional curta a colocar em um prompt. label serve só para exibição. Nunca derive um do outro. Uma opção que não adiciona nada, como auto ou none, tem um term vazio.

Imagens. Uma opção com imagem tem um imageUrl absoluto, nos dois níveis de detalhe. person e styling também retornam sections: os temas sob os quais o editor agrupa as configurações deles, cada um { label, fields, imageUrl? }. As fotos e as artes de música e de voz são servidas pela própria instalação. As prévias renderizadas de visual vêm da CDN do Nodaro, e só o Nodaro Cloud as retorna. Os nomes dos arquivos trazem um hash do conteúdo, então você pode manter as imagens em cache sem expiração.

const { data: person } = await client.pickerCatalogs.get("person")
for (const section of person.sections ?? []) {
  const settings = person.dimensions?.filter((d) => section.fields.includes(d.field)) ?? []
  for (const setting of settings) {
    for (const option of setting.options) renderTile(option.label, option.imageUrl)
  }
}

Movimento de personagem. As opções de character-motion trazem um objeto motion opcional nos dois níveis de detalhe. Ele informa o que um movimento exige e em que estado deixa o personagem: requires, startPose e endPose, endVisibility, handsAfter, needsFreeHands, kind, fixedPace, counterpart, os aliases de busca e deprecated com um replacementId. Um campo ausente significa desconhecido. Mantenha os IDs aposentados ao carregar workflows salvos e esconda-os das novas escolhas. Veja Movimento de personagem (Character Motion).

pickerCatalogs.analyzeText(params)

Preenche as escolhas dos seletores a partir de uma descrição de cena em texto livre (POST /v1/text-to-picker), a versão em texto do nó Descrever para seletor (Describe to Picker). Retorna pickerJson, organizado por tipo de seletor e depois por dimensão, com o ID ou os IDs escolhidos. Carregue os seletores a partir dele como está e depois deixe o usuário ajustá-los. Custa créditos, cobrados como os do Descrever para seletor.

analyzeText(params: TextToPickerParams): Promise<{
  jobId: string
  pickerJson: Record<string, Record<string, string | string[]>>
  gaps?: { missingItems: object[]; missingCategories: object[] }
}>

const { pickerJson, gaps } = await client.pickerCatalogs.analyzeText({
  text: "Neon-soaked Tokyo alley at night, rain, handheld tracking shot, moody synthwave",
})
console.log(pickerJson["setting"], pickerJson["camera-motion"])

As dimensões sobre as quais o texto não diz nada ficam de fora: a análise não adivinha. gaps lista o que o texto descreve e nenhuma opção do catálogo representa bem, em missingItems e missingCategories. Mostre isso ao usuário como “não encontramos uma opção para X; escolha uma você mesmo”.

client.catalogs

catalogs.list(opts?)

Retorna todos os catálogos de seletores em uma chamada, como esta implantação os serve (GET /v1/catalogs). Uma implantação pode registrar pacotes de catálogo que substituem, ampliam ou ocultam opções. Um cliente que desenha os próprios seletores deve ler esta lista para respeitá-los. Ela é pública e pode ficar em cache por 5 minutos.

list(opts?: { detail?: "compact" | "full" }): Promise<{
  curated: boolean
  packs: number
  version: number
  data?: ProjectedCatalog[]
}>

const { curated, data } = await client.catalogs.list({ detail: "full" })
if (curated) {
  const setting = data?.find((c) => c.catalogId === "setting")
  console.log(setting?.options?.[0]?.term)
}

data só está presente quando a implantação registrou pacotes de catálogo (curated: true). Sem pacotes, os catálogos são os padrão: leia-os um por um com pickerCatalogs.get(). As opções trazem o mesmo imageUrl, e person e styling trazem as mesmas sections.

client.presets

As suas predefinições de nó salvas e as integradas, só para leitura. O data de uma predefinição são as configurações salvas de um nó. Para aplicar uma predefinição, mescle o data dela nos dados de um nó quando montar um workflow. Um token OAuth precisa do escopo presets:read. Veja Predefinições.

presets.list(nodeType?)

Lista as suas predefinições salvas, das mais recentes para as mais antigas (GET /v1/node-presets).

list(nodeType?: string): Promise<NodePreset[]>

const presets = await client.presets.list("generate-image")
const cinematic = presets.find((p) => p.name === "Cinematic Portrait")
// apply: spread cinematic.data into the node's data when you create the workflow

Um NodePreset tem id, nodeType, name, description, data, groupId, tags, sortOrder, createdAt e updatedAt.

presets.listGroups(nodeType?)

Lista as suas pastas e seções de predefinições (GET /v1/node-preset-groups).

listGroups(nodeType?: string): Promise<NodePresetGroup[]>

const groups = await client.presets.listGroups("generate-image")

Cada grupo tem id, nodeType, name, kind (folder ou section), sortOrder, createdAt e updatedAt.

presets.listFactory(nodeType)

Lista as predefinições integradas de um tipo de nó (GET /v1/node-presets/factory).

listFactory(nodeType: string): Promise<{ data: FactoryPreset[] }>

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

client.promptHelper

O Assistente de prompt: ajuda de IA para escrever prompts para nós de geração. Os três métodos enviam a requisição para POST /v1/prompt-helper/wizard, e cada chamada custa créditos. Veja Assistente de prompt para a visão REST.

Os três recebem estes campos comuns:

A CLI oferece o mesmo com nodaro prompt wizard, analyze, generate e enhance, com --llm-model e --reasoning-effort. Veja a CLI.

promptHelper.analyze(input)

Transforma uma ideia vaga em perguntas guiadas para um tipo de nó. Responda às perguntas e depois passe as respostas para generate().

analyze(input: AnalyzeInput): Promise<{ jobId: string; questions: WizardQuestion[] }>

const { questions } = await client.promptHelper.analyze({
  nodeType: "generate-image",
  prompt: "a snow leopard",
})

promptHelper.generate(input)

Monta um prompt otimizado a partir das respostas escolhidas. Cada seleção é { category, value, isCustom }.

generate(input: GenerateInput): Promise<{ jobId: string; prompt: string; recommendedModel?: RecommendedModel }>

const { prompt, recommendedModel } = await client.promptHelper.generate({
  nodeType: "generate-image",
  selections: [{ category: "subject", value: "snow leopard", isCustom: false }],
})

promptHelper.enhance(input)

Melhora um prompt em uma etapa, sem as perguntas.

enhance(input: EnhanceInput): Promise<{ jobId: string; prompt: string; recommendedModel?: RecommendedModel }>

const { prompt } = await client.promptHelper.enhance({
  nodeType: "generate-image",
  prompt: "snow leopard on a rock",
  reasoningEffort: "high",
})