Prompt Wizard

The Prompt Wizard API turns a rough idea into an optimized prompt for a generation node. One endpoint, POST /v1/prompt-helper/wizard, does three things, chosen by the action field. It asks guided questions (analyze), builds a prompt from your answers (generate), or rewrites a prompt in one step (enhance). It is the same wizard the editor opens from the AI button on a prompt field.

The route works on every edition and takes a bearer token. Each call holds credits for one language-model call, then is charged for the tokens it used. See Authentication.

Endpoints

Ask for guided questions

analyze reads your idea and the target node type, and returns questions about what would most improve the prompt: the subject, the lighting, the camera, the mood and more. Each question comes with suggested answers, and the best one is selected when the wizard can tell. Omit prompt to start from scratch; the wizard then picks the key questions and selects nothing.

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
    }
  ]
}

A response holds 1 to 12 questions. Each question is { category, label, options, selected, allowCustom, multi? }:

Build a prompt from the answers

generate builds one optimized prompt from your answers. Send one selection per answered question, { category, value, isCustom }; set isCustom to true when value is your own words. Add originalPrompt to weave the original idea into the result.

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 appears when the wizard can suggest a model for the target node: provider is the model id to set, label its name and reason the explanation. A node type with only one model gets no recommendation.

Improve a prompt in one call

enhance skips the questions and returns the optimized prompt directly. It takes the same fields as analyze, without selections.

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

Request fields

An unsupported or omitted reasoningEffort uses the model's own default. advancedMode on a model that is not a Gemini or Claude model returns 400 advanced_mode_unsupported. While the model's own provider cannot take requests, advancedMode is refused with advanced_mode_unavailable instead of running on the default lane. See the Generate Text - Any LLM node for the language models.

Credits

Each call is one language-model call. It is charged for the tokens it actually used, at the rate of llmModel on the lane that served it. A hold is reserved when the call starts, and the call is then charged what it used. POST /v1/credits/model-costs returns an estimate of a typical call, with the key prompt-helper:<model>. Show it as ≈N. A guided flow costs two calls: analyze, then generate. Asking for new questions costs another call. A failed call the provider billed, such as a refusal, is charged for that usage. A failed call the provider did not bill is refunded. See How LLM calls are charged.

Use it from MCP

AI assistants use the same endpoint through analyze_prompt, generate_prompt and enhance_prompt, with the workflows:execute scope. The tools take the same fields, with advanced_mode, temperature and max_tokens for Gemini and Claude models. See the MCP tools reference.

Errors