# 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.

Source: https://nodaro.ai/pt-BR/docs/developers/api/prompt-wizard

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](https://nodaro.ai/docs/developers/api/authentication).

## Endpoints
| Método | Caminho | `action` | Retorna |
| --- | --- | --- | --- |
| `POST` | `/v1/prompt-helper/wizard` | `analyze` | `{ jobId, questions }` |
| `POST` | `/v1/prompt-helper/wizard` | `generate` | `{ jobId, prompt, recommendedModel? }` |
| `POST` | `/v1/prompt-helper/wizard` | `enhance` | `{ 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**

```bash
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"
}'
```

**TypeScript SDK**

```ts

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',
})
```

**CLI**

```bash
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"
```

```json
{
"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? }`:

| Campo | O que guarda |
| --- | --- |
| `category` | O ID da pergunta. Envie-o de volta na sua resposta. |
| `label` | A pergunta, como é mostrada a uma pessoa. |
| `options` | As respostas sugeridas, cada uma `{ value, label, description? }`. |
| `selected` | O `value` da resposta sugerida, uma lista de valores quando `multi` é `true`, ou `null` quando nada é sugerido. |
| `allowCustom` | Se você pode responder com as suas próprias palavras. |
| `multi` | Presente 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**

```bash
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 }
]
}'
```

**TypeScript SDK**

```ts
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 },
],
})
```

**CLI**

```bash
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
```

```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**

```bash
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 }'
```

**TypeScript SDK**

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

**CLI**

```bash
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
<TypeTable
type={{
action: { type: "'analyze' | 'generate' | 'enhance'", description: 'O que o assistente faz.', required: true },
nodeType: { type: 'string', description: 'O nó ao qual o prompt se destina, por exemplo generate-image, text-to-video ou generate-music. As perguntas e a recomendação de modelo dependem dele.', required: true },
prompt: { type: 'string', description: 'analyze e enhance: a sua ideia bruta, até 5.000 caracteres.' },
selections: { type: 'array', description: 'Só generate, pelo menos uma: { category, value, isCustom } por pergunta respondida.' },
originalPrompt: { type: 'string', description: 'Só generate: a ideia original a incorporar, até 5.000 caracteres.' },
provider: { type: 'string', description: 'O modelo em que o prompt vai ser executado, para que a redação combine com ele.' },
style: { type: 'string', description: 'O estilo já escolhido no nó.' },
aspectRatio: { type: 'string', description: 'A proporção do quadro que o prompt vai gerar.' },
duration: { type: 'number', description: 'A duração do clipe em segundos, para nós de vídeo e de áudio.' },
nodeContext: { type: 'object', description: 'O que está conectado ao nó: connectedInputTypes, referenceImageCount, referenceImageUrls (até 10) e hasSourceVideo. O assistente pula o que as entradas já cobrem.' },
llmModel: { type: 'string', description: 'O modelo de linguagem que executa o assistente. Ele define o nível de preço.' },
reasoningEffort: { type: "'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'", description: 'Quanto tempo o modelo pensa, nos modelos compatíveis. xhigh e max cobram um nível acima, com teto no premium.' },
advancedMode: { type: 'boolean', description: "Só para modelos Gemini: roda na API do próprio fabricante do modelo, para que temperature, maxTokens e toda a faixa de raciocínio se apliquem. Cobra um nível acima, com teto no premium." },
temperature: { type: 'number', description: 'Com advancedMode: a temperatura de amostragem.' },
maxTokens: { type: 'number', description: 'Com advancedMode: o tamanho máximo da resposta.' },
}}
/>

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**](https://nodaro.ai/docs/nodes/automate/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](https://nodaro.ai/docs/mcp/tools).

## Erros
| Status | Código | Significado |
| --- | --- | --- |
| `400` | `validation_error` | O corpo é inválido, por exemplo uma `action` desconhecida ou um `generate` sem seleções. |
| `400` | `advanced_mode_unsupported` | `advancedMode` foi enviado para um modelo que não é Gemini. |
| `401` | `unauthorized` | O token está ausente, é inválido ou foi revogado. |
| `402` | `insufficient_credits` | Só no Nodaro Cloud. A conta não tem créditos para cobrir a chamada. |
| `500` | `llm_error` | A chamada ao modelo de linguagem falhou. Os créditos são reembolsados; tente de novo com backoff. |
| `502` | `malformed_response` | Não foi possível usar a resposta do modelo. Os créditos são reembolsados. |
| `503` | `provider_unavailable` | Nenhum modelo de linguagem está configurado nesta instância. |

## Frequently asked questions

### 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, com preço pelo nível 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.