> ## Documentation Index > Fetch the complete documentation index at: https://docs.venice.ai/llms.txt > Use this file to discover all available pages before exploring further. # توليد الصور > أنشئ صورًا من موجّهات نصية باستخدام Venice API الأصلية للصور أو endpoint الصور المتوافقة مع OpenAI، مع تحكّم بالأسلوب ومخرجات ثنائية أو base64. توليد الصور في Venice متزامن. أرسل موجّهًا إلى `/image/generate` لتتلقى صورتك في الاستجابة ذاتها، إما بصيغة base64 داخل JSON أو كبيانات ثنائية خام عندما تكون `return_binary` بقيمة `true`. ## نقاط النهاية | نقطة النهاية | الغرض | متى تستخدمها | | -------------------------- | --------------------------------- | ------------------------------------------ | | `POST /image/generate` | واجهة Venice الأصلية لتوليد الصور | استخدمها للحصول على الدعم الكامل للميزات | | `GET /image/styles` | قائمة بالأنماط الجاهزة المتاحة | استخدمها قبل إرسال `style_preset` | | `POST /images/generations` | واجهة توليد صور متوافقة مع OpenAI | استخدمها عند نقل عملاء صور OpenAI الحاليين | ## الخطوة 1: إرسال طلب توليد تحديد الأبعاد يعتمد على النموذج. بعض النماذج تقبل `width` و`height` صريحَين، وبعضها يكشف عن `aspect_ratio`، ونماذج فئات الدقة تكشف عن `aspect_ratio` بالإضافة إلى قيم `resolution` مثل `1K` أو `2K` أو `4K`. **مثال على تحديد الأبعاد بالبكسل:** ```bash theme={"system"} POST https://api.venice.ai/api/v1/image/generate Authorization: Bearer $VENICE_API_KEY Content-Type: application/json { "model": "venice-sd35", "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water", "negative_prompt": "blurry, low quality, distorted anatomy, text, watermark", "width": 1024, "height": 1024, "format": "webp" } ``` **مثال على تحديد الأبعاد بنسبة العرض إلى الارتفاع:** ```bash theme={"system"} POST https://api.venice.ai/api/v1/image/generate Authorization: Bearer $VENICE_API_KEY Content-Type: application/json { "model": "qwen-image-2", "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour", "aspect_ratio": "16:9", "format": "webp" } ``` **مثال على تحديد الأبعاد بفئة الدقة:** ```bash theme={"system"} POST https://api.venice.ai/api/v1/image/generate Authorization: Bearer $VENICE_API_KEY Content-Type: application/json { "model": "gpt-image-2", "prompt": "A cinematic wide shot of a gondola passing through a narrow Venice canal at blue hour", "aspect_ratio": "16:9", "resolution": "4K", "format": "png" } ``` ينطبق النمط نفسه على نماذج فئات الدقة الأخرى: ```json theme={"system"} { "model": "nano-banana-pro", "prompt": "A serene canal in Venice at sunset", "aspect_ratio": "16:9", "resolution": "2K" } ``` استخدم [نماذج الصور](/models/image) أو [Models API](/api-reference/endpoint/models/list) للتأكد من حقول الأبعاد التي يقبلها كل نموذج. **الاستجابة (200):** ```json theme={"system"} { "id": "generate-image-1234567890", "images": [ "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..." ], "timing": { "inferenceDuration": 1840, "inferencePreprocessingTime": 22, "inferenceQueueTime": 31, "total": 1893 } } ``` تحتوي المصفوفة `images` على بيانات الصورة مرمّزة بـ base64. فُكّ ترميز أول عنصر لحفظ الصورة أو عرضها. القيمة `timing.total` هي إجمالي مدة الطلب بالملي ثانية. ## الخطوة 2: فكّ ترميز الصورة وحفظها ```python Python theme={"system"} import base64 import os 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 cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water", "width": 1024, "height": 1024, "format": "webp", }, ) data = response.json() image_bytes = base64.b64decode(data["images"][0]) with open("output.webp", "wb") as f: f.write(image_bytes) print(f"Saved image from request {data['id']}") ``` ```javascript Node.js theme={"system"} import fs from "fs"; const response = await fetch("https://api.venice.ai/api/v1/image/generate", { method: "POST", headers: { Authorization: `Bearer ${process.env.VENICE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "venice-sd35", prompt: "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water", width: 1024, height: 1024, format: "webp", }), }); const data = await response.json(); const imageBuffer = Buffer.from(data.images[0], "base64"); fs.writeFileSync("output.webp", imageBuffer); console.log(`Saved image from request ${data.id}`); ``` ## الخطوة 3: إرجاع بيانات ثنائية بدلاً من JSON (اختياري) إذا أردت أن يكون جسم الاستجابة هو ملف الصورة نفسه، فاضبط `return_binary: true`. هذا مفيد عندما تريد بثّ الصورة أو حفظها مباشرة دون الحاجة إلى فك ترميز base64. ```bash theme={"system"} curl https://api.venice.ai/api/v1/image/generate \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -o output.png \ -d '{ "model": "qwen-image-2", "prompt": "Minimalist poster of a moonlit Venetian bridge in deep blue tones", "format": "png", "return_binary": true }' ``` عندما تكون `return_binary` بقيمة `true`، يكون جسم الاستجابة بيانات `image/jpeg` أو `image/png` أو `image/webp` خام بحسب `format` الذي طلبته. الحقل `variants` مدعوم فقط عندما تكون `return_binary` بقيمة `false`. *** ## الخطوة 4: عرض أنماط الصور المتاحة (اختياري) إذا أردت استخدام `style_preset`، فاحضر أولًا الأنماط المتاحة من `/image/styles`: ```bash theme={"system"} curl https://api.venice.ai/api/v1/image/styles \ -H "Authorization: Bearer $VENICE_API_KEY" ``` **الاستجابة (200):** ```json theme={"system"} [ "3D Model", "Analog Film", "Anime", "Cinematic", "Digital Art" ] ``` ثم مرّر إحدى تلك القيم إلى طلب التوليد: ```json theme={"system"} { "model": "qwen-image-2", "prompt": "A futuristic Venice skyline at sunrise", "style_preset": "Cinematic" } ``` استخدم نقطة نهاية الأنماط عندما تريد أسماء الأنماط الجاهزة الدقيقة بدلًا من تخمينها. *** ## معاملات الطلب | المعامل | النوع | مطلوب | الافتراضي | الوصف | | ------------------- | ------- | ----- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | | `model` | string | نعم | - | معرّف النموذج المستخدم في التوليد | | `prompt` | string | نعم | - | ما المطلوب توليده | | `negative_prompt` | string | لا | - | ما يجب تجنبه في الصورة | | `width` | integer | لا | `1024` | عرض الإخراج بالبكسل للنماذج المعتمدة على البكسل مثل `venice-sd35` و`qwen-image` | | `height` | integer | لا | `1024` | ارتفاع الإخراج بالبكسل للنماذج المعتمدة على البكسل مثل `venice-sd35` و`qwen-image` | | `format` | string | لا | `webp` | صيغة الإخراج: `jpeg` أو `png` أو `webp` | | `variants` | integer | لا | `1` | عدد الصور المراد توليدها (من `1` إلى `4`)، فقط عندما تكون `return_binary` بقيمة `false` | | `return_binary` | boolean | لا | `false` | إرجاع بايتات الصورة الخام بدلًا من JSON بصيغة base64 | | `safe_mode` | boolean | لا | `true` | تشويش المحتوى للبالغين عند التفعيل | | `seed` | integer | لا | عشوائي | أعد استخدام نفس البذرة (seed) لتكرارات أكثر اتساقًا | | `cfg_scale` | number | لا | يعتمد على النموذج | القيم الأعلى تدفع النموذج لاتباع الموجّه بدقة أكبر | | `style_preset` | string | لا | - | تطبيق نمط جاهز من [Image Styles](/api-reference/endpoint/image/styles) | | `aspect_ratio` | string | شرطي | - | يستخدم في النماذج التي تدعم تحديد الأبعاد بالنسبة، مثل `qwen-image-2` و`gpt-image-2` و`nano-banana-2` و`nano-banana-pro` | | `resolution` | string | شرطي | - | يستخدم في النماذج التي تدعم فئات دقة مثل `1K` أو `2K` أو `4K` | | `enable_web_search` | boolean | شرطي | `false` | يسمح للنماذج المدعومة باستخدام معلومات الويب الحالية؛ يضيف تكلفة إضافية | التحقق من الصحة يعتمد على النموذج. راجع [نماذج الصور](/models/image) و[Models API](/api-reference/endpoint/models/list) قبل الاعتماد على معامل عبر عدة نماذج. *** ## خيارات خاصة بكل نموذج ### التوليد بدقة عالية تدعم بعض نماذج الصور `aspect_ratio` دون فئة `resolution` قابلة للاختيار. على سبيل المثال، يقبل `qwen-image-2` نسبة العرض إلى الارتفاع ويربطها بأبعاد إخراج خاصة بالنموذج: ```json theme={"system"} { "model": "qwen-image-2", "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting", "aspect_ratio": "16:9" } ``` تدعم نماذج صور أخرى `aspect_ratio` بالإضافة إلى فئة `resolution`. على سبيل المثال، يدعم كل من `gpt-image-2` و`nano-banana-2` و`nano-banana-pro` الفئات `1K` و`2K` و`4K`: ```json theme={"system"} { "model": "gpt-image-2", "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting", "aspect_ratio": "16:9", "resolution": "4K" } ``` ```json theme={"system"} { "model": "nano-banana-2", "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting", "aspect_ratio": "16:9", "resolution": "2K" } ``` استخدم [نماذج الصور](/models/image) لمعرفة النماذج التي تدعم دقات أعلى وكيفية تسعيرها. ### الأنماط الجاهزة (Style Presets) إذا كان النموذج المختار يدعم ذلك، فإن `style_preset` يتيح لك توجيه المخرجات دون إعادة كتابة الموجّه بأكمله. يمكنك جلب أسماء الأنماط الصالحة من [Image Styles](/api-reference/endpoint/image/styles): ```json theme={"system"} { "model": "qwen-image-2", "prompt": "A futuristic Venice skyline at sunrise", "style_preset": "3D Model" } ``` راجع [Image Styles](/api-reference/endpoint/image/styles) للاطلاع على قائمة الأنماط الحالية. *** ## نقطة النهاية المتوافقة مع OpenAI إذا كنت تستخدم بالفعل حِزم OpenAI للصور أو لديك تكاملات قائمة مع DALL-E، فإن Venice تدعم أيضًا `POST /images/generations`. توفّر صيغة طلب أبسط ولكن بميزات أقل من نقطة نهاية Venice الأصلية. **الطلب:** ```json theme={"system"} { "model": "qwen-image-2", "prompt": "A clean isometric illustration of an AI control room", "size": "1024x1024", "response_format": "b64_json" } ``` استخدم المسار المتوافق مع OpenAI لتسريع عمليات الانتقال. واستخدم `/image/generate` عندما تحتاج إلى خيارات خاصة بـ Venice مثل `cfg_scale` أو `style_preset` أو `variants` أو الاستجابات الثنائية. *** ## نصائح للموجّهات (Prompting) 1. ابدأ بالموضوع، ثم أضف الوسيلة والإضاءة والتركيب والمزاج. 2. ضع التفاصيل التي يجب تجنبها في `negative_prompt` بدلًا من إثقال الموجّه الرئيسي. 3. أعد استخدام `seed` أثناء التكرار حتى تتمكن من مقارنة تغييرات الموجّه دون تغيير التركيبة بالكامل. 4. اجعل تحديد الأبعاد متوافقًا مع النموذج. بعض النماذج تستخدم `width`/`height`، والبعض يستخدم `aspect_ratio`، أما نماذج فئات الدقة فتستخدم `aspect_ratio` بالإضافة إلى `resolution`. 5. استخدم `variants` أثناء الاستكشاف، ثم عُد إلى مخرج واحد بمجرد تحديد الاتجاه. *** ## الأخطاء | الحالة | المعنى | الإجراء | | ------ | --------------------------------------------- | ----------------------------------------------------------------------- | | `400` | معاملات الطلب غير صالحة | تحقّق من أسماء الحقول وأنواعها والقيود الخاصة بالنموذج | | `401` | فشل المصادقة أو يتطلب النموذج فئة وصول أعلى | تحقّق من مفتاح API وصلاحية الوصول للنموذج | | `402` | الرصيد غير كافٍ | أضف رصيدًا عبر [venice.ai/settings/api](https://venice.ai/settings/api) | | `415` | نوع المحتوى غير صالح | أرسل JSON مع `Content-Type: application/json` | | `429` | تجاوز حد المعدّل أو النموذج محمّل بأقصى طاقته | أعد المحاولة مع تأخير تصاعدي؛ افحص ترويسة `Retry-After` | | `500` | فشل في معالجة الاستدلال | أعد إرسال الطلب | | `503` | النموذج بكامل طاقته | أعد المحاولة بعد تأخير قصير | عند تفعيل Safe Venice، افحص ترويسات الاستجابة مثل `x-venice-is-blurred` و`x-venice-is-content-violation` إذا كنت بحاجة إلى اكتشاف نتائج الإشراف برمجيًا. *** ## النماذج المتاحة راجع [نماذج الصور](/models/image) للاطلاع على قائمة النماذج الحالية، والتسعير، والميزات المدعومة.