> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# تحسين الموجّهات

> أعد كتابة موجّهات توليد الصور وتحريرها تلقائيًا باستخدام معامل enhance_prompt من Venice لإضافة تفاصيل بصرية توضيحية وتحسين جودة المخرجات.

يعيد تحسين الموجّهات كتابة موجّهك قبل توليد الصورة أو تحريرها لإضافة تفاصيل بصرية توضيحية، فيحوّل الأوصاف القصيرة أو الشحيحة إلى موجّهات أغنى تتّبعها نماذج الصور بموثوقية أعلى. فعّله بضبط `enhance_prompt: true` في `POST /image/generate` أو `POST /image/edit` أو `POST /image/multi-edit`.

بالنسبة لتوليد الصور، هذا هو نفس التحسين الذي يشغّل "العصا السحرية" في تطبيق Venice على الويب. أما لتحرير الصور، فإن مُحسِّنًا مدركًا للرؤية يستخدم الصورة أو الصور المُدخلة لتوضيح تعليمة التحرير الخاصة بك.

## متى تستخدمه

يكون تحسين الموجّهات مفيدًا خصوصًا عندما:

* يكون موجّهك قصيرًا (بضع كلمات أو عبارة واحدة) وتريد من النموذج أن يملأ التركيبة والإضاءة والأجواء.
* تبني منتجًا يكتب فيه المستخدمون النهائيون موجّهات عادية تستفيد من التوسيع.
* تحرّر صورة وتريد إعادة كتابة التعليمة مع الوعي بمحتواها المرئي.
* تريد مخرجات أكثر تفصيلًا وثباتًا دون كتابة موجّهات طويلة يدويًا.

إذا كنت ترسل بالفعل موجّهات طويلة ومصاغة بعناية، فعادةً ما تحصل على تحكم أفضل بترك التحسين معطّلًا.

## الخطوة 1: أرسل طلبًا مع تفعيل التحسين

أضف `enhance_prompt: true` إلى أي طلب قياسي لتوليد الصور.

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-sd35",
    "prompt": "a cabin in the woods",
    "enhance_prompt": true,
    "format": "webp"
  }'
```

تعيد Venice كتابة `"a cabin in the woods"` إلى موجّه أكثر تفصيلًا، ثم تستخدم النص المُعاد كتابته للتوليد. أما بقية الطلب فتتصرف تمامًا مثل استدعاء التوليد العادي.

<Note>
  يضيف التحسين ما يصل إلى نحو 30 ثانية قبل أن يبدأ التوليد، لأن إعادة الكتابة تُنتَج عبر استدعاء نموذج منفصل. ضع ذلك في الحسبان في مهلات العميل.
</Note>

## الخطوة 2: اقرأ الموجّه المُحسَّن من ترويسة الاستجابة

عند تطبيق إعادة كتابة، تُعيد Venice الموجّه النهائي مُرمَّزًا بترميز URL في ترويسة الاستجابة `x-venice-enhanced-prompt`. فُكّ ترميزه لترى أو تسجّل أو تعرض ما أُرسل فعليًا إلى نموذج الصور.

<CodeGroup>
  ```python Python theme={"system"}
  import base64
  import os
  from urllib.parse import unquote

  import requests

  response = requests.post(
      "https://api.venice.ai/api/v1/image/generate",
      headers={
          "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "model": "venice-sd35",
          "prompt": "a cabin in the woods",
          "enhance_prompt": True,
          "format": "webp",
      },
  )

  data = response.json()

  enhanced = response.headers.get("x-venice-enhanced-prompt")
  if enhanced:
      print("Enhanced prompt:", unquote(enhanced))
  else:
      print("No enhancement was applied; original prompt was used.")

  image_bytes = base64.b64decode(data["images"][0])
  with open("output.webp", "wb") as f:
      f.write(image_bytes)
  ```

  ```javascript Node.js theme={"system"}
  import fs from "fs";

  const response = await fetch("https://api.venice.ai/api/v1/image/generate", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "venice-sd35",
      prompt: "a cabin in the woods",
      enhance_prompt: true,
      format: "webp",
    }),
  });

  const data = await response.json();

  const enhanced = response.headers.get("x-venice-enhanced-prompt");
  if (enhanced) {
    console.log("Enhanced prompt:", decodeURIComponent(enhanced));
  } else {
    console.log("No enhancement was applied; original prompt was used.");
  }

  const imageBuffer = Buffer.from(data.images[0], "base64");
  fs.writeFileSync("output.webp", imageBuffer);
  ```
</CodeGroup>

لا تظهر ترويسة `x-venice-enhanced-prompt` إلا عندما يتم توليد إعادة كتابة وتطبيقها فعليًا. إذا تم تخطي التحسين أو فشل، تكون الترويسة غائبة ويُستخدم موجّهك الأصلي.

## استخدام التحسين لتحرير الصور

تستخدم نقاط نهاية التحرير مُحسِّنًا مدركًا للرؤية يحلل الصورة أو الصور المُدخلة قبل إعادة كتابة التعليمة. يساعد هذا في تحويل طلب قصير مثل `"make it winter"` إلى تحرير أكثر تحديدًا مع الحفاظ على المواضيع والتركيبة ذات الصلة.

لتحرير صورة واحدة، ضمّن `enhance_prompt` في طلب JSON أو multipart:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o edited.png \
  -d '{
    "image": "https://example.com/cabin.jpg",
    "prompt": "make it winter",
    "enhance_prompt": true
  }'
```

