بداية سريعة لتحرير الصور باستخدام Qwen Image Edit عبر التعليمات النصية

تتيح واجهة برمجة تطبيقات Qwen Image Edit على Novita AI تعديل صورة موجودة باستخدام تعليمات بلغة طبيعية، مدعومة بنموذج Qwen-Image بحجم 20 مليار معمارية MMDiT ثنائية المسار. تغطي هذه البداية السريعة سير العمل غير المتزامن بالكامل: إرسال طلب تحرير مع الصورة المصدر والموجه، استلام معرف مهمة، الاستقصاء حتى اكتمال التحرير، واسترداد رابط الصورة المحررة. نقطة النهاية هي POST https://api.novita.ai/v3/async/qwen-image-edit.

جدول المحتويات

متى تستخدم هذه البداية السريعة

استخدم هذا الدليل عندما تحتاج إلى:

• تعديل صورة موجودة من خلال تعليمات نصية - تغيير الخلفيات، تبديل الأنماط، إزالة العناصر، تدوير الكائنات، أو ضبط الملابس دون إعادة بناء الصورة من الصفر.
• الحفاظ على المناطق غير المتأثرة سليمة أثناء تطبيق التعديلات المستهدفة. تم تصميم معمارية النموذج ثنائية المسار (Qwen2.5-VL للفهم الدلالي + مشفر VAE للحفاظ على المظهر) خصيصًا لمنع تسرب التعديلات إلى المناطق التي لم تصفها.
• تحرير النص في الصور بدقة. يتعامل Qwen Image Edit مع استبدال النص ثنائي اللغة (الإنجليزية والصينية) في اللافتات والملصقات والأصول ذات العلامات التجارية - مع الحفاظ على الخط والحجم والنمط البصري المحيط بطريقة تفشل فيها معظم مولدات الصور.

إذا كنت تقوم بإنشاء صورة جديدة من الموجه فقط (بدون صورة إدخال)، فاستخدم البداية السريعة لـ Qwen Image txt2img بدلاً من ذلك. للحصول على نظرة عامة كاملة على قدرات النموذج والمعايير والهندسة، راجع مقالة إطلاق Qwen-Image على Novita AI.

الخطوة 1: الحصول على مفتاح API من Novita

أنشئ حسابًا في Novita AI وانتقل إلى إدارة مفاتيح API. قم بإنشاء مفتاح واحفظه كمتغير بيئة قبل تشغيل أي من أمثلة الكود أدناه:

export NOVITA_API_KEY="your_api_key_here"

احتفظ بالمفتاح بعيدًا عن كود جانب العميل وحزم الواجهة الأمامية وأنظمة التحكم في الإصدارات. إذا تم اختراق المفتاح، قم بتدويره من نفس صفحة الإعدادات.

الخطوة 2: تأكيد نقطة النهاية والنموذج

العنصر	القيمة
نقطة نهاية التحرير	POST https://api.novita.ai/v3/async/qwen-image-edit
نقطة نهاية استقصاء النتيجة	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
النموذج	Qwen Image Edit (20B MMDiT، معمارية ثنائية المسار)
وثائق API	مرجع Novita AI Qwen Image Edit

واجهة API غير متزامنة. يعيد استدعاء التحرير معرف مهمة task_id فورًا؛ تستقصي نقطة نهاية النتيجة حتى تصبح الحالة TASK_STATUS_SUCCEED. هذا هو نفس النمط المكون من خطوتين المستخدم في جميع نقاط نهاية توليد الصور في Novita AI، بما في ذلك نقطة نهاية txt2img.

السعر هو 0.02 دولار لكل صورة. تحقق من السعر الحالي على صفحة تسعير Novita AI قبل بناء نموذج التكلفة.

الخطوة 3: إرسال طلب التحرير الأول الخاص بك

قم بإرسال POST إلى نقطة نهاية التحرير مع صورتك المصدر وتعليمات التحرير:

curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Change the background to a snowy mountain landscape",
    "image": "https://example.com/my-portrait.jpg"
  }'

يعيد استجابة ناجحة 200 ما يلي:

{
  "task_id": "abc123..."
}

احفظ task_id - ستحتاجه لاسترداد الصورة المحررة.

الخطوة 4: استقصاء النتيجة

قم بإجراء GET لنقطة نهاية نتيجة المهمة مع task_id كمعامل استعلام:

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

استمر في الاستقصاء حتى يصبح حقل task_status هو TASK_STATUS_SUCCEED:

{
  "task_status": "TASK_STATUS_SUCCEED",
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": "86400",
      "image_type": "JPEG"
    }
  ]
}

ينتهي صلاحية image_url بعد نافذة TTL (عادة 24 ساعة). قم بتنزيل النتيجة وتخزينها في مخزن الكائنات الخاص بك إذا كنت بحاجة إلى وصول طويل الأمد.

قيم الحالة التي يجب التعامل معها:

