تحرير الصور

حرّر الصور، وأجرِ inpaint، وأزل الخلفيات باستخدام Venice API عبر /image/edit، وطبقات التحرير المتعدد، والأقنعة، وعناصر التحكم في الوضع الآمن.

تحرير الصور في Venice متزامن. أرسل صورتك المصدر إلى /image/edit أو /image/multi-edit فتعود النتيجة المحرَّرة في الاستجابة ذاتها كملف صورة خام. أما للقصاصات (Cutouts)، فإن /image/background-remove يُعيد ملف PNG شفافًا.

نقاط نهاية تحرير الصور تجريبية، وقد يتغير السلوك الخاص بكل نموذج بمرور الوقت.

​

نقاط النهاية

نقطة النهاية	الغرض	الأنسب لـ
POST /image/edit	تحرير صورة واحدة باستخدام موجّه	التعديلات العامة والإصلاح الموضعي المعتمد على الموجّه
POST /image/multi-edit	تحرير باستخدام 1-3 صور متراكبة	تعديلات أكثر تحكمًا باستخدام أقنعة أو طبقات
POST /image/background-remove	إزالة الخلفية من صورة	قصاصات شفافة للمنتجات والصور الشخصية والأصول

لا توفّر Venice نقطة نهاية /images/edits متوافقة مع OpenAI. مسار الصور الوحيد المتوافق مع OpenAI هو POST /images/generations للتوليد. أما للتحرير، فاستخدم نقطة النهاية الأصلية POST /image/edit.

​

متى تستخدم كل نقطة نهاية

• استخدم /image/edit عندما تمتلك صورة مصدر واحدة وترغب في تغيير جزء منها أو إزالته أو إعادة تنسيقه بموجّه.
• استخدم /image/multi-edit عندما تحتاج إلى تحكم إضافي عبر الأقنعة أو الطبقات أو الطبقات المرجعية.
• استخدم /image/background-remove عندما تريد فقط استخراج موضوع المقدمة بشفافية نظيفة.

للإصلاح الموضعي (Inpainting)، استخدم /image/edit أو /image/multi-edit. أما المعامل القديم inpaint في /image/generate فقد تم إيقافه.

اضبط enhance_prompt: true على أي من نقطتَي نهاية التحرير ليُحلِّل مُحسِّنٌ مدرك للرؤية الصورة أو الصور المُدخلة ويعيد كتابة تعليمتك قبل التحرير. راجع تحسين الموجّهات للاطلاع على السلوك والتسعير وتفاصيل ترويسة الاستجابة.

​

الخطوة 1: تحرير صورة واحدة

تحرير الصورة الواحدة هو أبسط تدفق إصلاح موضعي. أرسل صورة واحدة مع موجّه قصير مثل “remove the sign” أو “change the sky to sunrise” أو “replace the background with a studio backdrop”.

الطلب:

POST https://api.venice.ai/api/v1/image/edit
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "qwen-edit",
  "prompt": "Replace the cloudy sky with a warm sunrise while preserving the buildings and canal",
  "image": "https://example.com/venice-canal.jpg"
}

الاستجابة (200): يحتوي جسم الاستجابة على بيانات صورة ثنائية خام. احفظها مباشرة في ملف. راجع صيغة الاستجابة لمعرفة كيف يتحكّم output_format في نوع الملف.

Python

import base64
import os
import requests

with open("input.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.venice.ai/api/v1/image/edit",
    headers={
        "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-edit",
        "prompt": "Remove the tourist crowd from the square and keep the architecture intact",
        "image": image_base64,
    },
)

with open("edited.png", "wb") as f:
    f.write(response.content)

​

الخطوة 2: استخدم multi-edit للأقنعة أو الإصلاح الموضعي بالطبقات

تقبل نقطة النهاية /image/multi-edit ما يصل إلى ثلاث صور. الصورة الأولى هي الصورة الأساسية، أما الصور المتبقية فيُتعامل معها كطبقات تحرير أو أقنعة، مما يمنحك تحكمًا أكبر من التحرير المعتمد على الموجّه فقط.

هذا هو الخيار الأفضل عندما تريد:

• استهداف منطقة محددة باستخدام قناع
• دمج تركيبة موجودة مع طبقة فوقها
• تقييد التحرير بشكل أدق مما يسمح به موجّه صورة واحدة

طلب JSON:

{
  "modelId": "qwen-edit",
  "prompt": "Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective",
  "images": [
    "https://example.com/street-scene.png",
    "https://example.com/billboard-mask.png"
  ]
}

طلب Multipart:

curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "modelId=qwen-edit" \
  -F "prompt=Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective" \
  -F "images=@street-scene.png" \
  -F "images=@billboard-mask.png" \
  -o multi-edited.png

كما هو الحال في /image/edit، يكون جسم الاستجابة بيانات صورة خام.

تستخدم نقطة النهاية /image/multi-edit حاليًا الحقل modelId بدلاً من model في مخطط الطلب.

---

​

نصائح للإصلاح الموضعي

يعمل الإصلاح الموضعي المعتمد على الموجّه بأفضل شكل عندما تكون التعليمة قصيرة ومحلية:

• remove the tree
• change the sky to sunset
• replace the logo with a blank sign
• restore the torn corner of the photo

أما لتغييرات المشهد الأوسع، فاوصف ما يجب أن يبقى كما هو:

Replace the background with a modern photo studio backdrop while preserving the subject pose, facial features, and clothing.

إذا استمر التحرير في التأثير على المنطقة الخطأ، فانتقل من /image/edit إلى /image/multi-edit وزوّد طبقة قناع أو طبقة فوقية.

---

​

الخطوة 3: إزالة الخلفية

استخدم /image/background-remove عندما تريد عزل موضوع المقدمة على خلفية شفافة. تُعيد نقطة النهاية هذه ملف PNG بقناة شفافية (alpha).

باستخدام رابط صورة:

curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o cutout.png \
  -d '{
    "image_url": "https://example.com/product-photo.jpg"
  }'

باستخدام رفع ملف محلي:

curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "image=@product-photo.jpg" \
  -o cutout.png

استخدم إزالة الخلفية لـ:

• صور منتجات التجارة الإلكترونية
• الصور الشخصية وصور الملف الشخصي
• الأصول التي تنوي وضعها فوق خلفية جديدة

---

​

صيغة الاستجابة

تُعيد /image/edit و/image/multi-edit دائمًا الصورة المحرَّرة كبيانات ثنائية خام (image/png أو image/jpeg أو image/webp). لا تقبل نقطتا نهاية التحرير المعامل response_format. ولا يوجد خيار b64_json أو url كما في /images/generations. إذا كنت بحاجة إلى النتيجة داخل JSON، فقم بترميز الاستجابة الثنائية بـ base64 في الكود الخاص بك.

تحكّم في نوع الملف باستخدام output_format:

• يقبل output_format القيم jpeg أو jpg أو png أو webp.
• عند حذفه، تُستنتج الصيغة من resolution: تكون PNG لتحريرات 1K وJPEG لتحريرات 2K و4K.

---

​

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

​

/image/edit

المعامل	النوع	مطلوب	الافتراضي	الوصف
image	ملف، أو سلسلة base64، أو رابط URL	نعم	-	الصورة المصدر المراد تحريرها
prompt	string	نعم	-	تعليمات نصية للتعديل
model	string	لا	qwen-edit	معرّف نموذج التحرير
aspect_ratio	string	لا	الافتراضي للنموذج	نسبة الإخراج للنماذج التي تدعمها
resolution	string	لا	1K	فئة الدقة للصورة الناتجة (1K، 2K، 4K)؛ تختلف القيم المدعومة بحسب النموذج
output_format	string	لا	يُستنتج من resolution	نوع ملف الإخراج: jpeg أو jpg أو png أو webp
enhance_prompt	boolean	لا	false	يحلّل الصورة المُدخلة ويعيد كتابة تعليمة التحرير قبل الاستدلال
safe_mode	boolean	لا	true	يشوّش المحتوى للبالغين في النتيجة المحرَّرة؛ اضبطه على false للتعطيل
modelId	string	متروك (Deprecated)	-	اسم مرادف متروك للحقل model

​

/image/multi-edit

المعامل	النوع	مطلوب	الافتراضي	الوصف
images	مصفوفة من 1-3 ملفات أو سلاسل base64 أو روابط URL	نعم	-	الصورة الأولى هي الأساسية؛ والباقي طبقات تحرير أو أقنعة
prompt	string	نعم	-	تعليمات نصية لكيفية دمج الطبقات أو تحريرها
modelId	string	لا	qwen-edit	معرّف نموذج التحرير
resolution	string	لا	1K	فئة الدقة للصورة الناتجة (1K، 2K، 4K)؛ تختلف القيم المدعومة بحسب النموذج
output_format	string	لا	يُستنتج من resolution	نوع ملف الإخراج: jpeg أو jpg أو png أو webp
enhance_prompt	boolean	لا	false	يحلّل الصور المُدخلة ويعيد كتابة تعليمة التحرير قبل الاستدلال
safe_mode	boolean	لا	true	يشوّش المحتوى للبالغين في النتيجة المحرَّرة؛ اضبطه على false للتعطيل

