NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
API REST

Assistente de prompt

Transforme uma ideia bruta em um prompt otimizado via REST: peça perguntas guiadas, monte um prompt com as respostas ou melhore um prompt em uma chamada.

A API do assistente de prompt 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 token Bearer. Cada chamada reserva créditos para uma chamada a um modelo de linguagem e depois é cobrada pelos tokens que usou. Veja Autenticação.

Endpoints

MétodoCaminhoactionRetorna
POST/v1/prompt-helper/wizardanalyze{ jobId, questions }
POST/v1/prompt-helper/wizardgenerate{ jobId, prompt, recommendedModel? }
POST/v1/prompt-helper/wizardenhance{ jobId, prompt, recommendedModel? }

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? }:

CampoO que guarda
categoryO ID da pergunta. Envie-o de volta na sua resposta.
labelA pergunta, como é mostrada a uma pessoa.
optionsAs respostas sugeridas, cada uma { value, label, description? }.
selectedO value da resposta sugerida, uma lista de valores quando multi é true, ou null quando nada é sugerido.
allowCustomSe você pode responder com as suas próprias palavras.
multiPresente e true quando várias respostas podem ser escolhidas.

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

Propriedade

Tipo

Um reasoningEffort não aceito ou omitido usa o padrão do próprio modelo. advancedMode em um modelo que não é Gemini nem Claude retorna 400 advanced_mode_unsupported. Enquanto o provedor do próprio modelo não aceita requisições, advancedMode é recusado com advanced_mode_unavailable em vez de ser executado na via padrão. Veja o nó Gerar texto - qualquer LLM para conhecer os modelos de linguagem.

Créditos

Cada chamada é uma chamada a um modelo de linguagem. Ela é cobrada pelos tokens que realmente usou, pela tarifa de llmModel na via que a atendeu. Uma reserva é feita quando a chamada começa, e a chamada é então cobrada pelo que usou. POST /v1/credits/model-costs retorna uma estimativa de uma chamada típica, com a chave prompt-helper:<model>. Mostre-a como ≈N. Um fluxo guiado custa duas chamadas: analyze e depois generate. Pedir novas perguntas custa mais uma chamada. Uma chamada com falha que o provedor cobrou, como uma recusa, é cobrada por esse uso. Uma chamada com falha que o provedor não cobrou é reembolsada. Veja Como as chamadas de LLM são cobradas.

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 e Claude. Veja a Referência das ferramentas MCP.

Erros

StatusCódigoSignificado
400validation_errorO corpo é inválido, por exemplo uma action desconhecida ou um generate sem seleções.
400advanced_mode_unsupportedadvancedMode foi enviado para um modelo que não é Gemini nem Claude.
400advanced_mode_unavailableO provedor do próprio modelo não consegue aceitar requisições do Modo avançado agora. Nada é cobrado. Desative o Modo avançado para executar o modelo.
401unauthorizedO token está ausente, é inválido ou foi revogado.
402insufficient_creditsSó no Nodaro Cloud. A conta não tem créditos para cobrir a reserva da chamada.
500llm_errorA chamada ao modelo de linguagem falhou. Ela é reembolsada, a menos que o provedor a tenha cobrado. Tente de novo, com intervalos cada vez maiores entre as tentativas.
502advanced_mode_unavailableO provedor do próprio modelo recusou a chamada do Modo avançado no meio. Ela é reembolsada, a menos que o provedor tenha cobrado a tentativa. Desative o Modo avançado para executar o modelo.
502malformed_responseNão foi possível usar a resposta do modelo. Ela é reembolsada, a menos que o provedor tenha cobrado a chamada.
503provider_unavailableNenhum modelo de linguagem está configurado nesta instância.

Perguntas frequentes

Qual é a diferença entre analyze, generate e enhance?

analyze transforma uma ideia bruta em algumas perguntas guiadas com respostas sugeridas. generate monta um prompt otimizado a partir das respostas que você escolhe. enhance pula as perguntas e reescreve o prompt em uma única chamada.

Quanto custa o assistente de prompt?

Cada chamada é uma chamada a um modelo de linguagem, cobrada pelos tokens que usou, pela tarifa do modelo que você escolhe em llmModel. Um fluxo guiado completo são duas chamadas, analyze e depois generate. Pedir novas perguntas custa mais uma chamada.

O assistente de prompt recomenda um modelo?

Muitas vezes. generate e enhance podem retornar recommendedModel, que indica um modelo para o nó de destino e explica o motivo. Um tipo de nó com um único modelo não recebe recomendação.

Quais tipos de nó o assistente aceita?

Nós de geração que recebem um prompt, como generate-image, image-to-video e generate-music. Passe o tipo de nó em nodeType para que as perguntas e a recomendação de modelo se ajustem a ele.

Última atualização

Nesta página