الحالة	المعنى
TASK_STATUS_QUEUED	الطلب في قائمة الانتظار؛ استمر في الاستقصاء
TASK_STATUS_PROCESSING	التحرير قيد التقدم؛ استمر في الاستقصاء
TASK_STATUS_SUCCEED	اكتمل؛ اقرأ الصورة المحررة من images[0].image_url
TASK_STATUS_FAILED	فشل التوليد؛ تحقق من حقل error لمعرفة السبب

الخطوة 5: التحقق من التسعير والحدود والأخطاء الشائعة

السعر: 0.02 دولار لكل صورة (تحقق من صفحة التسعير).

حدود المعدل: راجع مرجع API للحدود الحالية. إذا وصلت إلى 429، قلل معدل طلباتك وقم بتنفيذ التراجع الأسي على إعادة المحاولة.

أخطاء HTTP الشائعة:

رمز الحالة	السبب المحتمل
400	نص الطلب غير صحيح - prompt أو image مفقود، تنسيق صورة غير صالح، أو حجم إدخال غير مدعوم
401	مفتاح API مفقود أو غير صالح - تأكد من تنسيق Authorization: Bearer <key>
429	تجاوز حد المعدل - أضف منطق التراجع وإعادة المحاولة
500	خطأ من جانب الخادم - أعد المحاولة بعد تأخير قصير

إذا كانت حالة المهمة TASK_STATUS_FAILED، فإن الرد يتضمن عادة رسالة خطأ. تشمل الأسباب الشائعة تنسيقات الصور غير المدعومة، الصور التي تتجاوز حدود الحجم، أو الموجهات التي تؤدي إلى تفعيل مرشحات أمان المحتوى.

مثال بلغة Python

يقوم هذا البرنامج النصي بإرسال طلب تحرير، والاستقصاء حتى الاكتمال، وطباعة رابط صورة الإخراج:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai/v3/async"


def submit_edit(image: str, prompt: str, seed: int | None = None) -> str:
    payload: dict = {"prompt": prompt, "image": image}
    if seed is not None:
        payload["seed"] = seed
    response = requests.post(
        f"{BASE_URL}/qwen-image-edit",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
    )
    response.raise_for_status()
    return response.json()["task_id"]


def poll_result(task_id: str, interval: float = 2.0, timeout: float = 120.0) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/task-result",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
        )
        response.raise_for_status()
        data = response.json()
        status = data.get("task_status", "")
        if status == "TASK_STATUS_SUCCEED":
            return data
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Edit task failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    task_id = submit_edit(
        image="https://example.com/product-photo.jpg",
        prompt="Change the jacket to a red leather jacket, preserve the background",
    )
    print(f"Task ID: {task_id}")

    result = poll_result(task_id)
    for img in result["images"]:
        print(img["image_url"])

مثال باستخدام cURL

سير عمل من أمرين باستخدام jq لتحليل JSON:

#!/bin/bash
# الخطوة 1: إرسال طلب التحرير
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Convert to watercolor painting style, preserve the subject and composition",
    "image": "https://example.com/landscape.jpg"
  }' | jq -r '.task_id')

echo "Task ID: $TASK_ID"

# الخطوة 2: استقصاء حتى الاكتمال
while true; do
  RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.task_status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
    echo "$RESULT" | jq -r '.images[].image_url'
    break
  elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
    echo "Task failed:"
    echo "$RESULT" | jq .
    exit 1
  fi
  sleep 2
done

قم بتثبيت jq باستخدام apt install jq (Debian/Ubuntu) أو brew install jq (macOS) إذا لم يكن مثبتًا بالفعل.

المعلمات الرئيسية

المعامل	النوع	إلزامي	القيمة الافتراضية	الوصف
prompt	string	نعم	—	تعليمات بلغة طبيعية تصف التحرير المطلوب
image	string	نعم	—	الصورة المصدر كرابط أو سلسلة مشفرة بـ base64
seed	integer	لا	عشوائي	قيمة ثابتة لإنتاج مخرجات قابلة للتكرار عبر عمليات تشغيل متعددة
output_format	string	لا	jpeg	تنسيق الإخراج - راجع وثائق API للقيم المقبولة

كتابة موجهات فعالة: التحديد مهم. “Change the text on the billboard to ‘Summer Sale’” يعطي النموذج مهمة واضحة ومحدودة. “Improve the image” لا يفعل ذلك. عندما تريد تغيير عنصر واحد وترك الباقي كما هو، قم بتسمية ما تريد الحفاظ عليه: “change the jacket color to red, keep the background and face unchanged.” يساعد هذا مسار مشفر VAE في أداء مهمته المتمثلة في تثبيت المناطق غير المتأثرة.

استخدام seed للتكرار: عند ضبط الموجه، تثبيت البذور يسمح لك بمقارنة التعديلات مباشرة - يأتي الاختلاف في المخرجات من تغيير الموجه، وليس من أخذ العينات العشوائي. بمجرد العثور على موجه يعمل، قم بإزالة قيد البذور إذا كنت تريد تنوع المخرجات عبر تعديلات متعددة.

حالات الاستخدام النموذجية