​

/image/background-remove

المعامل	النوع	مطلوب	الوصف
image	ملف أو سلسلة base64	أحد image أو image_url	الصورة المصدر المراد قصها
image_url	string	أحد image أو image_url	رابط عام للصورة المراد قصها

تستخدم /image/background-remove نموذجًا داخليًا ثابتًا. ولا تقبل حقل model. إرساله (على سبيل المثال "model": "bria-bg-remover") يُعيد 400 invalid model id.

​

المحتوى للبالغين والوضع الآمن

تقبل كل من /image/edit و/image/multi-edit المعامل safe_mode (القيمة الافتراضية: true). عند تفعيله، يُشوَّش المحتوى للبالغين في المخرجات المحرَّرة. اضبط safe_mode: false للحصول على مخرجات دون تشويش:

{
  "model": "qwen-edit-uncensored",
  "prompt": "…",
  "image": "…",
  "safe_mode": false
}

لا يزال نموذج التحرير الافتراضي qwen-edit يحجب الصور الجنسية الصريحة والعنف الواقعي بصرف النظر عن safe_mode. للتحرير غير الخاضع للرقابة، استخدم qwen-edit-uncensored.

يُربك اختلافُ تسمية الإشراف بين نقاط النهاية كثيرًا من المستخدمين:

نقطة النهاية	الحقل الذي يُعطّل التشويش
POST /image/edit, POST /image/multi-edit	safe_mode: false
POST /image/generate (التوليد الأصلي)	safe_mode: false
POST /images/generations (التوليد المتوافق مع OpenAI)	moderation: "low"

تمرير safe_mode إلى /images/generations يُعيد 400 مع الرسالة Unrecognized key(s) in object: 'safe_mode'.

---

​

صيغ الإدخال المدعومة

نقطة النهاية	إدخال JSON	إدخال Multipart	الإخراج
/image/edit	سلسلة Base64 أو رابط URL	رفع ملف	image/png أو image/jpeg أو image/webp بحسب output_format
/image/multi-edit	سلاسل Base64 أو روابط URL	رفع ملفات	image/png أو image/jpeg أو image/webp بحسب output_format
/image/background-remove	سلسلة Base64 أو رابط URL	رفع ملف	image/png

بالنسبة لنقاط نهاية التحرير، يجب أن تكون أبعاد الصورة 65536 بكسل على الأقل وألا تتجاوز 33177600 بكسل. ويجب أن تكون الملفات المرفوعة أقل من 25MB.

---

​

النماذج والتسعير

نموذج التحرير الافتراضي هو qwen-edit، بسعر 0.04 دولار لكل عملية تحرير. وقد تختلف أسعار وقيود النماذج الأخرى القادرة على التحرير. يضيف تحسين الموجّهات 0.04 دولار لكل إعادة كتابة مُطبَّقة إلى سعر التحرير.

راجع:

• تسعير الصور
• Models API باستخدام type=inpaint

---

​

الأخطاء

الحالة	المعنى	الإجراء
400	معاملات الطلب غير صالحة	تحقّق من عدد الصور وأسماء الحقول وصيغة الإدخال
401	فشل المصادقة	تحقّق من مفتاح API الخاص بك
402	الرصيد غير كافٍ	أضف رصيدًا عبر venice.ai/settings/api
415	نوع المحتوى غير صالح	استخدم JSON أو multipart form-data بشكل صحيح
429	تجاوز حد المعدّل أو النموذج محمّل بأقصى طاقته	أعد المحاولة مع تأخير تصاعدي؛ افحص ترويسة Retry-After
500	فشل في معالجة الاستدلال	أعد إرسال الطلب
503	النموذج بكامل طاقته	أعد المحاولة بعد تأخير قصير

بعض نماذج التحرير تتبنى سياسات محتوى أكثر صرامة من نماذج توليد الصور. على سبيل المثال، يحجب qwen-edit الطلبات التي تتضمن صورًا جنسية صريحة، أو قاصرين بصورة جنسية، أو عنفًا واقعيًا.

---

​

مسارات العمل ذات الصلة

• استخدم توليد الصور عندما تبدأ من نص بدلاً من صورة موجودة.
• استخدم تحسين الموجّهات لتتعرّف على كيفية عمل إعادة كتابة تحرير الصور المدركة للرؤية.
• استخدم نماذج الصور لمقارنة عائلات نماذج التوليد والتحرير والتحسين.
• استخدم Image Edit API وMulti-Edit API وBackground Remove API للاطلاع على تفاصيل المخطط الكاملة.