الانتقال إلى المحتوى الرئيسي
توليد الصور في 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. مثال على تحديد الأبعاد بالبكسل: 
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"
}
مثال على تحديد الأبعاد بنسبة العرض إلى الارتفاع: 
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"
}
مثال على تحديد الأبعاد بفئة الدقة: 
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"
}
ينطبق النمط نفسه على نماذج فئات الدقة الأخرى: 
{
  "model": "nano-banana-pro",
  "prompt": "A serene canal in Venice at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
استخدم نماذج الصور أو Models API للتأكد من حقول الأبعاد التي يقبلها كل نموذج. الاستجابة (200): 
{
  "id": "generate-image-1234567890",
  "images": [
    "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..."
  ],
  "timing": {
    "inferenceDuration": 1840,
    "inferencePreprocessingTime": 22,
    "inferenceQueueTime": 31,
    "total": 1893
  }
}
تحتوي المصفوفة images على بيانات الصورة مرمّزة بـ base64. فُكّ ترميز أول عنصر لحفظ الصورة أو عرضها. القيمة timing.total هي إجمالي مدة الطلب بالملي ثانية.

​
الخطوة 2: فكّ ترميز الصورة وحفظها

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']}")

​
الخطوة 3: إرجاع بيانات ثنائية بدلاً من JSON (اختياري)

إذا أردت أن يكون جسم الاستجابة هو ملف الصورة نفسه، فاضبط return_binary: true. هذا مفيد عندما تريد بثّ الصورة أو حفظها مباشرة دون الحاجة إلى فك ترميز base64. 
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: 
curl https://api.venice.ai/api/v1/image/styles \
  -H "Authorization: Bearer $VENICE_API_KEY"
الاستجابة (200): 
[
  "3D Model",
  "Analog Film",
  "Anime",
  "Cinematic",
  "Digital Art"
]
ثم مرّر إحدى تلك القيم إلى طلب التوليد: 
{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "Cinematic"
}
استخدم نقطة نهاية الأنماط عندما تريد أسماء الأنماط الجاهزة الدقيقة بدلًا من تخمينها.

​
معاملات الطلب

المعاملالنوعمطلوبالافتراضيالوصف
modelstringنعم-معرّف النموذج المستخدم في التوليد
promptstringنعم-ما المطلوب توليده
negative_promptstringلا-ما يجب تجنبه في الصورة
widthintegerلا1024عرض الإخراج بالبكسل للنماذج المعتمدة على البكسل مثل venice-sd35 وqwen-image
heightintegerلا1024ارتفاع الإخراج بالبكسل للنماذج المعتمدة على البكسل مثل venice-sd35 وqwen-image
formatstringلاwebpصيغة الإخراج: jpeg أو png أو webp
variantsintegerلا1عدد الصور المراد توليدها (من 1 إلى 4)، فقط عندما تكون return_binary بقيمة false
return_binarybooleanلاfalseإرجاع بايتات الصورة الخام بدلًا من JSON بصيغة base64
safe_modebooleanلاtrueتشويش المحتوى للبالغين عند التفعيل
seedintegerلاعشوائيأعد استخدام نفس البذرة (seed) لتكرارات أكثر اتساقًا
cfg_scalenumberلايعتمد على النموذجالقيم الأعلى تدفع النموذج لاتباع الموجّه بدقة أكبر
style_presetstringلا-تطبيق نمط جاهز من Image Styles
aspect_ratiostringشرطي-يستخدم في النماذج التي تدعم تحديد الأبعاد بالنسبة، مثل qwen-image-2 وgpt-image-2 وnano-banana-2 وnano-banana-pro
resolutionstringشرطي-يستخدم في النماذج التي تدعم فئات دقة مثل 1K أو 2K أو 4K
enable_web_searchbooleanشرطيfalseيسمح للنماذج المدعومة باستخدام معلومات الويب الحالية؛ يضيف تكلفة إضافية
التحقق من الصحة يعتمد على النموذج. راجع نماذج الصور وModels API قبل الاعتماد على معامل عبر عدة نماذج.

​
خيارات خاصة بكل نموذج

​
التوليد بدقة عالية

تدعم بعض نماذج الصور aspect_ratio دون فئة resolution قابلة للاختيار. على سبيل المثال، يقبل qwen-image-2 نسبة العرض إلى الارتفاع ويربطها بأبعاد إخراج خاصة بالنموذج: 
{
  "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: 
{
  "model": "gpt-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "4K"
}

{
  "model": "nano-banana-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
استخدم نماذج الصور لمعرفة النماذج التي تدعم دقات أعلى وكيفية تسعيرها.

​
الأنماط الجاهزة (Style Presets)

إذا كان النموذج المختار يدعم ذلك، فإن style_preset يتيح لك توجيه المخرجات دون إعادة كتابة الموجّه بأكمله. يمكنك جلب أسماء الأنماط الصالحة من Image Styles: 
{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "3D Model"
}
راجع Image Styles للاطلاع على قائمة الأنماط الحالية.

​
نقطة النهاية المتوافقة مع OpenAI

إذا كنت تستخدم بالفعل حِزم OpenAI للصور أو لديك تكاملات قائمة مع DALL-E، فإن Venice تدعم أيضًا POST /images/generations. توفّر صيغة طلب أبسط ولكن بميزات أقل من نقطة نهاية Venice الأصلية. الطلب: 
{
  "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
415نوع المحتوى غير صالحأرسل JSON مع Content-Type: application/json
429تجاوز حد المعدّل أو النموذج محمّل بأقصى طاقتهأعد المحاولة مع تأخير تصاعدي؛ افحص ترويسة Retry-After
500فشل في معالجة الاستدلالأعد إرسال الطلب
503النموذج بكامل طاقتهأعد المحاولة بعد تأخير قصير
عند تفعيل Safe Venice، افحص ترويسات الاستجابة مثل x-venice-is-blurred وx-venice-is-content-violation إذا كنت بحاجة إلى اكتشاف نتائج الإشراف برمجيًا.

​
النماذج المتاحة

راجع نماذج الصور للاطلاع على قائمة النماذج الحالية، والتسعير، والميزات المدعومة.