استبدال الخلفية: “Replace the background with a minimalist white studio” - يحافظ Qwen Image Edit على حواف الموضوع والإضاءة أثناء تبديل البيئة. يعمل بشكل موثوق عندما يكون للموضوع حدود واضحة مقابل الخلفية الأصلية.

النص في الصور: استبدال لافتات المتاجر، عناوين الملصقات، أو ملصقات المنتجات بنص جديد - بما في ذلك الصينية والإنجليزية. يحافظ النموذج على نمط الخط والسياق البصري المحيط بشكل أفضل من أساليب التلوين التوليدي التي تميل إلى إعادة توليد المنطقة بأكملها.

تحويل النمط: “Convert to oil painting style” أو “make this look like a pencil sketch” مطبقة على صورة مصدر بدلاً من وصفها من الصفر. يحافظ مسار مشفر VAE على التكوين الأصلي وموضع الكائن بينما يدفع الموجه تحويل النمط.

تغييرات على مستوى الكائن: تبديل الملابس، تغيير ألوان عناصر محددة، إضافة أو إزالة الإكسسوارات. يجب أن يذكر الموجه العنصر المحدد الذي يتم تغييره لمنع التعديل من التأثير على المناطق المجاورة.

تحويل IP وتدوير الكائن: يدعم النموذج تغييرات تركيب العرض (مثل تدوير كائن لإظهار زاوية مختلفة) والتحويل بين الأنماط البصرية لصور الشخصيات أو المنتجات - حالات استخدام موثقة في نظرة عامة على Qwen-Image-Edit على Novita AI.

استكشاف الأخطاء وإصلاحها

المخرجات تبدو غير متغيرة: الموجه على الأرجح غير محدد بشكل كاف. اجعله أكثر وضوحًا بخصوص العنصر المستهدف: “Change the color of the car from blue to red” بدلاً من “make it red.”

انتشار التعديلات غير المرغوب فيها إلى مناطق غير مقصودة: للتعديلات المحلية المحددة للغاية، قم بتضمين لغة حفظ صريحة في موجهك: “only change X, leave Y intact.” الموجهات المفتوحة للغاية تعطي النموذج مجالًا لإعادة تفسير التكوين بالكامل.

تكتمل المهمة ولكن رابط الصورة يعيد 403 أو 404: يخبرك حقل image_url_ttl (بالثواني) بمدة صلاحية الرابط. إذا قمت بالاستقصاء عن الرابط بعد انتهاء TTL، يكون الرابط قد انتهت صلاحيته. قم بتنزيل الصورة فورًا بعد استقصاء ناجح.

401 غير مصرح: تحقق من أن تنسيق رأس Authorization هو بالضبط Bearer <key> مع مسافة بعد Bearer. تأكد من أن المفتاح نشط ولم يتم إبطاله في وحدة تحكم Novita AI.

انتهاء مهلة المهام باستمرار: يستغرق تحرير الصور وقتًا أطول من توليد النص - عادة 15–60 ثانية تحت الحمل العادي. إذا تجاوزت المهام بانتظام مهلة الوقت، قم بزيادة نافذة الاستقصاء قبل اعتبارها فشلًا.

الأسئلة الشائعة

هل تبقى الصورة المصدر على خوادم Novita؟

يتم تحميل صورتك إلى واجهة برمجة تطبيقات Novita AI عبر HTTPS ومعالجتها على بنيتها التحتية. راجع سياسات معالجة البيانات الخاصة بـ Novita AI قبل إرسال صور تحتوي على معلومات شخصية حساسة أو بيانات صحية خاصة أو محتوى سري.

هل يمكنني استخدام الصور المشفرة بـ base64 بدلاً من الرابط؟

نعم. قم بتمرير سلسلة base64 الخام في حقل image. استشر مرجع API لأي حدود حجم على حمولات base64.

هل يوجد معامل بذور للثبات؟

نعم - معامل seed الاختياري يثبت الحالة العشوائية بحيث ينتج نفس الموجه والصورة نتائج متسقة. مفيد للتكرار على صياغة الموجه دون ضوضاء المخرجات من إعادة أخذ العينات.

هل يمكنني استخدام نقطة النهاية هذه للمهام الدفعية؟

نعم. أرسل طلبات تحرير متعددة بالتوازي واجمع قيم task_id، ثم استقصها بشكل متزامن. كل طلب مستقل.

ما الفرق بين هذه ونقطة نهاية Qwen Image txt2img؟

تتطلب نقطة نهاية التحرير صورة مصدر وتنتج نسخة معدلة منها. نقطة نهاية txt2img تولد صورة بالكامل من موجه نصي - بدون صورة إدخال. استخدم نقطة نهاية التحرير عندما يكون لديك محتوى موجود تريد تعديله؛ استخدم txt2img عندما تقوم بالإنشاء من الصفر.

مقالات موصى بها

• بداية سريعة لـ Qwen Image Text-to-Image لتوليد الصور من الموجهات
• Qwen-Image-Edit على Novita AI: تحرير احترافي مقابل 0.02 دولار فقط
• Novita AI تقدم الآن Qwen-Image: نموذج نص-إلى-صورة متقدم بحجم 20 مليار