Assistente de prompt

A API do assistente de prompt (Prompt Wizard) transforma uma ideia bruta em um prompt otimizado para um nó de geração. Um único endpoint, POST /v1/prompt-helper/wizard, faz três coisas, escolhidas pelo campo action. Ele faz perguntas guiadas (analyze), monta um prompt a partir das suas respostas (generate) ou reescreve um prompt em um passo (enhance). É o mesmo assistente que o editor abre pelo botão de IA de um campo de prompt.

A rota funciona em todas as edições e recebe um bearer token. Cada chamada reserva créditos para uma chamada a um modelo de linguagem. Veja Autenticação.

Endpoints

Pedir perguntas guiadas

analyze lê a sua ideia e o tipo de nó de destino e retorna perguntas sobre o que mais melhoraria o prompt: o assunto, a iluminação, a câmera, o clima e mais. Cada pergunta vem com respostas sugeridas, e a melhor fica selecionada quando o assistente consegue identificá-la. Omita prompt para começar do zero; o assistente então escolhe as perguntas principais e não seleciona nada.

curl -X POST https://app.nodaro.ai/v1/prompt-helper/wizard \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "analyze",
    "nodeType": "generate-image",
    "prompt": "a snow leopard on a ridge",
    "provider": "nano-banana-pro",
    "aspectRatio": "16:9"
  }'

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

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

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

nodaro prompt analyze --node-type generate-image --prompt "a snow leopard on a ridge" --json

# Interactive questions and answers in the terminal:
nodaro prompt wizard --node-type generate-image --prompt "a snow leopard on a ridge"

{
  "jobId": "3b7d1f9a-5c2e-4a8b-9d6f-1e4c7a2b5d8f",
  "questions": [
    {
      "category": "lighting",
      "label": "Lighting",
      "options": [
        { "value": "golden-hour", "label": "Golden hour", "description": "Low warm sun, long shadows" },
        { "value": "overcast", "label": "Overcast", "description": "Soft, even light" },
        { "value": "blizzard", "label": "Blizzard haze", "description": "Flat light through blowing snow" }
      ],
      "selected": "golden-hour",
      "allowCustom": true
    }
  ]
}

Uma resposta traz de 1 a 12 perguntas. Cada pergunta é { category, label, options, selected, allowCustom, multi? }:

Montar um prompt a partir das respostas

generate monta um prompt otimizado a partir das suas respostas. Envie uma seleção por pergunta respondida, { category, value, isCustom }; defina isCustom como true quando value tiver as suas próprias palavras. Adicione originalPrompt para incorporar a ideia original ao resultado.

curl -X POST https://app.nodaro.ai/v1/prompt-helper/wizard \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "generate",
    "nodeType": "generate-image",
    "originalPrompt": "a snow leopard on a ridge",
    "selections": [
      { "category": "lighting", "value": "golden-hour", "isCustom": false },
      { "category": "camera", "value": "telephoto from below, 400mm", "isCustom": true }
    ]
  }'

const { prompt, recommendedModel } = await client.promptHelper.generate({
  nodeType: 'generate-image',
  originalPrompt: 'a snow leopard on a ridge',
  selections: [
    { category: 'lighting', value: 'golden-hour', isCustom: false },
    { category: 'camera', value: 'telephoto from below, 400mm', isCustom: true },
  ],
})

nodaro prompt generate --node-type generate-image \
  --original-prompt "a snow leopard on a ridge" \
  --selection lighting=golden-hour --selection camera="telephoto from below, 400mm" --json

{
  "jobId": "9e1a3c5b-7d2f-4b6a-8c4e-2f5d8b1a3c7e",
  "prompt": "A snow leopard stands on a rocky ridge at golden hour, low warm sun raking across its spotted coat, shot from below on a 400mm telephoto lens, snow dust drifting in the backlight.",
  "recommendedModel": {
    "provider": "nano-banana-pro",
    "field": "provider",
    "label": "Nano Banana Pro",
    "reason": "Strong fine detail for fur and snow texture."
  }
}

recommendedModel aparece quando o assistente consegue sugerir um modelo para o nó de destino: provider é o ID do modelo a definir, label é o nome dele e reason é a explicação. Um tipo de nó com um único modelo não recebe recomendação.

Melhorar um prompt em uma chamada

enhance pula as perguntas e retorna o prompt otimizado diretamente. Ele aceita os mesmos campos que analyze, sem seleções.

curl -X POST https://app.nodaro.ai/v1/prompt-helper/wizard \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "enhance", "nodeType": "text-to-video", "prompt": "a paper boat in a rainy street", "duration": 5 }'

const { prompt } = await client.promptHelper.enhance({
  nodeType: 'generate-image',
  prompt: 'a snow leopard',
})
const image = await client.nodes.runAndWait('generate-image', { prompt })

PROMPT=$(nodaro prompt enhance --node-type generate-image --prompt "snow leopard" --json | jq -r '.prompt')
nodaro nodes run generate-image --param prompt="$PROMPT" --watch

Campos da requisição

Um reasoningEffort não aceito ou omitido usa o padrão do próprio modelo. advancedMode em um modelo que não é Gemini retorna 400 advanced_mode_unsupported. Veja o nó Prompt para conhecer os modelos de linguagem e os níveis deles.

Créditos

Cada chamada é uma chamada a um modelo de linguagem, com preço pelo nível de llmModel, e os créditos são reservados quando a chamada começa. Um fluxo guiado custa duas chamadas: analyze e depois generate. Pedir novas perguntas custa mais uma chamada. Quando uma chamada falha com 500 ou 502, os créditos dela são reembolsados.

Usar pelo MCP

Os assistentes de IA usam o mesmo endpoint por meio de analyze_prompt, generate_prompt e enhance_prompt, com o escopo workflows:execute. As ferramentas aceitam os mesmos campos, com advanced_mode, temperature e max_tokens para modelos Gemini. Veja a Referência das ferramentas MCP.

Erros