프롬프트 마법사 API: 가이드 질문, 프롬프트 작성, 한 번에 프롬프트 개선

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

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

이 라우트는 모든 에디션에서 작동하며 Bearer 토큰을 받습니다. 각 호출은 언어 모델 호출 한 번분의 크레딧을 예약합니다. 인증을 참조하세요.

엔드포인트

메서드	경로	`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 -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
    }
  ]
}

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

한 번의 호출로 프롬프트 개선

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

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

요청 필드

속성

타입

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

크레딧

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

MCP에서 사용

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

오류

상태	코드	의미
`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으로 전달하세요.

프롬프트 마법사

엔드포인트

가이드 질문 받기

답변으로 프롬프트 만들기

한 번의 호출로 프롬프트 개선

요청 필드

크레딧

MCP에서 사용

오류

자주 묻는 질문

텍스트 생성 - 모든 LLM

노드

이미지 생성

크리에이티브 컨트롤

MCP 도구 레퍼런스

목차

프롬프트 마법사

자주 묻는 질문

관련 문서

텍스트 생성 - 모든 LLM

노드

이미지 생성

크리에이티브 컨트롤

MCP 도구 레퍼런스

목차