توليد الصور

أنشئ صورًا من موجّهات نصية باستخدام واجهة Venice الأصلية للصور أو نقطة نهاية الصور المتوافقة مع OpenAI

توليد الصور في 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: فكّ ترميز الصورة وحفظها

Python

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

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.

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"
}

استخدم نقطة نهاية الأنماط عندما تريد أسماء الأنماط الجاهزة الدقيقة بدلًا من تخمينها.

---

​

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

المعامل	النوع	مطلوب	الافتراضي	الوصف
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
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 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 إذا كنت بحاجة إلى اكتشاف نتائج الإشراف برمجيًا.

---

​

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

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