# 프롬프트 마법사

> REST로 대략적인 아이디어를 최적화된 프롬프트로 바꾸세요. 가이드 질문을 받고, 답변으로 프롬프트를 만들거나, 한 번의 호출로 프롬프트를 개선합니다.

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

**프롬프트 마법사 API**는 대략적인 아이디어를 생성 노드용 최적화 프롬프트로 바꿉니다. 엔드포인트 하나인 `POST /v1/prompt-helper/wizard`가 `action` 필드에 따라 세 가지 일을 합니다. 가이드 질문을 하거나(`analyze`), 답변으로 프롬프트를 만들거나(`generate`), 한 번에 프롬프트를 다시 씁니다(`enhance`). 편집기에서 프롬프트 필드의 AI 버튼으로 여는 것과 같은 마법사입니다.

이 라우트는 모든 에디션에서 작동하며 Bearer 토큰을 받습니다. 각 호출은 언어 모델 호출 한 번분의 크레딧을 예약합니다. [인증](https://nodaro.ai/docs/developers/api/authentication)을 참조하세요.

## 엔드포인트
| 메서드 | 경로 | `action` | 반환 |
| --- | --- | --- | --- |
| `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? }` |

## 가이드 질문 받기
`analyze`는 내 아이디어와 대상 노드 타입을 읽고, 프롬프트를 가장 많이 개선할 수 있는 질문을 반환합니다. 피사체, 조명, 카메라, 분위기 등에 대한 질문입니다. 각 질문에는 추천 답변이 딸려 있으며, 마법사가 판단할 수 있으면 가장 좋은 답변이 선택되어 있습니다. 처음부터 시작하려면 `prompt`를 생략하세요. 그러면 마법사가 핵심 질문을 고르고 아무것도 선택하지 않습니다.

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

응답에는 질문이 1~12개 들어 있습니다. 각 질문은 `{ category, label, options, selected, allowCustom, multi? }`입니다.

| 필드 | 담는 내용 |
| --- | --- |
| `category` | 질문의 ID입니다. 답변에 이 값을 다시 보내세요. |
| `label` | 사람에게 보여 주는 질문 문구입니다. |
| `options` | 추천 답변으로, 각각 `{ value, label, description? }`입니다. |
| `selected` | 추천 답변의 `value`입니다. `multi`가 `true`이면 값 목록이고, 추천이 없으면 `null`입니다. |
| `allowCustom` | 직접 쓴 답변을 허용하는지 여부입니다. |
| `multi` | 답변을 여러 개 고를 수 있을 때 있으며, 값은 `true`입니다. |

## 답변으로 프롬프트 만들기
`generate`는 내 답변으로 최적화된 프롬프트 하나를 만듭니다. 답한 질문마다 선택을 하나씩 `{ category, value, isCustom }` 형태로 보내세요. `value`가 직접 쓴 말이면 `isCustom`을 `true`로 설정하세요. 원래 아이디어를 결과에 녹여 넣으려면 `originalPrompt`를 추가하세요.

**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`은 마법사가 대상 노드에 맞는 모델을 추천할 수 있을 때 나타납니다. `provider`는 설정할 모델 ID, `label`은 그 이름, `reason`은 설명입니다. 모델이 하나뿐인 노드 타입은 추천을 받지 않습니다.

## 한 번의 호출로 프롬프트 개선
`enhance`는 질문을 건너뛰고 최적화된 프롬프트를 바로 반환합니다. `analyze`와 같은 필드를 받으며, 선택은 받지 않습니다.

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

## 요청 필드
<TypeTable
type={{
action: { type: "'analyze' | 'generate' | 'enhance'", description: '마법사가 하는 일입니다.', required: true },
nodeType: { type: 'string', description: '프롬프트를 쓸 노드입니다. 예를 들어 generate-image, text-to-video, generate-music입니다. 질문과 모델 추천이 이 값에 따라 달라집니다.', required: true },
prompt: { type: 'string', description: 'analyze와 enhance: 대략적인 아이디어로, 최대 5,000자입니다.' },
selections: { type: 'array', description: 'generate 전용이며 하나 이상 필요합니다. 답한 질문마다 { category, value, isCustom }입니다.' },
originalPrompt: { type: 'string', description: 'generate 전용: 녹여 넣을 원래 아이디어로, 최대 5,000자입니다.' },
provider: { type: 'string', description: '프롬프트를 실행할 모델로, 문구가 이 모델에 맞춰집니다.' },
style: { type: 'string', description: '노드에서 이미 선택한 스타일입니다.' },
aspectRatio: { type: 'string', description: '프롬프트를 실행할 프레임입니다.' },
duration: { type: 'number', description: '동영상과 오디오 노드의 클립 길이(초)입니다.' },
nodeContext: { type: 'object', description: '노드에 연결된 것입니다. connectedInputTypes, referenceImageCount, referenceImageUrls(최대 10개), hasSourceVideo입니다. 마법사는 입력이 이미 다루는 내용을 건너뜁니다.' },
llmModel: { type: 'string', description: '마법사를 실행하는 언어 모델입니다. 가격 등급을 정합니다.' },
reasoningEffort: { type: "'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'", description: '지원하는 모델에서 모델이 생각하는 시간입니다. xhigh와 max는 한 등급 위로 청구되지만, 프리미엄 모델은 프리미엄 그대로입니다. Claude 모델에서는 어떤 추론 강도든 한 단계 더 위로 청구되며, 최대 premium-direct까지입니다.' },
advancedMode: { type: 'boolean', description: "Gemini와 Claude 모델: 모델 제작사의 자체 API로 실행해 temperature, maxTokens, 전체 추론 범위를 적용합니다. 한 단계 위로 청구되며, 프리미엄 모델은 premium-direct 가격으로 올라갑니다." },
temperature: { type: 'number', description: 'advancedMode 사용 시: 샘플링 온도입니다.' },
maxTokens: { type: 'number', description: 'advancedMode 사용 시: 답변의 최대 길이입니다.' },
}}
/>

지원되지 않거나 생략한 `reasoningEffort`는 모델 자체의 기본값을 사용합니다. Gemini나 Claude 모델이 아닌 모델에 `advancedMode`를 보내면 `400 advanced_mode_unsupported`가 반환됩니다. 언어 모델과 그 등급은 [텍스트 생성 - 모든 LLM](https://nodaro.ai/docs/nodes/automate/prompt) 노드를 참조하세요.

## 크레딧
각 호출은 언어 모델 호출 한 번이며, `llmModel`의 등급에 따라 가격이 정해지고, 호출이 시작될 때 크레딧이 예약됩니다. 가이드 흐름은 `analyze` 다음 `generate`로 두 번의 호출이 듭니다. 새 질문을 요청하면 호출이 한 번 더 듭니다. 호출이 `500` 또는 `502`로 실패하면 크레딧이 환불됩니다.

## MCP에서 사용
AI 어시스턴트는 `workflows:execute` 스코프로 `analyze_prompt`, `generate_prompt`, `enhance_prompt`를 통해 같은 엔드포인트를 사용합니다. 이 도구들은 같은 필드를 받으며, Gemini와 Claude 모델에서는 `advanced_mode`, `temperature`, `max_tokens`도 받습니다. [MCP 도구 레퍼런스](https://nodaro.ai/docs/mcp/tools)를 참조하세요.

## 오류
| 상태 | 코드 | 의미 |
| --- | --- | --- |
| `400` | `validation_error` | 본문이 잘못되었습니다. 예를 들어 알 수 없는 `action`이거나 선택이 없는 `generate`입니다. |
| `400` | `advanced_mode_unsupported` | Gemini나 Claude 모델이 아닌 모델에 `advancedMode`를 보냈습니다. |
| `401` | `unauthorized` | 토큰이 없거나, 잘못되었거나, 폐기되었습니다. |
| `402` | `insufficient_credits` | Nodaro Cloud 전용입니다. 계정의 크레딧이 호출에 부족합니다. |
| `500` | `llm_error` | 언어 모델 호출이 실패했습니다. 크레딧이 환불됩니다. 백오프를 두고 다시 시도하세요. |
| `502` | `malformed_response` | 모델의 답변을 사용할 수 없었습니다. 크레딧이 환불됩니다. |
| `503` | `provider_unavailable` | 이 인스턴스에 구성된 언어 모델이 없습니다. |

## 자주 묻는 질문

### analyze, generate, enhance는 무엇이 다른가요?

analyze는 대략적인 아이디어를 추천 답변이 딸린 몇 가지 가이드 질문으로 바꿉니다. generate는 내가 고른 답변으로 최적화된 프롬프트 하나를 만듭니다. enhance는 질문을 건너뛰고 한 번의 호출로 프롬프트를 다시 씁니다.

### 프롬프트 마법사의 비용은 얼마인가요?

각 호출은 언어 모델 호출 한 번이며, llmModel로 선택한 모델의 등급에 따라 가격이 정해집니다. 전체 가이드 흐름은 analyze 다음 generate로 두 번의 호출입니다. 새 질문을 요청하면 호출이 한 번 더 듭니다.

### 프롬프트 마법사가 모델을 추천하나요?

대개 그렇습니다. generate와 enhance는 recommendedModel을 반환할 수 있으며, 여기에 대상 노드에 맞는 모델과 그 이유가 나옵니다. 모델이 하나뿐인 노드 타입은 추천을 받지 않습니다.

### 마법사는 어떤 노드 타입을 지원하나요?

generate-image, image-to-video, generate-music처럼 프롬프트를 받는 생성 노드입니다. 질문과 모델 추천이 노드에 맞도록 노드 타입을 nodeType으로 전달하세요.