From a046a60e4fbe7d7cd439561c34ba7edeabcbcee3 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 01:03:42 +0000 Subject: [PATCH] docs: translate prompt enhancement guide and image editing updates into 8 locales --- ar/guides/media/image-editing.mdx | 9 +- ar/guides/media/prompt-enhancement.mdx | 227 ++++++++++++++++++++++ de/guides/media/image-editing.mdx | 9 +- de/guides/media/prompt-enhancement.mdx | 227 ++++++++++++++++++++++ docs.json | 8 + es/guides/media/image-editing.mdx | 9 +- es/guides/media/prompt-enhancement.mdx | 227 ++++++++++++++++++++++ fr/guides/media/image-editing.mdx | 9 +- fr/guides/media/prompt-enhancement.mdx | 227 ++++++++++++++++++++++ it/guides/media/image-editing.mdx | 9 +- it/guides/media/prompt-enhancement.mdx | 227 ++++++++++++++++++++++ ko/guides/media/image-editing.mdx | 9 +- ko/guides/media/prompt-enhancement.mdx | 227 ++++++++++++++++++++++ pt-BR/guides/media/image-editing.mdx | 9 +- pt-BR/guides/media/prompt-enhancement.mdx | 227 ++++++++++++++++++++++ zh/guides/media/image-editing.mdx | 9 +- zh/guides/media/prompt-enhancement.mdx | 227 ++++++++++++++++++++++ 17 files changed, 1888 insertions(+), 8 deletions(-) create mode 100644 ar/guides/media/prompt-enhancement.mdx create mode 100644 de/guides/media/prompt-enhancement.mdx create mode 100644 es/guides/media/prompt-enhancement.mdx create mode 100644 fr/guides/media/prompt-enhancement.mdx create mode 100644 it/guides/media/prompt-enhancement.mdx create mode 100644 ko/guides/media/prompt-enhancement.mdx create mode 100644 pt-BR/guides/media/prompt-enhancement.mdx create mode 100644 zh/guides/media/prompt-enhancement.mdx diff --git a/ar/guides/media/image-editing.mdx b/ar/guides/media/image-editing.mdx index 230ae96a..7ecce115 100644 --- a/ar/guides/media/image-editing.mdx +++ b/ar/guides/media/image-editing.mdx @@ -27,6 +27,10 @@ description: "حرّر الصور، وأجرِ inpaint، وركّب مدخلات للإصلاح الموضعي (Inpainting)، استخدم `/image/edit` أو `/image/multi-edit`. أما المعامل القديم `inpaint` في `/image/generate` فقد تم إيقافه. + + +اضبط `enhance_prompt: true` على أي من نقطتَي نهاية التحرير ليُحلِّل مُحسِّنٌ مدرك للرؤية الصورة أو الصور المُدخلة ويعيد كتابة تعليمتك قبل التحرير. راجع [تحسين الموجّهات](/guides/media/prompt-enhancement) للاطلاع على السلوك والتسعير وتفاصيل ترويسة الاستجابة. + ## الخطوة 1: تحرير صورة واحدة @@ -211,6 +215,7 @@ curl https://api.venice.ai/api/v1/image/background-remove \ | `prompt` | string | نعم | - | تعليمات نصية للتعديل | | `model` | string | لا | `qwen-edit` | معرّف نموذج التحرير | | `aspect_ratio` | string | لا | الافتراضي للنموذج | نسبة الإخراج للنماذج التي تدعمها | +| `enhance_prompt` | boolean | لا | `false` | يحلّل الصورة المُدخلة ويعيد كتابة تعليمة التحرير قبل الاستدلال | | `modelId` | string | متروك (Deprecated) | - | اسم مرادف متروك للحقل `model` | ### `/image/multi-edit` @@ -220,6 +225,7 @@ curl https://api.venice.ai/api/v1/image/background-remove \ | `images` | مصفوفة من 1-3 ملفات أو سلاسل base64 أو روابط URL | نعم | - | الصورة الأولى هي الأساسية؛ والباقي طبقات تحرير أو أقنعة | | `prompt` | string | نعم | - | تعليمات نصية لكيفية دمج الطبقات أو تحريرها | | `modelId` | string | لا | `qwen-edit` | معرّف نموذج التحرير | +| `enhance_prompt` | boolean | لا | `false` | يحلّل الصور المُدخلة ويعيد كتابة تعليمة التحرير قبل الاستدلال | ### `/image/background-remove` @@ -244,7 +250,7 @@ curl https://api.venice.ai/api/v1/image/background-remove \ ## النماذج والتسعير -نموذج التحرير الافتراضي هو `qwen-edit`، بسعر **0.04 دولار لكل عملية تحرير**. وقد تختلف أسعار وقيود النماذج الأخرى القادرة على التحرير. +نموذج التحرير الافتراضي هو `qwen-edit`، بسعر **0.04 دولار لكل عملية تحرير**. وقد تختلف أسعار وقيود النماذج الأخرى القادرة على التحرير. يضيف تحسين الموجّهات **0.04 دولار لكل إعادة كتابة مُطبَّقة** إلى سعر التحرير. راجع: @@ -274,5 +280,6 @@ curl https://api.venice.ai/api/v1/image/background-remove \ ## مسارات العمل ذات الصلة - استخدم [توليد الصور](/guides/media/image-generation) عندما تبدأ من نص بدلاً من صورة موجودة. +- استخدم [تحسين الموجّهات](/guides/media/prompt-enhancement) لتتعرّف على كيفية عمل إعادة كتابة تحرير الصور المدركة للرؤية. - استخدم [نماذج الصور](/models/image) لمقارنة عائلات نماذج التوليد والتحرير والتحسين. - استخدم [Image Edit API](/api-reference/endpoint/image/edit) و[Multi-Edit API](/api-reference/endpoint/image/multi-edit) و[Background Remove API](/api-reference/endpoint/image/background-remove) للاطلاع على تفاصيل المخطط الكاملة. diff --git a/ar/guides/media/prompt-enhancement.mdx b/ar/guides/media/prompt-enhancement.mdx new file mode 100644 index 00000000..3f1a6a88 --- /dev/null +++ b/ar/guides/media/prompt-enhancement.mdx @@ -0,0 +1,227 @@ +--- +title: "تحسين الموجّهات" +description: "أعد كتابة موجّهات توليد الصور وتحريرها تلقائيًا باستخدام معامل enhance_prompt من Venice لإضافة تفاصيل بصرية توضيحية وتحسين جودة المخرجات." +'og:title': "Prompt Enhancement | Venice API Docs" +'og:description': "تعرّف على كيفية استخدام معامل enhance_prompt في واجهات Venice لتوليد الصور وتحريرها لتوسيع الموجّهات القصيرة إلى أوصاف أغنى وأكثر تفصيلاً." +--- + +يعيد تحسين الموجّهات كتابة موجّهك قبل توليد الصورة أو تحريرها لإضافة تفاصيل بصرية توضيحية، فيحوّل الأوصاف القصيرة أو الشحيحة إلى موجّهات أغنى تتّبعها نماذج الصور بموثوقية أعلى. فعّله بضبط `enhance_prompt: true` في `POST /image/generate` أو `POST /image/edit` أو `POST /image/multi-edit`. + +بالنسبة لتوليد الصور، هذا هو نفس التحسين الذي يشغّل "العصا السحرية" في تطبيق Venice على الويب. أما لتحرير الصور، فإن مُحسِّنًا مدركًا للرؤية يستخدم الصورة أو الصور المُدخلة لتوضيح تعليمة التحرير الخاصة بك. + +## متى تستخدمه + +يكون تحسين الموجّهات مفيدًا خصوصًا عندما: + +- يكون موجّهك قصيرًا (بضع كلمات أو عبارة واحدة) وتريد من النموذج أن يملأ التركيبة والإضاءة والأجواء. +- تبني منتجًا يكتب فيه المستخدمون النهائيون موجّهات عادية تستفيد من التوسيع. +- تحرّر صورة وتريد إعادة كتابة التعليمة مع الوعي بمحتواها المرئي. +- تريد مخرجات أكثر تفصيلًا وثباتًا دون كتابة موجّهات طويلة يدويًا. + +إذا كنت ترسل بالفعل موجّهات طويلة ومصاغة بعناية، فعادةً ما تحصل على تحكم أفضل بترك التحسين معطّلًا. + +## الخطوة 1: أرسل طلبًا مع تفعيل التحسين + +أضف `enhance_prompt: true` إلى أي طلب قياسي لتوليد الصور. + +```bash +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"` إلى موجّه أكثر تفصيلًا، ثم تستخدم النص المُعاد كتابته للتوليد. أما بقية الطلب فتتصرف تمامًا مثل استدعاء التوليد العادي. + + +يضيف التحسين ما يصل إلى نحو 30 ثانية قبل أن يبدأ التوليد، لأن إعادة الكتابة تُنتَج عبر استدعاء نموذج منفصل. ضع ذلك في الحسبان في مهلات العميل. + + +## الخطوة 2: اقرأ الموجّه المُحسَّن من ترويسة الاستجابة + +عند تطبيق إعادة كتابة، تُعيد Venice الموجّه النهائي مُرمَّزًا بترميز URL في ترويسة الاستجابة `x-venice-enhanced-prompt`. فُكّ ترميزه لترى أو تسجّل أو تعرض ما أُرسل فعليًا إلى نموذج الصور. + + +```python Python +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 +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); +``` + + +لا تظهر ترويسة `x-venice-enhanced-prompt` إلا عندما يتم توليد إعادة كتابة وتطبيقها فعليًا. إذا تم تخطي التحسين أو فشل، تكون الترويسة غائبة ويُستخدم موجّهك الأصلي. + +## استخدام التحسين لتحرير الصور + +تستخدم نقاط نهاية التحرير مُحسِّنًا مدركًا للرؤية يحلل الصورة أو الصور المُدخلة قبل إعادة كتابة التعليمة. يساعد هذا في تحويل طلب قصير مثل `"make it winter"` إلى تحرير أكثر تحديدًا مع الحفاظ على المواضيع والتركيبة ذات الصلة. + +لتحرير صورة واحدة، ضمّن `enhance_prompt` في طلب JSON أو multipart: + +```bash +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 +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 +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 + }' +``` + + +`variants` مدعوم فقط عندما تكون `return_binary` بقيمة `false`. راجع [توليد الصور](/guides/media/image-generation) للتفاصيل. + + +## نصائح للموجّهات + +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` لكل نموذج. diff --git a/de/guides/media/image-editing.mdx b/de/guides/media/image-editing.mdx index c7fbe776..e93c85b4 100644 --- a/de/guides/media/image-editing.mdx +++ b/de/guides/media/image-editing.mdx @@ -29,6 +29,10 @@ Die Image-Edit-Endpoints sind experimentell, und modellspezifisches Verhalten ka Für Inpainting `/image/edit` oder `/image/multi-edit` verwenden. Der alte `inpaint`-Parameter auf `/image/generate` ist deprecated. + +Setze `enhance_prompt: true` auf einem der Edit-Endpoints, damit ein Vision-fähiger Enhancer das Eingabebild oder die Eingabebilder analysiert und deine Anweisung vor der Bearbeitung umschreibt. Siehe [Prompt-Enhancement](/guides/media/prompt-enhancement) für Verhalten, Preise und Details zu Response-Headern. + + ## Schritt 1: Ein einzelnes Bild bearbeiten Single-Image-Edit ist der einfachste Inpainting-Flow. Sende ein Bild plus einen kurzen Prompt wie „remove the sign", „change the sky to sunrise" oder „replace the background with a studio backdrop". @@ -211,6 +215,7 @@ Hintergrundentfernung eignet sich für: | `prompt` | string | Ja | - | Text-Anweisungen für den Edit | | `model` | string | Nein | `qwen-edit` | Edit-Modell-ID | | `aspect_ratio` | string | Nein | Modell-Default | Output-Ratio bei Modellen, die das unterstützen | +| `enhance_prompt` | boolean | Nein | `false` | Eingabebild analysieren und die Edit-Anweisung vor der Inferenz umschreiben | | `modelId` | string | Deprecated | - | Deprecated-Alias für `model` | ### `/image/multi-edit` @@ -220,6 +225,7 @@ Hintergrundentfernung eignet sich für: | `images` | Array aus 1–3 Dateien, Base64-Strings oder URLs | Ja | - | Erstes Bild ist das Basis-Bild; weitere sind Edit-Layer oder Masken | | `prompt` | string | Ja | - | Text-Anweisungen, wie die Layer kombiniert oder bearbeitet werden | | `modelId` | string | Nein | `qwen-edit` | Edit-Modell-ID | +| `enhance_prompt` | boolean | Nein | `false` | Eingabebilder analysieren und die Edit-Anweisung vor der Inferenz umschreiben | ### `/image/background-remove` @@ -244,7 +250,7 @@ Für Edit-Endpoints müssen die Bilddimensionen mindestens `65536` Pixel und hö ## Modelle und Preise -Das Default-Edit-Modell ist `qwen-edit`, **\$0,04 pro Edit**. Andere edit-fähige Modelle können andere Preise und Einschränkungen haben. +Das Default-Edit-Modell ist `qwen-edit`, **\$0,04 pro Edit**. Andere edit-fähige Modelle können andere Preise und Einschränkungen haben. Prompt-Enhancement erhöht den Edit-Preis um **\$0,04 pro angewendetem Rewrite**. Siehe: @@ -274,5 +280,6 @@ Einige Edit-Modelle haben strengere Content-Policies als Image-Generation-Modell ## Verwandte Workflows - Nutze [Bildgenerierung](/guides/media/image-generation), wenn du nicht von einem Bild, sondern von Text startest. +- Nutze [Prompt-Enhancement](/guides/media/prompt-enhancement), um zu lernen, wie Vision-fähiges Umschreiben von Edits funktioniert. - Nutze [Image-Modelle](/models/image), um Generations-, Edit- und Enhancement-Modellfamilien zu vergleichen. - Nutze [Image-Edit-API](/api-reference/endpoint/image/edit), [Multi-Edit-API](/api-reference/endpoint/image/multi-edit) und [Background-Remove-API](/api-reference/endpoint/image/background-remove) für vollständige Schema-Details. diff --git a/de/guides/media/prompt-enhancement.mdx b/de/guides/media/prompt-enhancement.mdx new file mode 100644 index 00000000..bc7fb931 --- /dev/null +++ b/de/guides/media/prompt-enhancement.mdx @@ -0,0 +1,227 @@ +--- +title: "Prompt-Enhancement" +description: "Prompts für Bildgenerierung und -bearbeitung automatisch mit Venices enhance_prompt-Parameter umschreiben, um klärende visuelle Details hinzuzufügen und die Output-Qualität zu verbessern." +'og:title': "Prompt-Enhancement | Venice API Docs" +'og:description': "Lerne, wie du den enhance_prompt-Parameter in Venices Image-Generation- und Edit-APIs nutzt, um kurze Prompts zu reichhaltigeren, detaillierteren Beschreibungen zu erweitern." +--- + +Prompt-Enhancement schreibt deinen Prompt vor der Bildgenerierung oder -bearbeitung um und ergänzt klärende visuelle Details. Aus kurzen oder spärlichen Beschreibungen werden so reichhaltigere Prompts, denen Image-Modelle zuverlässiger folgen. Aktiviere es, indem du `enhance_prompt: true` an `POST /image/generate`, `POST /image/edit` oder `POST /image/multi-edit` sendest. + +Für die Bildgenerierung ist das dasselbe Enhancement, das auch den „Zauberstab" in der Venice-Web-App antreibt. Für Bildbearbeitungen nutzt ein Vision-fähiger Enhancer das Eingabebild oder die Eingabebilder, um deine Edit-Anweisung zu präzisieren. + +## Wann einsetzen + +Prompt-Enhancement ist besonders nützlich, wenn: + +- Dein Prompt kurz ist (wenige Wörter oder ein einzelner Satz) und du möchtest, dass das Modell Komposition, Beleuchtung und Stimmung ergänzt. +- Du ein Produkt baust, bei dem Endnutzer beiläufige Prompts eingeben, die von einer Erweiterung profitieren. +- Du ein Bild bearbeitest und möchtest, dass die Anweisung mit Bewusstsein für den sichtbaren Inhalt umgeschrieben wird. +- Du konsistentere, detailliertere Ergebnisse willst, ohne lange Prompts von Hand zu schreiben. + +Wenn du bereits lange, sorgfältig ausgearbeitete Prompts sendest, hast du in der Regel bessere Kontrolle, wenn du Enhancement ausgeschaltet lässt. + +## Schritt 1: Request mit aktiviertem Enhancement senden + +Ergänze `enhance_prompt: true` in einer beliebigen Standard-Bildgenerierungsanfrage. + +```bash +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 schreibt `"a cabin in the woods"` in einen detaillierteren Prompt um und verwendet dann den umgeschriebenen Text für die Generierung. Der Rest des Requests verhält sich exakt wie ein normaler Generierungsaufruf. + + +Enhancement fügt bis zu ~30 Sekunden vor Beginn der Generierung hinzu, weil das Umschreiben von einem separaten Modellaufruf erzeugt wird. Berücksichtige das in Client-Timeouts. + + +## Schritt 2: Enhanced Prompt aus dem Response-Header lesen + +Wenn ein Rewrite angewendet wurde, gibt Venice den finalen Prompt URL-kodiert im Response-Header `x-venice-enhanced-prompt` zurück. Dekodiere ihn, um zu sehen, zu loggen oder anzuzeigen, was tatsächlich an das Image-Modell geschickt wurde. + + +```python Python +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 +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); +``` + + +Der Header `x-venice-enhanced-prompt` ist nur vorhanden, wenn tatsächlich ein Rewrite erzeugt und angewendet wurde. Wenn Enhancement übersprungen wird oder fehlschlägt, fehlt der Header und dein ursprünglicher Prompt wird verwendet. + +## Enhancement für Bildbearbeitungen nutzen + +Die Edit-Endpoints verwenden einen Vision-fähigen Enhancer, der das Eingabebild oder die Eingabebilder analysiert, bevor die Anweisung umgeschrieben wird. Das hilft, einen kurzen Wunsch wie `"make it winter"` in einen präziseren Edit zu übersetzen und dabei relevante Motive und die Komposition zu erhalten. + +Für einen Single-Image-Edit füge `enhance_prompt` in einem JSON- oder Multipart-Request hinzu: + +```bash +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 + }' +``` + +Für Multi-Edit verwende denselben Parameter mit dem `images`-Array: + +```bash +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 + }' +``` + +Beide Edit-Endpoints geben das bearbeitete Bild als Binärdaten zurück. Wie bei der Generierung kannst du `x-venice-enhanced-prompt` auslesen und URL-dekodieren, um den angewendeten Rewrite zu sehen. + +## Verhalten + +| Aspekt | Verhalten | +|---|---| +| Unterstützte Endpoints | `POST /image/generate`, `POST /image/edit` und `POST /image/multi-edit` | +| Default | `enhance_prompt` ist standardmäßig `false`; Enhancement passiert nie, außer du aktivierst es. | +| Fail-Open | Wenn der Rewrite aus irgendeinem Grund fehlschlägt, wird die Generierung oder Bearbeitung mit deinem ursprünglichen Prompt fortgesetzt. Der Request bricht wegen des Enhancements nicht mit einem Fehler ab. | +| Bild-bewusste Edits | Bei Edit-Requests analysiert der Enhancer das übergebene Bild oder die Bilder beim Umschreiben der Anweisung. | +| Zeichenlimit | Bei der Generierung wird der Enhanced Prompt auf das `promptCharacterLimit` des gewählten Modells gekürzt (siehe [Models-API](/api-reference/endpoint/models/list)). | +| Safe Mode | Bei Generierungs-Requests wird `safe_mode` beim Enhancement berücksichtigt. Mit `safe_mode: true` bleibt der Rewrite SFW. | +| Response-Header | Wenn angewendet, wird der finale Prompt URL-kodiert in `x-venice-enhanced-prompt` zurückgegeben. | + +## Preise + +Prompt-Enhancement wird als pauschaler Aufschlag von **\$0,04 pro angewendetem Rewrite** zusätzlich zu den normalen Bildgenerierungskosten berechnet. + +Abrechnungsregeln: + +- Berechnet wird nur, wenn tatsächlich ein Rewrite erzeugt und angewendet wird. Wenn Enhancement übersprungen wird oder auf deinen ursprünglichen Prompt zurückfällt, fällt kein Aufschlag an. +- Der Aufschlag wird auf dem Erfolgs-Pfad des Bildes abgerechnet. Wenn die Generierung mit einem Content-Verstoß endet, wird das Enhancement nicht berechnet. +- Wenn du mit `variants` mehrere Bilder anforderst, wird der gemeinsame Rewrite **höchstens einmal** pro Request abgerechnet, nicht einmal pro Variante. + +Siehe [Preise](/overview/pricing) für die Basiskosten der Bildgenerierung. + +## Enhancement zusammen mit Variants nutzen + +Enhancement passt gut zu `variants`, wenn du eine Idee erkundest: Ein einziger Rewrite wird erzeugt und dann über alle Varianten hinweg wiederverwendet, sodass du den Aufschlag von \$0,04 nur einmal zahlst. + +```bash +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 + }' +``` + + +`variants` wird nur unterstützt, wenn `return_binary` auf `false` steht. Details siehe [Bildgenerierung](/guides/media/image-generation). + + +## Prompting-Tipps + +1. Halte deinen Eingabe-Prompt auf das Motiv und alle nicht verhandelbaren Details fokussiert. Enhancement ergänzt Stil, Beleuchtung und Komposition drumherum. +2. Logge während der Entwicklung den Header `x-venice-enhanced-prompt`, damit du lernst, was Enhancement hinzufügt, und entscheiden kannst, wann du lieber selbst Prompts schreibst. +3. Für reproduzierbare Generierungsergebnisse über einen Batch hinweg: einmal mit Enhancement generieren, den Enhanced Prompt aus dem Header übernehmen und dann exakt diesen Text mit ausgeschaltetem `enhance_prompt` wiederverwenden. +4. Für die Bildgenerierung kombiniere den übernommenen Prompt mit einem festen `seed`, um andere Parameteränderungen zu vergleichen, ohne den Rewrite erneut zu erzeugen. + +## Fehler + +Enhancement selbst fällt auf den ursprünglichen Prompt zurück und liefert keine eigenen Fehlercodes. Die üblichen Fehler der Bildgenerierung gelten weiterhin. + +| Status | Bedeutung | Aktion | +|---|---|---| +| `400` | Ungültige Request-Parameter | Feldnamen, Typen und modellspezifische Einschränkungen prüfen | +| `401` | Authentifizierung fehlgeschlagen oder Modell erfordert eine höhere Zugriffsstufe | API-Schlüssel und Modellzugriff prüfen | +| `402` | Unzureichendes Guthaben | Credits unter [venice.ai/settings/api](https://venice.ai/settings/api) aufladen | +| `429` | Rate-Limit überschritten oder Modell überlastet | Mit Backoff erneut versuchen; `Retry-After`-Header beachten | +| `500` | Inferenz-Verarbeitung fehlgeschlagen | Request wiederholen | +| `503` | Modell ausgelastet | Nach kurzer Verzögerung erneut versuchen | + +Details in der vollständigen Referenz [Fehlercodes](/api-reference/error-codes). + +## Verwandt + +- [Bildgenerierung](/guides/media/image-generation) — der vollständige Generierungs-Guide, inklusive Größen, Styles und Binär-Antworten. +- [Bildbearbeitung](/guides/media/image-editing) — Single-Image-Edits, mehrschichtige Multi-Edit-Requests und Binär-Antworten. +- [Bilder generieren (API-Referenz)](/api-reference/endpoint/image/generate) — alle Request- und Response-Felder für `POST /image/generate`. +- [Bild bearbeiten (API-Referenz)](/api-reference/endpoint/image/edit) — Request-Felder für `POST /image/edit`. +- [Multi-Edit Bild (API-Referenz)](/api-reference/endpoint/image/multi-edit) — Request-Felder für `POST /image/multi-edit`. +- [Image-Modelle](/models/image) — Modellliste, Preise und `promptCharacterLimit` pro Modell. diff --git a/docs.json b/docs.json index 54e682da..badb7d75 100644 --- a/docs.json +++ b/docs.json @@ -377,6 +377,7 @@ "expanded": true, "pages": [ "pt-BR/guides/media/image-generation", + "pt-BR/guides/media/prompt-enhancement", "pt-BR/guides/media/image-editing", "pt-BR/guides/media/image-upscaling", "pt-BR/guides/media/video-generation", @@ -686,6 +687,7 @@ "expanded": true, "pages": [ "ar/guides/media/image-generation", + "ar/guides/media/prompt-enhancement", "ar/guides/media/image-editing", "ar/guides/media/image-upscaling", "ar/guides/media/video-generation", @@ -995,6 +997,7 @@ "expanded": true, "pages": [ "it/guides/media/image-generation", + "it/guides/media/prompt-enhancement", "it/guides/media/image-editing", "it/guides/media/image-upscaling", "it/guides/media/video-generation", @@ -1304,6 +1307,7 @@ "expanded": true, "pages": [ "de/guides/media/image-generation", + "de/guides/media/prompt-enhancement", "de/guides/media/image-editing", "de/guides/media/image-upscaling", "de/guides/media/video-generation", @@ -1613,6 +1617,7 @@ "expanded": true, "pages": [ "es/guides/media/image-generation", + "es/guides/media/prompt-enhancement", "es/guides/media/image-editing", "es/guides/media/image-upscaling", "es/guides/media/video-generation", @@ -1922,6 +1927,7 @@ "expanded": true, "pages": [ "fr/guides/media/image-generation", + "fr/guides/media/prompt-enhancement", "fr/guides/media/image-editing", "fr/guides/media/image-upscaling", "fr/guides/media/video-generation", @@ -2231,6 +2237,7 @@ "expanded": true, "pages": [ "zh/guides/media/image-generation", + "zh/guides/media/prompt-enhancement", "zh/guides/media/image-editing", "zh/guides/media/image-upscaling", "zh/guides/media/video-generation", @@ -2540,6 +2547,7 @@ "expanded": true, "pages": [ "ko/guides/media/image-generation", + "ko/guides/media/prompt-enhancement", "ko/guides/media/image-editing", "ko/guides/media/image-upscaling", "ko/guides/media/video-generation", diff --git a/es/guides/media/image-editing.mdx b/es/guides/media/image-editing.mdx index db91b898..18fe49d8 100644 --- a/es/guides/media/image-editing.mdx +++ b/es/guides/media/image-editing.mdx @@ -29,6 +29,10 @@ Los endpoints de edición de imagen son experimentales y el comportamiento espec Para inpainting, usa `/image/edit` o `/image/multi-edit`. El antiguo parámetro `inpaint` en `/image/generate` está deprecado. + +Establece `enhance_prompt: true` en cualquiera de los endpoints de edición para que un mejorador con conciencia visual analice la imagen o imágenes de entrada y reescriba tu instrucción antes de editar. Consulta [Mejora de prompts](/guides/media/prompt-enhancement) para conocer el comportamiento, los precios y los detalles de las cabeceras de respuesta. + + ## Paso 1: edita una sola imagen La edición de imagen única es el flujo más simple de inpainting. Envía una imagen más un prompt corto como "remove the sign", "change the sky to sunrise" o "replace the background with a studio backdrop". @@ -211,6 +215,7 @@ Usa la eliminación de fondo para: | `prompt` | string | Sí | - | Instrucciones de texto para la edición | | `model` | string | No | `qwen-edit` | ID del modelo de edición | | `aspect_ratio` | string | No | predeterminado del modelo | Ratio de salida para los modelos que lo admiten | +| `enhance_prompt` | boolean | No | `false` | Analiza la imagen de entrada y reescribe la instrucción de edición antes de la inferencia | | `modelId` | string | Deprecado | - | Alias deprecado de `model` | ### `/image/multi-edit` @@ -220,6 +225,7 @@ Usa la eliminación de fondo para: | `images` | array de 1-3 archivos, cadenas base64 o URLs | Sí | - | La primera imagen es la base; el resto son capas de edición o máscaras | | `prompt` | string | Sí | - | Instrucciones de texto sobre cómo combinar o editar las capas | | `modelId` | string | No | `qwen-edit` | ID del modelo de edición | +| `enhance_prompt` | boolean | No | `false` | Analiza las imágenes de entrada y reescribe la instrucción de edición antes de la inferencia | ### `/image/background-remove` @@ -244,7 +250,7 @@ Para los endpoints de edición, las dimensiones de la imagen deben ser de al men ## Modelos y precios -El modelo de edición predeterminado es `qwen-edit`, con precio de **$0.04 por edición**. Otros modelos con capacidad de edición pueden tener precios y restricciones diferentes. +El modelo de edición predeterminado es `qwen-edit`, con precio de **$0.04 por edición**. Otros modelos con capacidad de edición pueden tener precios y restricciones diferentes. La mejora de prompts añade **$0.04 por reescritura aplicada** al precio de la edición. Consulta: @@ -274,5 +280,6 @@ Algunos modelos de edición tienen políticas de contenido más estrictas que lo ## Flujos relacionados - Usa [Generación de imágenes](/guides/media/image-generation) cuando partes de texto en lugar de una imagen existente. +- Usa [Mejora de prompts](/guides/media/prompt-enhancement) para aprender cómo funciona la reescritura de ediciones con conciencia visual. - Usa [Modelos de imagen](/models/image) para comparar familias de modelos de generación, edición y mejora. - Usa la [API de edición de imagen](/api-reference/endpoint/image/edit), la [API multi-edit](/api-reference/endpoint/image/multi-edit) y la [API de eliminación de fondo](/api-reference/endpoint/image/background-remove) para detalles completos del schema. diff --git a/es/guides/media/prompt-enhancement.mdx b/es/guides/media/prompt-enhancement.mdx new file mode 100644 index 00000000..9cf15749 --- /dev/null +++ b/es/guides/media/prompt-enhancement.mdx @@ -0,0 +1,227 @@ +--- +title: "Mejora de prompts" +description: "Reescribe automáticamente los prompts de generación y edición de imágenes con el parámetro enhance_prompt de Venice para añadir detalle visual clarificador y mejorar la calidad de la salida." +'og:title': "Prompt Enhancement | Venice API Docs" +'og:description': "Aprende a usar el parámetro enhance_prompt en las APIs de generación y edición de imágenes de Venice para expandir prompts cortos en descripciones más ricas y detalladas." +--- + +La mejora de prompts reescribe tu prompt antes de la generación o edición de imagen para añadir detalle visual clarificador, convirtiendo descripciones cortas o escasas en prompts más ricos que los modelos de imagen siguen de forma más fiable. Actívala estableciendo `enhance_prompt: true` en `POST /image/generate`, `POST /image/edit` o `POST /image/multi-edit`. + +Para la generación de imágenes, esta es la misma mejora que impulsa la "varita mágica" en la aplicación web de Venice. Para las ediciones de imagen, un mejorador con conciencia visual usa la imagen o imágenes de entrada para clarificar tu instrucción de edición. + +## Cuándo usarla + +La mejora de prompts es más útil cuando: + +- Tu prompt es corto (unas pocas palabras o una sola frase) y quieres que el modelo complete la composición, la iluminación y el ambiente. +- Estás construyendo un producto en el que los usuarios finales escriben prompts informales que se benefician de una expansión. +- Estás editando una imagen y quieres que la instrucción se reescriba con conciencia de su contenido visible. +- Quieres una salida más consistente y detallada sin escribir a mano prompts largos. + +Si ya envías prompts largos y cuidadosamente elaborados, normalmente obtendrás un mejor control dejando la mejora desactivada. + +## Paso 1: envía una solicitud con la mejora activada + +Añade `enhance_prompt: true` a cualquier solicitud estándar de generación de imagen. + +```bash +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 reescribe `"a cabin in the woods"` en un prompt más detallado, y luego usa el texto reescrito para la generación. El resto de la solicitud se comporta exactamente como una llamada de generación normal. + + +La mejora añade hasta ~30 segundos antes de que comience la generación, porque la reescritura la produce una llamada a un modelo aparte. Tenlo en cuenta en los timeouts del cliente. + + +## Paso 2: lee el prompt mejorado desde la cabecera de la respuesta + +Cuando se aplica una reescritura, Venice devuelve el prompt final codificado en URL en la cabecera de respuesta `x-venice-enhanced-prompt`. Decodifícala para ver, registrar o mostrar lo que realmente se envió al modelo de imagen. + + +```python Python +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 +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); +``` + + +La cabecera `x-venice-enhanced-prompt` solo está presente cuando realmente se generó y aplicó una reescritura. Si la mejora se omite o falla, la cabecera no aparece y se usa tu prompt original. + +## Usar la mejora para editar imágenes + +Los endpoints de edición utilizan un mejorador con conciencia visual que analiza la imagen o imágenes de entrada antes de reescribir la instrucción. Esto ayuda a convertir una solicitud corta como `"make it winter"` en una edición más específica preservando los sujetos y la composición relevantes. + +Para una edición de una sola imagen, incluye `enhance_prompt` tanto en una solicitud JSON como en una multipart: + +```bash +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 + }' +``` + +Para multi-edit, usa el mismo parámetro con el array `images`: + +```bash +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 + }' +``` + +Ambos endpoints de edición devuelven la imagen editada como datos binarios. Al igual que con la generación, inspecciona y decodifica en URL `x-venice-enhanced-prompt` para ver la reescritura aplicada. + +## Comportamiento + +| Aspecto | Comportamiento | +|---|---| +| Endpoints admitidos | `POST /image/generate`, `POST /image/edit` y `POST /image/multi-edit` | +| Predeterminado | `enhance_prompt` es `false` por defecto; la mejora nunca ocurre a menos que la actives. | +| Fail-open | Si la reescritura falla por cualquier motivo, la generación o edición continúa con tu prompt original. La solicitud no falla debido a la mejora. | +| Ediciones con conciencia de imagen | En las solicitudes de edición, el mejorador analiza la imagen o imágenes proporcionadas al reescribir la instrucción. | +| Límite de caracteres | Para la generación, el prompt mejorado se trunca al `promptCharacterLimit` del modelo seleccionado (consulta la [API de Models](/api-reference/endpoint/models/list)). | +| Modo seguro | En las solicitudes de generación, se respeta `safe_mode` durante la mejora. Con `safe_mode: true`, la reescritura se mantiene SFW. | +| Cabecera de respuesta | Cuando se aplica, el prompt final se devuelve codificado en URL en `x-venice-enhanced-prompt`. | + +## Precios + +La mejora de prompts se cobra como un recargo fijo de **\$0.04 por reescritura aplicada**, además del coste normal de generación de imagen. + +Reglas de facturación: + +- Solo se te cobra cuando realmente se genera y aplica una reescritura. Si la mejora se omite o falla-open a tu prompt original, no hay recargo. +- El recargo se factura en la vía de éxito de la imagen. Si la generación termina en una violación de contenido, la mejora no se cobra. +- Cuando solicitas varias imágenes con `variants`, la reescritura compartida se factura **como máximo una vez** por solicitud, no una vez por variante. + +Consulta [Precios](/overview/pricing) para los costes base de la generación de imagen. + +## Usar la mejora con variants + +La mejora combina bien con `variants` al explorar una idea: se genera una reescritura y luego se reutiliza en cada variante, así pagas el recargo de \$0.04 una sola vez. + +```bash +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 + }' +``` + + +`variants` solo se admite cuando `return_binary` es `false`. Consulta [Generación de imágenes](/guides/media/image-generation) para más detalles. + + +## Consejos para prompts + +1. Mantén tu prompt de entrada centrado en el sujeto y en los detalles innegociables. La mejora rellena el estilo, la iluminación y la composición a su alrededor. +2. Registra la cabecera `x-venice-enhanced-prompt` durante el desarrollo para aprender qué añade la mejora y decidir cuándo prefieres escribir los prompts a mano. +3. Para obtener resultados de generación repetibles en un lote, genera una vez con la mejora, captura el prompt mejorado desde la cabecera y luego reutiliza ese texto exacto con `enhance_prompt` desactivado. +4. Para la generación de imágenes, combina el prompt capturado con un `seed` fijo para comparar otros cambios de parámetros sin volver a reescribir. + +## Errores + +La mejora en sí falla-open y no expone sus propios códigos de error. Los errores estándar de generación de imagen siguen aplicándose. + +| Estado | Significado | Acción | +|---|---|---| +| `400` | Parámetros de solicitud no válidos | Comprueba los nombres de campo, los tipos y las restricciones específicas del modelo | +| `401` | Autenticación fallida o el modelo requiere un nivel de acceso superior | Comprueba tu API key y el acceso al modelo | +| `402` | Saldo insuficiente | Añade créditos en [venice.ai/settings/api](https://venice.ai/settings/api) | +| `429` | Límite de velocidad excedido o modelo sobrecargado | Reintenta con backoff; comprueba la cabecera `Retry-After` | +| `500` | Procesamiento de inferencia fallido | Reintenta la solicitud | +| `503` | Modelo a capacidad máxima | Reintenta tras una breve demora | + +Consulta la referencia completa de [Códigos de error](/api-reference/error-codes) para más detalles. + +## Relacionado + +- [Generación de imágenes](/guides/media/image-generation) — la guía completa de generación, incluyendo tamaños, estilos y respuestas binarias. +- [Edición de imágenes](/guides/media/image-editing) — ediciones de una sola imagen, solicitudes multi-edit en capas y respuestas binarias. +- [Generar imágenes (referencia de la API)](/api-reference/endpoint/image/generate) — todos los campos de solicitud y respuesta para `POST /image/generate`. +- [Editar imagen (referencia de la API)](/api-reference/endpoint/image/edit) — campos de solicitud para `POST /image/edit`. +- [Multi-Edit de imagen (referencia de la API)](/api-reference/endpoint/image/multi-edit) — campos de solicitud para `POST /image/multi-edit`. +- [Modelos de imagen](/models/image) — lista de modelos, precios y `promptCharacterLimit` por modelo. diff --git a/fr/guides/media/image-editing.mdx b/fr/guides/media/image-editing.mdx index 61aee3ec..374a3308 100644 --- a/fr/guides/media/image-editing.mdx +++ b/fr/guides/media/image-editing.mdx @@ -27,6 +27,10 @@ Les endpoints d'édition d'images sont expérimentaux et le comportement spécif Pour l'inpainting, utilisez `/image/edit` ou `/image/multi-edit`. L'ancien paramètre `inpaint` sur `/image/generate` est déprécié. + + +Définissez `enhance_prompt: true` sur l'un ou l'autre des endpoints d'édition pour qu'un enhancer conscient de l'image analyse l'image ou les images d'entrée et réécrive votre instruction avant l'édition. Voir [Amélioration de prompt](/guides/media/prompt-enhancement) pour le comportement, la tarification et les détails de l'en-tête de réponse. + ## Étape 1 : Éditer une seule image @@ -211,6 +215,7 @@ Utilisez la suppression d'arrière-plan pour : | `prompt` | string | Oui | - | Instructions textuelles pour l'édition | | `model` | string | Non | `qwen-edit` | Identifiant du modèle d'édition | | `aspect_ratio` | string | Non | valeur par défaut du modèle | Ratio de sortie pour les modèles qui le prennent en charge | +| `enhance_prompt` | boolean | Non | `false` | Analyser l'image d'entrée et réécrire l'instruction d'édition avant l'inférence | | `modelId` | string | Déprécié | - | Alias déprécié de `model` | ### `/image/multi-edit` @@ -220,6 +225,7 @@ Utilisez la suppression d'arrière-plan pour : | `images` | tableau de 1 à 3 fichiers, chaînes base64 ou URL | Oui | - | La première image est l'image de base ; les autres sont des couches d'édition ou des masques | | `prompt` | string | Oui | - | Instructions textuelles pour combiner ou éditer les couches | | `modelId` | string | Non | `qwen-edit` | Identifiant du modèle d'édition | +| `enhance_prompt` | boolean | Non | `false` | Analyser les images d'entrée et réécrire l'instruction d'édition avant l'inférence | ### `/image/background-remove` @@ -244,7 +250,7 @@ Pour les endpoints d'édition, les dimensions de l'image doivent être d'au moin ## Modèles et tarification -Le modèle d'édition par défaut est `qwen-edit`, au tarif de **0,04 $ par édition**. D'autres modèles capables d'édition peuvent avoir des tarifs et des contraintes différents. +Le modèle d'édition par défaut est `qwen-edit`, au tarif de **0,04 $ par édition**. D'autres modèles capables d'édition peuvent avoir des tarifs et des contraintes différents. L'amélioration de prompt ajoute **0,04 $ par réécriture appliquée** au prix de l'édition. Voir : @@ -274,5 +280,6 @@ Certains modèles d'édition ont des politiques de contenu plus strictes que les ## Workflows liés - Utilisez [Génération d'images](/guides/media/image-generation) lorsque vous partez d'un texte plutôt que d'une image existante. +- Utilisez [Amélioration de prompt](/guides/media/prompt-enhancement) pour apprendre comment fonctionne la réécriture d'édition consciente de l'image. - Utilisez [Modèles d'image](/models/image) pour comparer les familles de modèles de génération, d'édition et d'amélioration. - Utilisez [API Image Edit](/api-reference/endpoint/image/edit), [API Multi-Edit](/api-reference/endpoint/image/multi-edit) et [API Background Remove](/api-reference/endpoint/image/background-remove) pour les détails complets du schéma. diff --git a/fr/guides/media/prompt-enhancement.mdx b/fr/guides/media/prompt-enhancement.mdx new file mode 100644 index 00000000..6603eac5 --- /dev/null +++ b/fr/guides/media/prompt-enhancement.mdx @@ -0,0 +1,227 @@ +--- +title: "Amélioration de prompt" +description: "Réécrivez automatiquement les prompts de génération et d'édition d'images avec le paramètre enhance_prompt de Venice pour ajouter des détails visuels clarifiants et améliorer la qualité de sortie." +'og:title': "Amélioration de prompt | Documentation de l'API Venice" +'og:description': "Apprenez à utiliser le paramètre enhance_prompt sur les API de génération et d'édition d'images de Venice pour transformer des prompts courts en descriptions plus riches et détaillées." +--- + +L'amélioration de prompt réécrit votre prompt avant la génération ou l'édition d'images afin d'ajouter des détails visuels clarifiants, transformant des descriptions courtes ou éparses en prompts plus riches que les modèles d'image suivent plus fidèlement. Activez-la en définissant `enhance_prompt: true` sur `POST /image/generate`, `POST /image/edit` ou `POST /image/multi-edit`. + +Pour la génération d'images, il s'agit de la même amélioration qui alimente la « baguette magique » dans l'application web Venice. Pour les éditions d'images, un enhancer conscient de l'image utilise l'image ou les images d'entrée pour clarifier votre instruction d'édition. + +## Quand l'utiliser + +L'amélioration de prompt est particulièrement utile lorsque : + +- Votre prompt est court (quelques mots ou une seule phrase) et vous souhaitez que le modèle complète la composition, l'éclairage et l'ambiance. +- Vous développez un produit dans lequel les utilisateurs finaux tapent des prompts informels qui bénéficient d'une expansion. +- Vous éditez une image et souhaitez que l'instruction soit réécrite en tenant compte de son contenu visible. +- Vous voulez une sortie plus cohérente et détaillée sans avoir à rédiger manuellement de longs prompts. + +Si vous envoyez déjà des prompts longs et soigneusement rédigés, vous obtiendrez généralement un meilleur contrôle en laissant l'amélioration désactivée. + +## Étape 1 : Envoyer une requête avec l'amélioration activée + +Ajoutez `enhance_prompt: true` à n'importe quelle requête standard de génération d'images. + +```bash +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 réécrit `"a cabin in the woods"` en un prompt plus détaillé, puis utilise le texte réécrit pour la génération. Le reste de la requête se comporte exactement comme un appel de génération normal. + + +L'amélioration ajoute jusqu'à ~30 secondes avant le démarrage de la génération, car la réécriture est produite par un appel de modèle distinct. Prenez cela en compte dans les timeouts de votre client. + + +## Étape 2 : Lire le prompt amélioré depuis l'en-tête de réponse + +Lorsqu'une réécriture est appliquée, Venice renvoie le prompt final encodé en URL dans l'en-tête de réponse `x-venice-enhanced-prompt`. Décodez-le pour voir, journaliser ou afficher ce qui a réellement été envoyé au modèle d'image. + + +```python Python +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 +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); +``` + + +L'en-tête `x-venice-enhanced-prompt` n'est présent que lorsqu'une réécriture a effectivement été générée et appliquée. Si l'amélioration est ignorée ou échoue, l'en-tête est absent et votre prompt original est utilisé. + +## Utiliser l'amélioration pour les éditions d'images + +Les endpoints d'édition utilisent un enhancer conscient de l'image qui analyse l'image ou les images d'entrée avant de réécrire l'instruction. Cela permet de transformer une requête courte telle que `"make it winter"` en une édition plus spécifique tout en préservant les sujets et la composition pertinents. + +Pour une édition d'une seule image, incluez `enhance_prompt` dans une requête JSON ou multipart : + +```bash +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 + }' +``` + +Pour multi-edit, utilisez le même paramètre avec le tableau `images` : + +```bash +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 + }' +``` + +Les deux endpoints d'édition renvoient l'image éditée sous forme de données binaires. Comme pour la génération, inspectez et décodez l'URL de `x-venice-enhanced-prompt` pour voir la réécriture appliquée. + +## Comportement + +| Aspect | Comportement | +|---|---| +| Endpoints pris en charge | `POST /image/generate`, `POST /image/edit` et `POST /image/multi-edit` | +| Valeur par défaut | `enhance_prompt` vaut `false` par défaut ; l'amélioration ne se produit jamais sans opt-in. | +| Fail-open | Si la réécriture échoue pour une raison quelconque, la génération ou l'édition se poursuit avec votre prompt original. La requête ne renvoie pas d'erreur à cause de l'amélioration. | +| Éditions conscientes de l'image | Sur les requêtes d'édition, l'enhancer analyse l'image ou les images fournies lors de la réécriture de l'instruction. | +| Limite de caractères | Pour la génération, le prompt amélioré est tronqué à la valeur `promptCharacterLimit` du modèle sélectionné (voir l'[API Models](/api-reference/endpoint/models/list)). | +| Safe mode | Sur les requêtes de génération, `safe_mode` est respecté pendant l'amélioration. Avec `safe_mode: true`, la réécriture reste SFW. | +| En-tête de réponse | Lorsqu'elle est appliquée, le prompt final est renvoyé encodé en URL dans `x-venice-enhanced-prompt`. | + +## Tarification + +L'amélioration de prompt est facturée sous forme de supplément forfaitaire de **0,04 $ par réécriture appliquée**, en plus du coût normal de génération d'images. + +Règles de facturation : + +- Vous n'êtes facturé que lorsqu'une réécriture est effectivement générée et appliquée. Si l'amélioration est ignorée ou échoue en revenant à votre prompt original, il n'y a pas de supplément. +- Le supplément est facturé sur le chemin de succès de l'image. Si la génération se termine par une violation de contenu, l'amélioration n'est pas facturée. +- Lorsque vous demandez plusieurs images avec `variants`, la réécriture partagée est facturée **au plus une fois** par requête, et non une fois par variante. + +Consultez [Tarification](/overview/pricing) pour les coûts de base de la génération d'images. + +## Utiliser l'amélioration avec les variantes + +L'amélioration se marie bien avec `variants` lors de l'exploration d'une idée : une réécriture est générée, puis réutilisée pour chaque variante, de sorte que vous ne payez le supplément de 0,04 $ qu'une seule fois. + +```bash +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 + }' +``` + + +`variants` n'est pris en charge que lorsque `return_binary` est `false`. Voir [Génération d'images](/guides/media/image-generation) pour plus de détails. + + +## Conseils de prompting + +1. Concentrez votre prompt d'entrée sur le sujet et tout détail non négociable. L'amélioration ajoute autour le style, l'éclairage et la composition. +2. Journalisez l'en-tête `x-venice-enhanced-prompt` pendant le développement afin d'apprendre ce que l'amélioration ajoute et de décider quand vous préféreriez écrire les prompts à la main. +3. Pour des résultats de génération reproductibles sur un lot, générez une fois avec l'amélioration, capturez le prompt amélioré depuis l'en-tête, puis réutilisez ce texte exact avec `enhance_prompt` désactivé. +4. Pour la génération d'images, combinez le prompt capturé avec un `seed` fixe pour comparer d'autres changements de paramètres sans avoir à réécrire. + +## Erreurs + +L'amélioration elle-même échoue en fail-open et ne remonte pas ses propres codes d'erreur. Les erreurs standard de génération d'images s'appliquent toujours. + +| Statut | Signification | Action | +|---|---|---| +| `400` | Paramètres de requête invalides | Vérifiez les noms de champs, les types et les contraintes spécifiques au modèle | +| `401` | Échec d'authentification ou modèle nécessitant un niveau d'accès supérieur | Vérifiez votre clé API et votre accès au modèle | +| `402` | Solde insuffisant | Ajoutez des crédits sur [venice.ai/settings/api](https://venice.ai/settings/api) | +| `429` | Limite de débit dépassée ou modèle surchargé | Réessayez avec un backoff ; vérifiez l'en-tête `Retry-After` | +| `500` | Échec du traitement d'inférence | Réessayez la requête | +| `503` | Modèle à pleine capacité | Réessayez après un court délai | + +Consultez la référence complète des [Codes d'erreur](/api-reference/error-codes) pour plus de détails. + +## Liens associés + +- [Génération d'images](/guides/media/image-generation) — le guide complet de génération, y compris le dimensionnement, les styles et les réponses binaires. +- [Édition d'images](/guides/media/image-editing) — éditions d'une seule image, requêtes multi-edit en couches et réponses binaires. +- [Générer des images (référence API)](/api-reference/endpoint/image/generate) — chaque champ de requête et de réponse pour `POST /image/generate`. +- [Éditer une image (référence API)](/api-reference/endpoint/image/edit) — champs de requête pour `POST /image/edit`. +- [Multi-Edit d'image (référence API)](/api-reference/endpoint/image/multi-edit) — champs de requête pour `POST /image/multi-edit`. +- [Modèles d'image](/models/image) — liste des modèles, tarification et `promptCharacterLimit` par modèle. diff --git a/it/guides/media/image-editing.mdx b/it/guides/media/image-editing.mdx index d6c46268..d97398ef 100644 --- a/it/guides/media/image-editing.mdx +++ b/it/guides/media/image-editing.mdx @@ -29,6 +29,10 @@ Gli endpoint di image edit sono sperimentali e il comportamento specifico dei mo Per l'inpainting, usa `/image/edit` o `/image/multi-edit`. Il vecchio parametro `inpaint` su `/image/generate` è deprecato. + +Imposta `enhance_prompt: true` su entrambi gli endpoint di edit per fare in modo che un enhancer vision-aware analizzi l'immagine o le immagini di input e riscriva la tua istruzione prima di eseguire la modifica. Vedi [Prompt Enhancement](/guides/media/prompt-enhancement) per comportamento, prezzi e dettagli sugli header di risposta. + + ## Passo 1: Modifica una singola immagine L'edit di una singola immagine è il flusso di inpainting più semplice. Invia un'immagine più un breve prompt come "remove the sign", "change the sky to sunrise" o "replace the background with a studio backdrop". @@ -211,6 +215,7 @@ Usa la rimozione dello sfondo per: | `prompt` | string | Sì | - | Istruzioni testuali per l'edit | | `model` | string | No | `qwen-edit` | ID del modello di edit | | `aspect_ratio` | string | No | default del modello | Rapporto d'aspetto di output per i modelli che lo supportano | +| `enhance_prompt` | boolean | No | `false` | Analizza l'immagine di input e riscrive l'istruzione di edit prima dell'inferenza | | `modelId` | string | Deprecato | - | Alias deprecato per `model` | ### `/image/multi-edit` @@ -220,6 +225,7 @@ Usa la rimozione dello sfondo per: | `images` | array di 1-3 file, stringhe base64 o URL | Sì | - | La prima immagine è quella di base; le altre sono layer di edit o maschere | | `prompt` | string | Sì | - | Istruzioni testuali su come combinare o modificare i layer | | `modelId` | string | No | `qwen-edit` | ID del modello di edit | +| `enhance_prompt` | boolean | No | `false` | Analizza le immagini di input e riscrive l'istruzione di edit prima dell'inferenza | ### `/image/background-remove` @@ -244,7 +250,7 @@ Per gli endpoint di edit, le dimensioni dell'immagine devono essere almeno `6553 ## Modelli e prezzi -Il modello di edit di default è `qwen-edit`, con un prezzo di **$0,04 per edit**. Altri modelli con capacità di edit possono avere prezzi e vincoli diversi. +Il modello di edit di default è `qwen-edit`, con un prezzo di **$0,04 per edit**. Altri modelli con capacità di edit possono avere prezzi e vincoli diversi. Il prompt enhancement aggiunge **$0,04 per riscrittura applicata** al prezzo dell'edit. Vedi: @@ -274,5 +280,6 @@ Alcuni modelli di edit hanno policy sui contenuti più rigide rispetto ai modell ## Workflow correlati - Usa [Generazione di immagini](/guides/media/image-generation) quando parti dal testo invece che da un'immagine esistente. +- Usa [Prompt Enhancement](/guides/media/prompt-enhancement) per capire come funziona la riscrittura degli edit basata sulla vision. - Usa [Modelli di immagini](/models/image) per confrontare famiglie di modelli di generazione, edit e miglioramento. - Usa [Image Edit API](/api-reference/endpoint/image/edit), [Multi-Edit API](/api-reference/endpoint/image/multi-edit) e [Background Remove API](/api-reference/endpoint/image/background-remove) per i dettagli completi dello schema. diff --git a/it/guides/media/prompt-enhancement.mdx b/it/guides/media/prompt-enhancement.mdx new file mode 100644 index 00000000..69d8b201 --- /dev/null +++ b/it/guides/media/prompt-enhancement.mdx @@ -0,0 +1,227 @@ +--- +title: "Prompt Enhancement" +description: "Riscrivi automaticamente i prompt di generazione e modifica delle immagini con il parametro enhance_prompt di Venice per aggiungere dettagli visivi chiarificatori e migliorare la qualità dell'output." +'og:title': "Prompt Enhancement | Venice API Docs" +'og:description': "Scopri come usare il parametro enhance_prompt sulle API di generazione e modifica delle immagini di Venice per espandere prompt brevi in descrizioni più ricche e dettagliate." +--- + +Il prompt enhancement riscrive il tuo prompt prima della generazione o della modifica dell'immagine per aggiungere dettagli visivi chiarificatori, trasformando descrizioni brevi o scarne in prompt più ricchi che i modelli di immagini seguono in modo più affidabile. Abilitalo impostando `enhance_prompt: true` su `POST /image/generate`, `POST /image/edit` o `POST /image/multi-edit`. + +Per la generazione di immagini, è lo stesso enhancement che alimenta la "bacchetta magica" nella web app di Venice. Per le modifiche di immagini, un enhancer vision-aware utilizza l'immagine o le immagini di input per chiarire la tua istruzione di edit. + +## Quando usarlo + +Il prompt enhancement è più utile quando: + +- Il tuo prompt è breve (poche parole o una singola frase) e vuoi che il modello riempia composizione, illuminazione e atmosfera. +- Stai sviluppando un prodotto in cui gli utenti finali digitano prompt informali che beneficiano dell'espansione. +- Stai modificando un'immagine e vuoi che l'istruzione venga riscritta tenendo conto del suo contenuto visibile. +- Vuoi un output più coerente e dettagliato senza scrivere a mano prompt lunghi. + +Se invii già prompt lunghi e accuratamente elaborati, di solito otterrai un controllo migliore lasciando l'enhancement disattivato. + +## Passo 1: Invia una richiesta con l'enhancement abilitato + +Aggiungi `enhance_prompt: true` a qualsiasi richiesta standard di generazione di immagini. + +```bash +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 riscrive `"a cabin in the woods"` in un prompt più dettagliato, quindi usa il testo riscritto per la generazione. Il resto della richiesta si comporta esattamente come una normale chiamata di generazione. + + +L'enhancement aggiunge fino a ~30 secondi prima che la generazione inizi, perché la riscrittura è prodotta da una chiamata a un modello separato. Tienine conto nei timeout del client. + + +## Passo 2: Leggi il prompt migliorato dall'header della risposta + +Quando viene applicata una riscrittura, Venice restituisce il prompt finale codificato in URL nell'header di risposta `x-venice-enhanced-prompt`. Decodificalo per vedere, registrare o mostrare ciò che è stato effettivamente inviato al modello di immagine. + + +```python Python +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 +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); +``` + + +L'header `x-venice-enhanced-prompt` è presente solo quando una riscrittura è stata effettivamente generata e applicata. Se l'enhancement viene saltato o fallisce, l'header è assente e viene usato il tuo prompt originale. + +## Uso dell'enhancement per le modifiche di immagini + +Gli endpoint di edit usano un enhancer vision-aware che analizza l'immagine o le immagini di input prima di riscrivere l'istruzione. Questo aiuta a trasformare una richiesta breve come `"make it winter"` in una modifica più specifica, preservando i soggetti e la composizione rilevanti. + +Per un edit su singola immagine, includi `enhance_prompt` in una richiesta JSON o multipart: + +```bash +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 + }' +``` + +Per multi-edit, usa lo stesso parametro con l'array `images`: + +```bash +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 + }' +``` + +Entrambi gli endpoint di edit restituiscono l'immagine modificata come dati binari. Come per la generazione, ispeziona e decodifica in URL `x-venice-enhanced-prompt` per vedere la riscrittura applicata. + +## Comportamento + +| Aspetto | Comportamento | +|---|---| +| Endpoint supportati | `POST /image/generate`, `POST /image/edit` e `POST /image/multi-edit` | +| Default | `enhance_prompt` ha come default `false`; l'enhancement non avviene mai a meno che tu non lo richieda. | +| Fail-open | Se la riscrittura fallisce per qualsiasi motivo, la generazione o la modifica continua con il tuo prompt originale. La richiesta non genera un errore a causa dell'enhancement. | +| Edit consapevoli dell'immagine | Nelle richieste di edit, l'enhancer analizza l'immagine o le immagini fornite quando riscrive l'istruzione. | +| Limite di caratteri | Per la generazione, il prompt migliorato viene troncato al `promptCharacterLimit` del modello selezionato (vedi la [Models API](/api-reference/endpoint/models/list)). | +| Safe mode | Nelle richieste di generazione, `safe_mode` viene rispettato durante l'enhancement. Con `safe_mode: true`, la riscrittura rimane SFW. | +| Header di risposta | Quando applicato, il prompt finale viene restituito codificato in URL in `x-venice-enhanced-prompt`. | + +## Prezzi + +Il prompt enhancement viene addebitato come un sovrapprezzo forfettario di **\$0,04 per riscrittura applicata**, oltre al costo normale di generazione dell'immagine. + +Regole di fatturazione: + +- Vieni addebitato solo quando una riscrittura viene effettivamente generata e applicata. Se l'enhancement viene saltato o fa fail-open sul tuo prompt originale, non c'è alcun sovrapprezzo. +- Il sovrapprezzo viene fatturato sul percorso di successo dell'immagine. Se la generazione termina con una violazione dei contenuti, l'enhancement non viene addebitato. +- Quando richiedi più immagini con `variants`, la riscrittura condivisa viene fatturata **al massimo una volta** per richiesta, non una volta per variante. + +Vedi [Prezzi](/overview/pricing) per i costi base della generazione di immagini. + +## Uso dell'enhancement con le variants + +L'enhancement si abbina bene a `variants` quando esplori un'idea: viene generata una sola riscrittura, poi riutilizzata su ogni variante, quindi paghi il sovrapprezzo di \$0,04 una sola volta. + +```bash +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 + }' +``` + + +`variants` è supportato solo quando `return_binary` è `false`. Vedi [Generazione di immagini](/guides/media/image-generation) per i dettagli. + + +## Consigli per il prompting + +1. Mantieni il tuo prompt di input focalizzato sul soggetto e su eventuali dettagli non negoziabili. L'enhancement riempie stile, illuminazione e composizione intorno ad esso. +2. Registra l'header `x-venice-enhanced-prompt` durante lo sviluppo, così puoi capire cosa aggiunge l'enhancement e decidere quando preferisci scrivere i prompt a mano. +3. Per risultati di generazione ripetibili in un batch, genera una volta con l'enhancement, cattura il prompt migliorato dall'header, quindi riutilizza quello stesso testo con `enhance_prompt` disattivato. +4. Per la generazione di immagini, combina il prompt catturato con un `seed` fisso per confrontare altre modifiche di parametri senza dover riscrivere di nuovo. + +## Errori + +L'enhancement in sé fa fail-open e non espone codici di errore propri. Gli errori standard della generazione di immagini si applicano comunque. + +| Status | Significato | Azione | +|---|---|---| +| `400` | Parametri di richiesta non validi | Controlla i nomi dei campi, i tipi e i vincoli specifici del modello | +| `401` | Autenticazione fallita o il modello richiede un tier di accesso superiore | Controlla la tua API key e l'accesso al modello | +| `402` | Saldo insufficiente | Aggiungi crediti su [venice.ai/settings/api](https://venice.ai/settings/api) | +| `429` | Rate limit superato o modello sovraccarico | Riprova con backoff; controlla l'header `Retry-After` | +| `500` | Elaborazione dell'inferenza fallita | Riprova la richiesta | +| `503` | Modello al massimo della capacità | Riprova dopo un breve ritardo | + +Vedi il riferimento completo [Codici di errore](/api-reference/error-codes) per i dettagli. + +## Correlati + +- [Generazione di immagini](/guides/media/image-generation) — la guida completa alla generazione, inclusi dimensionamento, stili e risposte binarie. +- [Image Editing](/guides/media/image-editing) — edit su singola immagine, richieste multi-edit a strati e risposte binarie. +- [Generate Images (API reference)](/api-reference/endpoint/image/generate) — ogni campo di richiesta e risposta per `POST /image/generate`. +- [Edit Image (API reference)](/api-reference/endpoint/image/edit) — campi di richiesta per `POST /image/edit`. +- [Multi-Edit Image (API reference)](/api-reference/endpoint/image/multi-edit) — campi di richiesta per `POST /image/multi-edit`. +- [Modelli di immagini](/models/image) — elenco dei modelli, prezzi e `promptCharacterLimit` per modello. diff --git a/ko/guides/media/image-editing.mdx b/ko/guides/media/image-editing.mdx index 26a5bb88..188e2f05 100644 --- a/ko/guides/media/image-editing.mdx +++ b/ko/guides/media/image-editing.mdx @@ -29,6 +29,10 @@ Venice의 이미지 편집은 동기 방식입니다. 원본 이미지를 `/imag Inpainting에는 `/image/edit` 또는 `/image/multi-edit`를 사용하세요. `/image/generate`의 기존 `inpaint` 파라미터는 deprecated입니다. + +편집 endpoint에서 `enhance_prompt: true`로 설정하면, 비전 인식 enhancer가 입력 이미지 하나 또는 여러 개를 분석해 편집 전에 지시를 다시 작성합니다. 동작 방식, 가격, 응답 헤더 관련 세부 정보는 [Prompt Enhancement](/guides/media/prompt-enhancement)를 참조하세요. + + ## 1단계: 단일 이미지 편집 단일 이미지 편집은 가장 단순한 inpainting 흐름입니다. 이미지 한 장과 "remove the sign", "change the sky to sunrise", "replace the background with a studio backdrop" 같은 짧은 prompt를 함께 보내세요. @@ -211,6 +215,7 @@ curl https://api.venice.ai/api/v1/image/background-remove \ | `prompt` | string | 예 | - | 편집을 위한 텍스트 지시 | | `model` | string | 아니오 | `qwen-edit` | 편집 모델 ID | | `aspect_ratio` | string | 아니오 | 모델 기본값 | 지원 모델의 출력 비율 | +| `enhance_prompt` | boolean | 아니오 | `false` | 입력 이미지를 분석하고 추론 전에 편집 지시를 다시 작성 | | `modelId` | string | Deprecated | - | `model`의 deprecated 별칭 | ### `/image/multi-edit` @@ -220,6 +225,7 @@ curl https://api.venice.ai/api/v1/image/background-remove \ | `images` | 1-3개의 파일, base64 문자열, 또는 URL 배열 | 예 | - | 첫 이미지는 base 이미지, 나머지는 편집 레이어나 마스크 | | `prompt` | string | 예 | - | 레이어를 결합하거나 편집하는 방법에 대한 텍스트 지시 | | `modelId` | string | 아니오 | `qwen-edit` | 편집 모델 ID | +| `enhance_prompt` | boolean | 아니오 | `false` | 입력 이미지들을 분석하고 추론 전에 편집 지시를 다시 작성 | ### `/image/background-remove` @@ -244,7 +250,7 @@ curl https://api.venice.ai/api/v1/image/background-remove \ ## 모델 및 가격 -기본 편집 모델은 `qwen-edit`이며 **편집당 $0.04** 입니다. 편집 가능한 다른 모델은 가격과 제약이 다를 수 있습니다. +기본 편집 모델은 `qwen-edit`이며 **편집당 $0.04** 입니다. 편집 가능한 다른 모델은 가격과 제약이 다를 수 있습니다. Prompt enhancement는 편집 가격에 **적용된 재작성당 $0.04**를 추가합니다. 참고: @@ -274,5 +280,6 @@ curl https://api.venice.ai/api/v1/image/background-remove \ ## 관련 워크플로 - 기존 이미지가 아닌 텍스트에서 시작한다면 [이미지 생성](/guides/media/image-generation)을 사용하세요. +- 비전 인식 편집 재작성이 어떻게 동작하는지 알아보려면 [Prompt Enhancement](/guides/media/prompt-enhancement)를 사용하세요. - 생성, 편집, 향상 모델 패밀리를 비교하려면 [이미지 모델](/models/image)을 참고하세요. - 전체 스키마는 [Image Edit API](/api-reference/endpoint/image/edit), [Multi-Edit API](/api-reference/endpoint/image/multi-edit), [Background Remove API](/api-reference/endpoint/image/background-remove)를 참고하세요. diff --git a/ko/guides/media/prompt-enhancement.mdx b/ko/guides/media/prompt-enhancement.mdx new file mode 100644 index 00000000..41828687 --- /dev/null +++ b/ko/guides/media/prompt-enhancement.mdx @@ -0,0 +1,227 @@ +--- +title: "Prompt Enhancement" +description: "Venice의 enhance_prompt 파라미터로 이미지 생성 및 편집 prompt를 자동으로 다시 작성해 시각적 세부 정보를 추가하고 출력 품질을 향상시키세요." +'og:title': "Prompt Enhancement | Venice API Docs" +'og:description': "Venice의 이미지 생성 및 편집 API에서 enhance_prompt 파라미터를 사용해 짧은 prompt를 더 풍부하고 상세한 설명으로 확장하는 방법을 알아보세요." +--- + +Prompt enhancement는 이미지 생성 또는 편집 전에 prompt를 다시 작성해 명확한 시각적 세부 정보를 추가하며, 짧거나 빈약한 설명을 이미지 모델이 더 안정적으로 따르는 풍부한 prompt로 바꿔줍니다. `POST /image/generate`, `POST /image/edit`, 또는 `POST /image/multi-edit`에서 `enhance_prompt: true`로 설정하여 활성화할 수 있습니다. + +이미지 생성의 경우, 이는 Venice 웹 앱의 "매직 완드"를 구동하는 것과 동일한 향상입니다. 이미지 편집의 경우, 비전 인식 enhancer가 입력 이미지 하나 또는 여러 개를 사용해 편집 지시를 명확히 합니다. + +## 언제 사용하나요 + +Prompt enhancement는 다음과 같은 경우에 가장 유용합니다: + +- prompt가 짧고(몇 단어 또는 한 문구) 모델이 구도, 조명, 분위기를 채워주기를 원할 때. +- 최종 사용자가 캐주얼한 prompt를 입력하고 확장을 통해 이점을 얻을 수 있는 제품을 구축할 때. +- 이미지를 편집 중이며 그 안에 보이는 콘텐츠를 인식한 상태로 지시가 다시 작성되기를 원할 때. +- 긴 prompt를 직접 작성하지 않고도 더 일관되고 상세한 출력을 원할 때. + +이미 길고 세심하게 다듬은 prompt를 보내고 있다면 enhancement를 꺼두는 편이 보통 더 나은 제어권을 줍니다. + +## 1단계: enhancement가 활성화된 요청 보내기 + +표준 이미지 생성 요청에 `enhance_prompt: true`를 추가하세요. + +```bash +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"`를 더 상세한 prompt로 다시 작성한 뒤, 다시 작성된 텍스트를 생성에 사용합니다. 요청의 나머지 부분은 일반 생성 호출과 정확히 동일하게 동작합니다. + + +Enhancement는 별도의 모델 호출로 재작성이 생성되기 때문에 생성이 시작되기 전에 최대 ~30초가 추가됩니다. 클라이언트 타임아웃에서 이를 고려하세요. + + +## 2단계: 응답 헤더에서 향상된 prompt 읽기 + +재작성이 적용되면, Venice는 최종 prompt를 `x-venice-enhanced-prompt` 응답 헤더에 URL 인코딩된 형태로 반환합니다. 이를 디코딩하면 이미지 모델에 실제로 전달된 내용을 확인하거나 로그로 남기거나 표시할 수 있습니다. + + +```python Python +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 +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); +``` + + +`x-venice-enhanced-prompt` 헤더는 재작성이 실제로 생성되어 적용된 경우에만 존재합니다. Enhancement가 건너뛰어지거나 실패하면 헤더가 없으며 원본 prompt가 사용됩니다. + +## 이미지 편집에 enhancement 사용하기 + +편집 endpoint는 입력 이미지 하나 또는 여러 개를 분석한 뒤 지시를 다시 작성하는 비전 인식 enhancer를 사용합니다. 이 덕분에 `"make it winter"` 같은 짧은 요청을 관련 피사체와 구도를 보존하면서 더 구체적인 편집으로 바꿀 수 있습니다. + +단일 이미지 편집의 경우, JSON 또는 multipart 요청 어디에서든 `enhance_prompt`를 포함하세요: + +```bash +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 + }' +``` + +Multi-edit의 경우, `images` 배열과 함께 같은 파라미터를 사용하세요: + +```bash +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 + }' +``` + +두 편집 endpoint 모두 편집된 이미지를 바이너리 데이터로 반환합니다. 생성과 마찬가지로, `x-venice-enhanced-prompt`를 확인하고 URL 디코딩해 적용된 재작성을 볼 수 있습니다. + +## 동작 방식 + +| Aspect | Behavior | +|---|---| +| 지원 endpoint | `POST /image/generate`, `POST /image/edit`, `POST /image/multi-edit` | +| 기본값 | `enhance_prompt`의 기본값은 `false`이며, 명시적으로 활성화하지 않으면 enhancement가 일어나지 않습니다. | +| Fail-open | 재작성이 어떤 이유로든 실패하면 원본 prompt로 생성 또는 편집이 계속됩니다. Enhancement 때문에 요청이 오류로 종료되지 않습니다. | +| 이미지 인식 편집 | 편집 요청 시, enhancer는 지시를 다시 작성할 때 제공된 이미지 하나 또는 여러 개를 분석합니다. | +| 문자 제한 | 생성의 경우, 향상된 prompt는 선택한 모델의 `promptCharacterLimit`으로 잘립니다([Models API](/api-reference/endpoint/models/list) 참조). | +| 안전 모드 | 생성 요청 시 enhancement 중에도 `safe_mode`가 준수됩니다. `safe_mode: true`이면 재작성은 SFW로 유지됩니다. | +| 응답 헤더 | 적용될 경우, 최종 prompt는 `x-venice-enhanced-prompt`에 URL 인코딩되어 반환됩니다. | + +## 가격 + +Prompt enhancement는 일반 이미지 생성 비용에 더해 **적용된 재작성당 \$0.04**의 정액 추가 요금으로 부과됩니다. + +과금 규칙: + +- 재작성이 실제로 생성되어 적용된 경우에만 요금이 부과됩니다. Enhancement가 건너뛰어지거나 fail open으로 원본 prompt를 사용하면 추가 요금이 없습니다. +- 추가 요금은 이미지 성공 경로에서 부과됩니다. 생성이 콘텐츠 위반으로 종료되면 enhancement 요금은 부과되지 않습니다. +- `variants`로 여러 이미지를 요청할 때, 공유되는 재작성은 요청당 **최대 한 번**만 부과되며 variant 하나당 부과되지 않습니다. + +이미지 생성 기본 비용은 [가격 정책](/overview/pricing)을 참조하세요. + +## variants와 함께 enhancement 사용하기 + +Enhancement는 아이디어를 탐색할 때 `variants`와 잘 어울립니다: 재작성이 한 번 생성된 뒤 모든 variant에 재사용되므로, \$0.04 추가 요금을 한 번만 지불합니다. + +```bash +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 + }' +``` + + +`variants`는 `return_binary`가 `false`일 때만 지원됩니다. 자세한 내용은 [이미지 생성](/guides/media/image-generation)을 참조하세요. + + +## Prompt 작성 팁 + +1. 입력 prompt는 피사체와 절대 양보할 수 없는 세부 사항에 집중하세요. Enhancement는 그 주변의 스타일, 조명, 구도를 채워줍니다. +2. 개발 중에는 `x-venice-enhanced-prompt` 헤더를 로그로 남겨 enhancement가 무엇을 추가하는지 학습하고, 언제 prompt를 직접 작성하는 것이 더 나을지 결정하세요. +3. 배치 전체에서 재현 가능한 생성 결과를 얻으려면 enhancement로 한 번 생성한 뒤 헤더에서 향상된 prompt를 캡처하고, `enhance_prompt`를 꺼둔 채 그 정확한 텍스트를 재사용하세요. +4. 이미지 생성의 경우, 캡처한 prompt를 고정된 `seed`와 결합하면 재작성 없이 다른 파라미터 변경을 비교할 수 있습니다. + +## 오류 + +Enhancement 자체는 fail open되며 자체 오류 코드를 노출하지 않습니다. 표준 이미지 생성 오류가 그대로 적용됩니다. + +| Status | Meaning | Action | +|---|---|---| +| `400` | 잘못된 요청 파라미터 | 필드 이름, 타입, 모델별 제약 조건 확인 | +| `401` | 인증 실패 또는 모델이 더 높은 액세스 등급 필요 | API 키 및 모델 액세스 확인 | +| `402` | 잔액 부족 | [venice.ai/settings/api](https://venice.ai/settings/api)에서 크레딧 추가 | +| `429` | Rate limit 초과 또는 모델 과부하 | 백오프와 함께 재시도, `Retry-After` 헤더 확인 | +| `500` | 추론 처리 실패 | 요청 재시도 | +| `503` | 모델 용량 초과 | 잠시 후 재시도 | + +자세한 내용은 전체 [오류 코드](/api-reference/error-codes) 레퍼런스를 참조하세요. + +## 관련 문서 + +- [이미지 생성](/guides/media/image-generation) — 크기 지정, 스타일, 바이너리 응답을 포함한 전체 생성 가이드. +- [이미지 편집](/guides/media/image-editing) — 단일 이미지 편집, 레이어드 multi-edit 요청, 바이너리 응답. +- [이미지 생성 (API 레퍼런스)](/api-reference/endpoint/image/generate) — `POST /image/generate`의 모든 요청 및 응답 필드. +- [이미지 편집 (API 레퍼런스)](/api-reference/endpoint/image/edit) — `POST /image/edit`의 요청 필드. +- [Multi-Edit 이미지 (API 레퍼런스)](/api-reference/endpoint/image/multi-edit) — `POST /image/multi-edit`의 요청 필드. +- [이미지 모델](/models/image) — 모델 목록, 가격, 모델별 `promptCharacterLimit`. diff --git a/pt-BR/guides/media/image-editing.mdx b/pt-BR/guides/media/image-editing.mdx index 187f4dd3..a26bc8f2 100644 --- a/pt-BR/guides/media/image-editing.mdx +++ b/pt-BR/guides/media/image-editing.mdx @@ -29,6 +29,10 @@ Os endpoints de edição de imagem são experimentais e o comportamento específ Para inpainting, use `/image/edit` ou `/image/multi-edit`. O antigo parâmetro `inpaint` em `/image/generate` está obsoleto. + +Defina `enhance_prompt: true` em qualquer um dos endpoints de edição para que um aprimorador com percepção visual analise a imagem ou imagens de entrada e reescreva sua instrução antes da edição. Veja [Aprimoramento de prompt](/guides/media/prompt-enhancement) para detalhes de comportamento, preços e cabeçalhos de resposta. + + ## Passo 1: Edite uma única imagem A edição de imagem única é o fluxo de inpainting mais simples. Envie uma imagem mais um prompt curto, como "remova a placa", "mude o céu para nascer do sol" ou "substitua o fundo por um cenário de estúdio". @@ -211,6 +215,7 @@ Use a remoção de fundo para: | `prompt` | string | Sim | - | Instruções de texto para a edição | | `model` | string | Não | `qwen-edit` | ID do modelo de edição | | `aspect_ratio` | string | Não | padrão do modelo | Proporção de saída para modelos que a suportam | +| `enhance_prompt` | boolean | Não | `false` | Analisa a imagem de entrada e reescreve a instrução de edição antes da inferência | | `modelId` | string | Obsoleto | - | Alias obsoleto para `model` | ### `/image/multi-edit` @@ -220,6 +225,7 @@ Use a remoção de fundo para: | `images` | array de 1-3 arquivos, strings base64 ou URLs | Sim | - | A primeira imagem é a base; o restante são camadas de edição ou máscaras | | `prompt` | string | Sim | - | Instruções de texto sobre como combinar ou editar as camadas | | `modelId` | string | Não | `qwen-edit` | ID do modelo de edição | +| `enhance_prompt` | boolean | Não | `false` | Analisa as imagens de entrada e reescreve a instrução de edição antes da inferência | ### `/image/background-remove` @@ -244,7 +250,7 @@ Para endpoints de edição, as dimensões da imagem devem ser de no mínimo `655 ## Modelos e preços -O modelo de edição padrão é `qwen-edit`, com preço de **$0,04 por edição**. Outros modelos com capacidade de edição podem ter preços e restrições diferentes. +O modelo de edição padrão é `qwen-edit`, com preço de **$0,04 por edição**. Outros modelos com capacidade de edição podem ter preços e restrições diferentes. O aprimoramento de prompt adiciona **$0,04 por reescrita aplicada** ao preço da edição. Veja: @@ -274,5 +280,6 @@ Alguns modelos de edição têm políticas de conteúdo mais rigorosas do que mo ## Workflows relacionados - Use [Geração de imagens](/guides/media/image-generation) quando estiver partindo de texto em vez de uma imagem existente. +- Use [Aprimoramento de prompt](/guides/media/prompt-enhancement) para aprender como funciona a reescrita de edições com percepção visual. - Use [Modelos de imagem](/models/image) para comparar famílias de modelos de geração, edição e aprimoramento. - Use a [API de Edição de imagem](/api-reference/endpoint/image/edit), [API de Multi-Edit](/api-reference/endpoint/image/multi-edit) e [API de Remoção de fundo](/api-reference/endpoint/image/background-remove) para detalhes completos do schema. diff --git a/pt-BR/guides/media/prompt-enhancement.mdx b/pt-BR/guides/media/prompt-enhancement.mdx new file mode 100644 index 00000000..8871e683 --- /dev/null +++ b/pt-BR/guides/media/prompt-enhancement.mdx @@ -0,0 +1,227 @@ +--- +title: "Aprimoramento de prompt" +description: "Reescreva automaticamente prompts de geração e edição de imagens com o parâmetro enhance_prompt da Venice para adicionar detalhes visuais esclarecedores e melhorar a qualidade do resultado." +'og:title': "Aprimoramento de prompt | Documentação da API Venice" +'og:description': "Aprenda a usar o parâmetro enhance_prompt nas APIs de geração e edição de imagens da Venice para expandir prompts curtos em descrições mais ricas e detalhadas." +--- + +O aprimoramento de prompt reescreve seu prompt antes da geração ou edição de imagens para adicionar detalhes visuais esclarecedores, transformando descrições curtas ou esparsas em prompts mais ricos que os modelos de imagem seguem com mais consistência. Ative-o definindo `enhance_prompt: true` em `POST /image/generate`, `POST /image/edit` ou `POST /image/multi-edit`. + +Para geração de imagens, este é o mesmo aprimoramento que alimenta a "varinha mágica" no aplicativo web da Venice. Para edições de imagem, um aprimorador com percepção visual usa a imagem ou imagens de entrada para esclarecer sua instrução de edição. + +## Quando usar + +O aprimoramento de prompt é mais útil quando: + +- Seu prompt é curto (poucas palavras ou uma única frase) e você quer que o modelo preencha composição, iluminação e clima. +- Você está construindo um produto no qual usuários finais digitam prompts casuais que se beneficiam de expansão. +- Você está editando uma imagem e quer que a instrução seja reescrita com percepção do conteúdo visível. +- Você quer saídas mais consistentes e detalhadas sem escrever manualmente prompts longos. + +Se você já envia prompts longos e cuidadosamente elaborados, normalmente terá melhor controle deixando o aprimoramento desativado. + +## Passo 1: Envie uma requisição com o aprimoramento ativado + +Adicione `enhance_prompt: true` a qualquer requisição padrão de geração de imagem. + +```bash +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" + }' +``` + +A Venice reescreve `"a cabin in the woods"` em um prompt mais detalhado e, em seguida, usa o texto reescrito para a geração. O restante da requisição se comporta exatamente como uma chamada de geração normal. + + +O aprimoramento adiciona até ~30 segundos antes de a geração começar, porque a reescrita é produzida por uma chamada de modelo separada. Leve isso em conta nos timeouts do cliente. + + +## Passo 2: Leia o prompt aprimorado no cabeçalho da resposta + +Quando uma reescrita é aplicada, a Venice retorna o prompt final codificado em URL no cabeçalho de resposta `x-venice-enhanced-prompt`. Decodifique-o para ver, registrar ou exibir o que foi efetivamente enviado ao modelo de imagem. + + +```python Python +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 +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); +``` + + +O cabeçalho `x-venice-enhanced-prompt` só está presente quando uma reescrita foi efetivamente gerada e aplicada. Se o aprimoramento for ignorado ou falhar, o cabeçalho fica ausente e seu prompt original é usado. + +## Usando aprimoramento para edições de imagem + +Os endpoints de edição usam um aprimorador com percepção visual que analisa a imagem ou imagens de entrada antes de reescrever a instrução. Isso ajuda a transformar uma solicitação curta como `"make it winter"` em uma edição mais específica, preservando sujeitos e composição relevantes. + +Para uma edição de imagem única, inclua `enhance_prompt` em uma requisição JSON ou multipart: + +```bash +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 + }' +``` + +Para multi-edit, use o mesmo parâmetro com o array `images`: + +```bash +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 + }' +``` + +Ambos os endpoints de edição retornam a imagem editada como dados binários. Assim como na geração, inspecione e decodifique via URL o `x-venice-enhanced-prompt` para ver a reescrita aplicada. + +## Comportamento + +| Aspecto | Comportamento | +|---|---| +| Endpoints suportados | `POST /image/generate`, `POST /image/edit` e `POST /image/multi-edit` | +| Padrão | `enhance_prompt` tem valor padrão `false`; o aprimoramento nunca acontece a menos que você opte por ele. | +| Fail-open | Se a reescrita falhar por qualquer motivo, a geração ou edição continua com seu prompt original. A requisição não retorna erro por causa do aprimoramento. | +| Edições com percepção de imagem | Em requisições de edição, o aprimorador analisa a imagem ou imagens fornecidas ao reescrever a instrução. | +| Limite de caracteres | Para geração, o prompt aprimorado é truncado ao `promptCharacterLimit` do modelo selecionado (veja a [API de Models](/api-reference/endpoint/models/list)). | +| Safe mode | Em requisições de geração, `safe_mode` é respeitado durante o aprimoramento. Com `safe_mode: true`, a reescrita permanece SFW. | +| Cabeçalho de resposta | Quando aplicado, o prompt final é retornado codificado em URL em `x-venice-enhanced-prompt`. | + +## Preços + +O aprimoramento de prompt é cobrado como uma sobretaxa fixa de **\$0,04 por reescrita aplicada**, além do custo normal de geração de imagem. + +Regras de cobrança: + +- Você só é cobrado quando uma reescrita é efetivamente gerada e aplicada. Se o aprimoramento for ignorado ou falhar de forma aberta para seu prompt original, não há sobretaxa. +- A sobretaxa é cobrada no caminho de sucesso da imagem. Se a geração terminar em violação de conteúdo, o aprimoramento não é cobrado. +- Quando você solicita múltiplas imagens com `variants`, a reescrita compartilhada é cobrada **no máximo uma vez** por requisição, e não uma vez por variante. + +Veja [Preços](/overview/pricing) para os custos-base de geração de imagens. + +## Usando aprimoramento com variants + +O aprimoramento combina bem com `variants` ao explorar uma ideia: uma reescrita é gerada e, em seguida, reutilizada em cada variante, de modo que você paga a sobretaxa de \$0,04 uma única vez. + +```bash +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 + }' +``` + + +`variants` só é suportado quando `return_binary` é `false`. Veja [Geração de imagens](/guides/media/image-generation) para detalhes. + + +## Dicas de prompt + +1. Mantenha seu prompt de entrada focado no sujeito e em quaisquer detalhes inegociáveis. O aprimoramento preenche estilo, iluminação e composição ao redor dele. +2. Registre o cabeçalho `x-venice-enhanced-prompt` durante o desenvolvimento para aprender o que o aprimoramento adiciona e decidir quando você preferiria escrever os prompts manualmente. +3. Para resultados de geração repetíveis em um lote, gere uma vez com aprimoramento, capture o prompt aprimorado a partir do cabeçalho e depois reutilize esse texto exato com `enhance_prompt` desativado. +4. Para geração de imagens, combine o prompt capturado com um `seed` fixo para comparar outras mudanças de parâmetros sem gerar nova reescrita. + +## Erros + +O próprio aprimoramento falha de forma aberta e não expõe seus próprios códigos de erro. Os erros padrão de geração de imagem continuam se aplicando. + +| Status | Significado | Ação | +|---|---|---| +| `400` | Parâmetros de requisição inválidos | Verifique nomes de campos, tipos e restrições específicas do modelo | +| `401` | Falha de autenticação ou o modelo exige um tier de acesso mais alto | Verifique sua chave de API e o acesso ao modelo | +| `402` | Saldo insuficiente | Adicione créditos em [venice.ai/settings/api](https://venice.ai/settings/api) | +| `429` | Limite de taxa excedido ou modelo sobrecarregado | Tente novamente com backoff; verifique o cabeçalho `Retry-After` | +| `500` | Falha no processamento da inferência | Tente novamente | +| `503` | Modelo em capacidade máxima | Tente novamente após um pequeno atraso | + +Veja a referência completa de [Códigos de erro](/api-reference/error-codes) para detalhes. + +## Relacionados + +- [Geração de imagens](/guides/media/image-generation) — o guia completo de geração, incluindo dimensionamento, estilos e respostas binárias. +- [Edição de imagens](/guides/media/image-editing) — edições de imagem única, requisições multi-edit em camadas e respostas binárias. +- [Gerar imagens (referência da API)](/api-reference/endpoint/image/generate) — todos os campos de requisição e resposta para `POST /image/generate`. +- [Editar imagem (referência da API)](/api-reference/endpoint/image/edit) — campos de requisição para `POST /image/edit`. +- [Multi-Edit de imagem (referência da API)](/api-reference/endpoint/image/multi-edit) — campos de requisição para `POST /image/multi-edit`. +- [Modelos de imagem](/models/image) — lista de modelos, preços e `promptCharacterLimit` por modelo. diff --git a/zh/guides/media/image-editing.mdx b/zh/guides/media/image-editing.mdx index 1c791972..5122774c 100644 --- a/zh/guides/media/image-editing.mdx +++ b/zh/guides/media/image-editing.mdx @@ -29,6 +29,10 @@ Venice 上的图像编辑是同步的。将源图像发送到 `/image/edit` 或 对于 inpainting，请使用 `/image/edit` 或 `/image/multi-edit`。`/image/generate` 上旧的 `inpaint` 参数已弃用。 + +在任一编辑端点上设置 `enhance_prompt: true`，即可让带视觉理解能力的增强器分析输入的一张或多张图像，并在编辑前重写您的指令。有关行为、定价和响应头详情，请参见 [Prompt 增强](/guides/media/prompt-enhancement)。 + + ## 第 1 步：编辑单张图像 单图像编辑是最简单的 inpainting 流程。发送一张图像加一个简短 prompt，例如 "remove the sign"、"change the sky to sunrise" 或 "replace the background with a studio backdrop"。 @@ -211,6 +215,7 @@ curl https://api.venice.ai/api/v1/image/background-remove \ | `prompt` | string | 是 | - | 编辑的文本指令 | | `model` | string | 否 | `qwen-edit` | 编辑模型 ID | | `aspect_ratio` | string | 否 | 模型默认 | 支持的模型的输出比例 | +| `enhance_prompt` | boolean | 否 | `false` | 分析输入图像并在推理前重写编辑指令 | | `modelId` | string | 已弃用 | - | `model` 的已弃用别名 | ### `/image/multi-edit` @@ -220,6 +225,7 @@ curl https://api.venice.ai/api/v1/image/background-remove \ | `images` | 1-3 个文件、base64 字符串或 URL 的数组 | 是 | - | 第一张是基础图像；其余为编辑层或遮罩 | | `prompt` | string | 是 | - | 关于如何组合或编辑层的文本指令 | | `modelId` | string | 否 | `qwen-edit` | 编辑模型 ID | +| `enhance_prompt` | boolean | 否 | `false` | 分析输入图像并在推理前重写编辑指令 | ### `/image/background-remove` @@ -244,7 +250,7 @@ curl https://api.venice.ai/api/v1/image/background-remove \ ## 模型和定价 -默认编辑模型是 `qwen-edit`，价格为**每次编辑 $0.04**。其他具备编辑能力的模型可能有不同的定价和限制。 +默认编辑模型是 `qwen-edit`，价格为**每次编辑 $0.04**。其他具备编辑能力的模型可能有不同的定价和限制。Prompt 增强会在编辑价格上叠加**每次成功应用的重写 $0.04**。 请参阅： @@ -274,5 +280,6 @@ curl https://api.venice.ai/api/v1/image/background-remove \ ## 相关工作流 - 如果您从文本而非现有图像开始，请使用[图像生成](/guides/media/image-generation)。 +- 使用 [Prompt 增强](/guides/media/prompt-enhancement)了解带视觉理解能力的编辑重写是如何工作的。 - 使用[图像模型](/models/image)比较生成、编辑和增强模型家族。 - 使用 [Image Edit API](/api-reference/endpoint/image/edit)、[Multi-Edit API](/api-reference/endpoint/image/multi-edit) 和 [Background Remove API](/api-reference/endpoint/image/background-remove) 了解完整 schema 细节。 diff --git a/zh/guides/media/prompt-enhancement.mdx b/zh/guides/media/prompt-enhancement.mdx new file mode 100644 index 00000000..ee23803a --- /dev/null +++ b/zh/guides/media/prompt-enhancement.mdx @@ -0,0 +1,227 @@ +--- +title: "Prompt 增强" +description: "使用 Venice 的 enhance_prompt 参数自动重写图像生成和编辑的 prompt，补充更清晰的视觉细节并提升输出质量。" +'og:title': "Prompt Enhancement | Venice API Docs" +'og:description': "Learn how to use the enhance_prompt parameter on Venice's image generation and editing APIs to expand short prompts into richer, more detailed descriptions." +--- + +Prompt 增强会在图像生成或编辑之前重写您的 prompt，补充清晰的视觉细节，把简短或稀疏的描述扩展为更丰富的 prompt，让图像模型更可靠地按其执行。在 `POST /image/generate`、`POST /image/edit` 或 `POST /image/multi-edit` 上设置 `enhance_prompt: true` 即可启用。 + +对于图像生成，这与 Venice web 应用中"魔法棒"背后的增强功能相同。对于图像编辑，则会使用带视觉理解能力的增强器，根据输入的一张或多张图像来澄清您的编辑指令。 + +## 何时使用 + +Prompt 增强在以下场景中最有用： + +- 您的 prompt 很短（几个词或单个短语），并且希望模型自行补充构图、光照和氛围。 +- 您正在构建的产品中，终端用户输入的是随意的 prompt，可以从扩展中受益。 +- 您正在编辑一张图像，并希望指令能结合可见内容进行改写。 +- 您希望在不手动撰写长 prompt 的情况下获得更一致、更详细的输出。 + +如果您已经发送经过精心撰写的长 prompt，通常关闭增强会得到更好的控制。 + +## 第 1 步：发送启用增强的请求 + +在任何标准图像生成请求中添加 `enhance_prompt: true`。 + +```bash +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"` 重写为更详细的 prompt，然后使用重写后的文本进行生成。请求的其余行为与普通生成调用完全相同。 + + +增强会在生成开始前额外增加最多约 30 秒，因为重写是由一次单独的模型调用产生的。请在客户端超时中考虑到这一点。 + + +## 第 2 步：从响应头中读取增强后的 prompt + +当发生重写时，Venice 会将最终 prompt 以 URL 编码形式通过 `x-venice-enhanced-prompt` 响应头返回。解码后即可查看、记录或展示实际发送给图像模型的内容。 + + +```python Python +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 +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); +``` + + +只有当实际生成并应用了重写时，才会出现 `x-venice-enhanced-prompt` 响应头。如果增强被跳过或失败，则不会出现该响应头，并使用您的原始 prompt。 + +## 在图像编辑中使用增强 + +编辑端点使用带视觉理解能力的增强器，会在重写指令之前分析输入的一张或多张图像。这有助于把 `"make it winter"` 这样简短的请求转化为更具体的编辑，同时保留相关主体和构图。 + +对于单图像编辑，可以在 JSON 或 multipart 请求中包含 `enhance_prompt`： + +```bash +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 + }' +``` + +对于 multi-edit，请对 `images` 数组使用同一参数： + +```bash +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 + }' +``` + +两个编辑端点都会以二进制数据返回编辑后的图像。与生成一样，可以查看并对 `x-venice-enhanced-prompt` 进行 URL 解码，以查看已应用的重写内容。 + +## 行为 + +| 方面 | 行为 | +|---|---| +| 支持的端点 | `POST /image/generate`、`POST /image/edit` 和 `POST /image/multi-edit` | +| 默认值 | `enhance_prompt` 默认为 `false`；除非您显式开启，否则不会进行增强。 | +| 失败宽容 | 如果重写因任何原因失败，生成或编辑会继续使用您的原始 prompt。请求不会因为增强而报错。 | +| 图像感知的编辑 | 在编辑请求中，增强器会在重写指令时分析所提供的一张或多张图像。 | +| 字符长度限制 | 对于生成，增强后的 prompt 会被截断至所选模型的 `promptCharacterLimit`（参见 [Models API](/api-reference/endpoint/models/list)）。 | +| 安全模式 | 对于生成请求，增强过程会遵循 `safe_mode`。当 `safe_mode: true` 时，重写内容会保持 SFW。 | +| 响应头 | 当应用增强时，最终 prompt 会以 URL 编码形式通过 `x-venice-enhanced-prompt` 返回。 | + +## 定价 + +Prompt 增强按**每次成功应用的重写 \$0.04** 的固定附加费计费，叠加在正常的图像生成费用之上。 + +计费规则： + +- 仅当实际生成并应用了重写时才会计费。如果增强被跳过或失败回退到您的原始 prompt，则不收取附加费。 +- 附加费在图像成功路径上计费。如果生成以内容违规结束，则不收取增强费用。 +- 当您使用 `variants` 请求多张图像时，共享的重写在每个请求中**最多计费一次**，而非按每个 variant 计费。 + +图像生成的基础费用请参见[定价](/overview/pricing)。 + +## 将增强与 variants 一起使用 + +在探索创意时，增强与 `variants` 搭配效果很好：生成一次重写，然后在所有 variant 之间复用，这样您只需支付一次 \$0.04 附加费。 + +```bash +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 + }' +``` + + +`variants` 仅在 `return_binary` 为 `false` 时受支持。详情参见[图像生成](/guides/media/image-generation)。 + + +## Prompt 技巧 + +1. 让您的输入 prompt 专注于主体和任何不可协商的细节。增强会围绕它补充风格、光照和构图。 +2. 在开发阶段记录 `x-venice-enhanced-prompt` 响应头，以便了解增强添加了哪些内容，并决定何时更愿意手工撰写 prompt。 +3. 为了在一批生成中获得可复用的结果，先启用增强生成一次，从响应头中捕获增强后的 prompt，然后关闭 `enhance_prompt` 复用该确切文本。 +4. 对于图像生成，将捕获的 prompt 与固定的 `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) — 单图像编辑、分层 multi-edit 请求和二进制响应。 +- [生成图像（API 参考）](/api-reference/endpoint/image/generate) — `POST /image/generate` 的每个请求和响应字段。 +- [编辑图像（API 参考）](/api-reference/endpoint/image/edit) — `POST /image/edit` 的请求字段。 +- [多图像编辑（API 参考）](/api-reference/endpoint/image/multi-edit) — `POST /image/multi-edit` 的请求字段。 +- [图像模型](/models/image) — 模型列表、定价及每个模型的 `promptCharacterLimit`。