> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-docs-revamp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# توليد الصور
> أنشئ صورًا من موجّهات نصية باستخدام واجهة 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`.
**مثال على تحديد الأبعاد بالبكسل:**
```bash theme={"dark"}
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={"dark"}
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={"dark"}
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={"dark"}
{
"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={"dark"}
{
"id": "generate-image-1234567890",
"images": [
"UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..."
],
"timing": {
"inferenceDuration": 1840,
"inferencePreprocessingTime": 22,
"inferenceQueueTime": 31,
"total": 1893
}
}
```
تحتوي المصفوفة `images` على بيانات الصورة مرمّزة بـ base64. فُكّ ترميز أول عنصر لحفظ الصورة أو عرضها. القيمة `timing.total` هي إجمالي مدة الطلب بالملي ثانية.
## الخطوة 2: فكّ ترميز الصورة وحفظها
```python Python theme={"dark"}
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={"dark"}
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={"dark"}
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={"dark"}
curl https://api.venice.ai/api/v1/image/styles \
-H "Authorization: Bearer $VENICE_API_KEY"
```
**الاستجابة (200):**
```json theme={"dark"}
[
"3D Model",
"Analog Film",
"Anime",
"Cinematic",
"Digital Art"
]
```
ثم مرّر إحدى تلك القيم إلى طلب التوليد:
```json theme={"dark"}
{
"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={"dark"}
{
"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={"dark"}
{
"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={"dark"}
{
"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={"dark"}
{
"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={"dark"}
{
"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) للاطلاع على قائمة النماذج الحالية، والتسعير، والميزات المدعومة.