# אשף הפרומפטים

> הפכו רעיון גולמי לפרומפט משופר ב-REST API של Nodaro: קבלו שאלות מנחות, בנו פרומפט מהתשובות או שפרו פרומפט בקריאה אחת.

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

**ה-API של אשף הפרומפטים** הופך רעיון גולמי לפרומפט משופר לרכיב יצירה. נקודת קצה אחת, `POST /v1/prompt-helper/wizard`, עושה שלושה דברים, לפי הערך בשדה `action`. היא שואלת שאלות מנחות (`analyze`), בונה פרומפט מהתשובות שלכם (`generate`) או משכתבת פרומפט בצעד אחד (`enhance`). זה אותו אשף שהעורך פותח מכפתור ה-AI שבשדה הפרומפט.

הנתיב עובד בכל המהדורות ומקבל אסימון Bearer. לכל קריאה משוריינים קרדיטים של קריאה אחת למודל שפה, ואחר כך היא מחויבת לפי הטוקנים שהיא השתמשה בהם. ראו את דף ה-API [אימות](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` | המזהה של השאלה. שלחו אותו בחזרה בתשובה שלכם. |
| `label` | השאלה, בניסוח שמוצג לאדם. |
| `options` | התשובות המוצעות, כל אחת `{ value, label, description? }`. |
| `selected` | ה-`value` של התשובה המוצעת, רשימה של ערכים כש-`multi` הוא `true`, או `null` כשאין הצעה. |
| `allowCustom` | האם מותר לענות במילים שלכם. |
| `multi` | מופיע, עם הערך `true`, כשאפשר לבחור כמה תשובות. |

## בניית פרומפט מהתשובות
הפעולה `generate` בונה פרומפט משופר אחד מהתשובות שלכם. שלחו בחירה אחת לכל שאלה שעניתם עליה, `{ category, value, isCustom }`; הגדירו את `isCustom` ל-`true` כשהשדה `value` הוא ניסוח שלכם. הוסיפו את `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` הוא מזהה המודל שצריך להגדיר, השדה `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: 'כמה זמן המודל חושב, במודלים שתומכים בכך. לרמת המאמץ אין מחיר משלה: רמה גבוהה יותר עולה יותר רק בגלל הטוקנים שהמודל כותב. במודל Claude, עם כל רמת מאמץ הקריאה רצה ב-API של Anthropic עצמה, בתעריף של אותו שירות.' },
advancedMode: { type: 'boolean', description: 'מודלי Gemini ו-Claude: מריץ את הקריאה ב-API של יצרן המודל עצמו, כך ש-temperature ו-maxTokens חלים עליה, וכל רמות החשיבה זמינות. הקריאה מחויבת בתעריף של אותו שירות.' },
temperature: { type: 'number', description: 'עם advancedMode: טמפרטורת הדגימה.' },
maxTokens: { type: 'number', description: 'עם advancedMode: האורך המרבי של התשובה.' },
}}
/>

כשהשדה `reasoningEffort` לא נתמך או לא נשלח, המודל משתמש בברירת המחדל שלו. בקשה עם `advancedMode` למודל שהוא לא מודל Gemini או Claude נדחית עם `400 advanced_mode_unsupported`. כל עוד הספק של המודל עצמו לא יכול לקבל בקשות, בקשה עם `advancedMode` נדחית עם `advanced_mode_unavailable`, והקריאה לא עוברת לרוץ בשירות ברירת המחדל. ראו את הדף של רכיב [יצירת טקסט - כל LLM](https://nodaro.ai/docs/nodes/automate/prompt) לרשימת מודלי השפה.

## קרדיטים
כל קריאה היא קריאה אחת למודל שפה. היא מחויבת לפי הטוקנים שהיא השתמשה בהם בפועל, בתעריף של `llmModel` בשירות שטיפל בה. כשהקריאה מתחילה, משוריינים קרדיטים, ואחר כך הקריאה מחויבת לפי השימוש בפועל. הנתיב `POST /v1/credits/model-costs` מחזיר אומדן של קריאה טיפוסית, תחת המפתח `prompt-helper:<model>`. הציגו אותו כ-`≈N`. שימוש באשף עם שאלות כולל שתי קריאות: קודם `analyze` ואחר כך `generate`. בקשה לשאלות חדשות היא קריאה נוספת. על קריאה שנכשלה והספק חייב עליה, כגון סירוב, משלמים לפי השימוש הזה. על קריאה שנכשלה והספק לא חייב עליה, הקרדיטים מוחזרים. ראו את הסעיף [איך מחויבות קריאות LLM](https://nodaro.ai/docs/concepts/credits#llm-calls) בדף קרדיטים.

## שימוש דרך MCP
עוזרי AI משתמשים באותה נקודת קצה דרך הכלים `analyze_prompt`, `generate_prompt` ו-`enhance_prompt`, עם ההרשאה `workflows:execute`. הכלים מקבלים את אותם שדות, ובמודלי Gemini ו-Claude גם את `advanced_mode`, `temperature` ו-`max_tokens`. ראו את [מדריך כלי ה-MCP](https://nodaro.ai/docs/mcp/tools).

## שגיאות
| סטטוס | קוד | משמעות |
| --- | --- | --- |
| `400` | `validation_error` | גוף הבקשה לא תקין, למשל ערך לא מוכר ב-`action` או הפעולה `generate` בלי בחירות. |
| `400` | `advanced_mode_unsupported` | השדה `advancedMode` נשלח למודל שהוא לא מודל Gemini או Claude. |
| `400` | `advanced_mode_unavailable` | הספק של המודל עצמו לא יכול לקבל כרגע בקשות במצב מתקדם. לא נגבים קרדיטים. כבו את המצב המתקדם כדי להריץ את המודל. |
| `401` | `unauthorized` | האסימון חסר, לא תקין או מבוטל. |
| `402` | `insufficient_credits` | ב-Nodaro Cloud בלבד. אין בחשבון מספיק קרדיטים לשריון של הקריאה. |
| `500` | `llm_error` | הקריאה למודל השפה נכשלה. הקרדיטים מוחזרים, אלא אם הספק חייב עליה. נסו שוב, והאריכו את ההמתנה לפני כל ניסיון. |
| `502` | `advanced_mode_unavailable` | הספק של המודל עצמו דחה באמצע הדרך את הקריאה במצב מתקדם. הקרדיטים מוחזרים, אלא אם הספק חייב על הניסיון. כבו את המצב המתקדם כדי להריץ את המודל. |
| `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, כדי שהשאלות והמלצת המודל יתאימו לו.