للتحرير المتعدد، استخدم المعامل نفسه مع مصفوفة `images`:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o edited.png \
  -d '{
    "images": [
      "https://example.com/cabin.jpg",
      "https://example.com/snow-reference.jpg"
    ],
    "prompt": "make the first image match this winter atmosphere",
    "enhance_prompt": true
  }'
```

تُعيد نقطتا نهاية التحرير الصورة المحرَّرة كبيانات ثنائية. كما هو الحال في التوليد، افحص وفُكّ ترميز URL لـ `x-venice-enhanced-prompt` لترى إعادة الكتابة المُطبَّقة.

## السلوك

| الجانب                | السلوك                                                                                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| نقاط النهاية المدعومة | `POST /image/generate` و`POST /image/edit` و`POST /image/multi-edit`                                                                          |
| الافتراضي             | القيمة الافتراضية لـ `enhance_prompt` هي `false`؛ لا يحدث التحسين مطلقًا ما لم تختره صراحةً.                                                  |
| فشل مرن (Fail-open)   | إذا فشلت إعادة الكتابة لأي سبب، يستمر التوليد أو التحرير بموجّهك الأصلي. لا يفشل الطلب بسبب التحسين.                                          |
| تحرير مدرك للصورة     | في طلبات التحرير، يحلّل المُحسِّن الصورة أو الصور المرفقة عند إعادة كتابة التعليمة.                                                           |
| حد الأحرف             | للتوليد، يُقتطع الموجّه المُحسَّن إلى `promptCharacterLimit` الخاص بالنموذج المختار (راجع [Models API](/api-reference/endpoint/models/list)). |
| الوضع الآمن           | في طلبات التوليد، يُحترم `safe_mode` أثناء التحسين. مع `safe_mode: true`، تبقى إعادة الكتابة SFW.                                             |
| ترويسة الاستجابة      | عند التطبيق، يُعاد الموجّه النهائي مُرمَّزًا بترميز URL في `x-venice-enhanced-prompt`.                                                        |

## التسعير

يُحسب تحسين الموجّهات كرسم ثابت قدره **0.04 دولار لكل إعادة كتابة مُطبَّقة**، فوق التكلفة الاعتيادية لتوليد الصور.

قواعد الفوترة:

* تُحاسَب فقط عند توليد إعادة كتابة وتطبيقها فعليًا. إذا تم تخطي التحسين أو فشل بشكل مرن إلى موجّهك الأصلي، فلا رسم إضافي.
* تُفوتر الرسوم الإضافية على مسار نجاح الصورة. إذا انتهى التوليد بانتهاك محتوى، فلا يُحاسَب التحسين.
* عند طلب صور متعددة باستخدام `variants`، تُفوتر إعادة الكتابة المشتركة **مرة واحدة على الأكثر** لكل طلب، وليس مرة لكل نسخة.

راجع [التسعير](/overview/pricing) للاطلاع على التكاليف الأساسية لتوليد الصور.

## استخدام التحسين مع variants

يقترن التحسين بشكل جيد مع `variants` عند استكشاف فكرة: تُولَّد إعادة كتابة واحدة، ثم يُعاد استخدامها عبر كل نسخة، فتدفع رسم 0.04 دولار مرة واحدة فقط.

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-sd35",
    "prompt": "a cabin in the woods",
    "enhance_prompt": true,
    "variants": 4
  }'
```

<Note>
  `variants` مدعوم فقط عندما تكون `return_binary` بقيمة `false`. راجع [توليد الصور](/guides/media/image-generation) للتفاصيل.
</Note>

## نصائح للموجّهات

1. أبقِ موجّه الإدخال مركّزًا على الموضوع وأي تفاصيل غير قابلة للتفاوض. يملأ التحسين الأسلوب والإضاءة والتركيبة حوله.
2. سجّل ترويسة `x-venice-enhanced-prompt` أثناء التطوير لتتعلم ما يضيفه التحسين وتقرر متى تفضّل كتابة الموجّهات يدويًا.
3. للحصول على نتائج توليد قابلة للتكرار عبر دفعة، ولّد مرة واحدة مع التحسين، والتقط الموجّه المُحسَّن من الترويسة، ثم أعد استخدام هذا النص بالضبط مع تعطيل `enhance_prompt`.
4. لتوليد الصور، اجمع الموجّه الملتقط مع `seed` ثابتة لمقارنة تغييرات المعاملات الأخرى دون إعادة كتابة.

## الأخطاء

يفشل التحسين نفسه بشكل مرن ولا يُطلق أكواد أخطاء خاصة به. لا تزال أخطاء توليد الصور القياسية سارية.

| الحالة | المعنى                                        | الإجراء                                                                 |
| ------ | --------------------------------------------- | ----------------------------------------------------------------------- |
| `400`  | معاملات طلب غير صالحة                         | تحقق من أسماء الحقول والأنواع والقيود الخاصة بالنموذج                   |
| `401`  | فشل المصادقة أو النموذج يتطلب مستوى وصول أعلى | تحقق من مفتاح API ووصولك للنموذج                                        |
| `402`  | الرصيد غير كافٍ                               | أضف رصيدًا عبر [venice.ai/settings/api](https://venice.ai/settings/api) |
| `429`  | تجاوز حد المعدّل أو النموذج محمّل بأقصى طاقته | أعد المحاولة مع تأخير تصاعدي؛ افحص ترويسة `Retry-After`                 |
| `500`  | فشل معالجة الاستدلال                          | أعد إرسال الطلب                                                         |
| `503`  | النموذج بكامل طاقته                           | أعد المحاولة بعد تأخير قصير                                             |

راجع مرجع [أكواد الأخطاء](/api-reference/error-codes) الكامل للتفاصيل.

## ذات صلة

* [توليد الصور](/guides/media/image-generation) — دليل التوليد الكامل، بما في ذلك الأبعاد والأنماط والاستجابات الثنائية.
* [تحرير الصور](/guides/media/image-editing) — تحرير الصورة الواحدة، وطلبات التحرير المتعدد بالطبقات، والاستجابات الثنائية.
* [Generate Images (API reference)](/api-reference/endpoint/image/generate) — كل حقول الطلب والاستجابة لـ `POST /image/generate`.
* [Edit Image (API reference)](/api-reference/endpoint/image/edit) — حقول الطلب لـ `POST /image/edit`.
* [Multi-Edit Image (API reference)](/api-reference/endpoint/image/multi-edit) — حقول الطلب لـ `POST /image/multi-edit`.
* [نماذج الصور](/models/image) — قائمة النماذج والتسعير و`promptCharacterLimit` لكل نموذج.