بدء الاستخدام السريع لـ Qwen Image Text-to-Image لتوليد الصور من النصوص

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

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

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

• توليد الصور من النصوص مع عرض نص عالي الجودة باللغة الإنجليزية أو الصينية عبر POST /v3/async/qwen-image-txt2img.
• بناء خطوط إنتاج تنشئ ملصقات أو رسومات أو محتوى مصورًا حيث تكون readability النص داخل الصورة مهمة.
• النمذجة الأولية بسرعة مقابل واجهة برمجة تطبيقات مستضافة بدلاً من تشغيل نموذج 20B على بنية GPU محلية.

نموذج Qwen Image قوي بشكل خاص في توليد الصور بنص قابل للقراءة ومصمم مضمن في المخرجات — فكر في الملصقات واللافتات ونماذج المنتجات والرسومات التوضيحية للغلاف. إذا كانت حالتك تتضمن تحرير صورة موجودة بدلاً من التوليد من الصفر، فراجع Qwen Image Edit API بدلاً من ذلك. إذا كنت تريد نظرة عامة كاملة على إمكانيات نموذج Qwen Image ومعايير الأداء، فإن منشور Novita AI حول Qwen Image يغطي الهندسة ونتائج المعايير بالتفصيل.

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

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

export NOVITA_API_KEY="your_api_key_here"

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

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

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

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

السعر هو 0.02 دولار لكل صورة، بما يتوافق مع نقطة نهاية Qwen Image Edit. تحقق من السعر الحالي على صفحة تسعير Novita AI قبل بناء تقدير للتكلفة.

الخطوة 3: إرسال طلبك الأول

أرسل طلب POST إلى نقطة نهاية التوليد مع prompt وحجم اختياري size:

curl -s -X POST https://api.novita.ai/v3/async/qwen-image-txt2img \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic mountain landscape at sunrise, warm golden light, ultra-detailed, 8K",
    "size": "1024*1024"
  }'

الاستجابة الناجحة 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"

تتضمن الاستجابة حقل status. استمر في الاستقصاء حتى تصبح الحالة TASK_STATUS_SUCCEED:

{
  "task": {
    "task_id": "abc123...",
    "status": "TASK_STATUS_SUCCEED"
  },
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": "3600",
      "image_type": "png"
    }
  ]
}

image_url هو رابط محدود المدة — قيمة image_url_ttl (بالثواني) تخبرك بالمدة التي يظل فيها صالحًا. قم بتنزيل الصورة على الفور أو قم بتوجيهها عبر التخزين الخاص بك إذا كنت بحاجة إلى وصول طويل الأمد.

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

الحالة	المعنى
TASK_STATUS_QUEUED	الطلب في قائمة الانتظار، لم يبدأ بعد
TASK_STATUS_PROCESSING	التوليد قيد التقدم
TASK_STATUS_SUCCEED	الصورة جاهزة؛ اقرأ images[0].image_url
TASK_STATUS_FAILED	فشل التوليد؛ تحقق من task.reason

مثال Python: من البداية إلى النهاية

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

import os
import time
import requests

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


def generate_image(prompt: str, size: str = "1024*1024") -> str:
    response = requests.post(
        f"{BASE_URL}/v3/async/qwen-image-txt2img",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"prompt": prompt, "size": size},
    )
    response.raise_for_status()
    return response.json()["task_id"]


def poll_result(task_id: str, interval: float = 2.0, max_attempts: int = 60) -> str:
    for _ in range(max_attempts):
        response = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
        )
        response.raise_for_status()
        data = response.json()
        status = data["task"]["status"]

        if status == "TASK_STATUS_SUCCEED":
            return data["images"][0]["image_url"]
        elif status == "TASK_STATUS_FAILED":
            reason = data["task"].get("reason", "unknown")
            raise RuntimeError(f"Generation failed: {reason}")

        time.sleep(interval)

    raise TimeoutError(f"Task {task_id} did not complete after {max_attempts} polls")


if __name__ == "__main__":
    prompt = (
        "A poster reading 'Welcome to Novita AI' in bold neon letters "
        "against a dark city skyline at night, cinematic lighting"
    )
    task_id = generate_image(prompt, size="1024*1024")
    print(f"Task ID: {task_id}")

    image_url = poll_result(task_id)
    print(f"Image URL: {image_url}")

مثال cURL

نمط من أمرين لسير العمل الكامل:

# Step 1: Submit generation request
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/qwen-image-txt2img \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene Japanese garden with cherry blossoms, koi pond, morning mist, watercolor style",
    "size": "1024*1536"
  }' | python3 -c "import sys,json; print(json.load(sys.stdin)['task_id'])")

echo "Task ID: $TASK_ID"

# Step 2: Poll until complete
while true; do
  STATUS=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATE=$(echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['task']['status'])")
  echo "Status: $STATE"
  if [ "$STATE" = "TASK_STATUS_SUCCEED" ]; then
    echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['images'][0]['image_url'])"
    break
  elif [ "$STATE" = "TASK_STATUS_FAILED" ]; then
    echo "Generation failed"
    break
  fi
  sleep 2
done

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

المعامل	النوع	مطلوب	الافتراضي	ملاحظات
prompt	string	نعم	—	وصف نصي للصورة المراد توليدها. يدعم الإنجليزية والصينية.
size	string	لا	1024*1024	العرض × الارتفاع بالبكسل، بتنسيق W*H. كل بُعد: 256–1536.

خيارات الحجم التي يجب مراعاتها:

حالة الاستخدام	الحجم الموصى به
مربع (اجتماعي، ملف شخصي)	1024*1024
عمودي (جوال، ملصق)	1024*1536
أفقي (لافتة، صورة مصغرة)	1536*1024

لا يوجد معامل منفصل negative_prompt أو steps أو cfg_scale في نقطة النهاية هذه — النموذج يتعامل مع تلك القرارات داخليًا. ركز في prompt الخاص بك على ما يجب أن تحتويه الصورة وأسلوبها البصري.

ما يولده Qwen Image بشكل جيد

تعطي بنية 20B MMDiT لـ Qwen Image ميزة حقيقية في بعض المجالات المحددة:

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

الاتساق الدلالي. عندما يصف prompt مشهدًا بعناصر متعددة وعلاقات مكانية محددة، يميل Qwen Image إلى احترام نية التخطيط بشكل أكثر موثوقية من البنى الأصغر أو الأقدم.

اتباع التعليمات على نطاق واسع. النصوص الطويلة والمفصلة التي تصف سمات متعددة — المشهد، الإضاءة، الأسلوب، لوحة الألوان، كائنات محددة — تنتج مخرجات تعكس الـ prompt بالكامل بدلاً من التعلق بكلمة مفتاحية واحدة.

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

الأخطاء الشائعة والحلول

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

400 Bad Request على size: يجب أن يستخدم معامل size * كفاصل (على سبيل المثال، 1024*1024)، وليس x أو × أو مصفوفة JSON. يجب أن يكون كل بُعد بين 256 و 1536.

TASK_STATUS_FAILED بدون سبب: يحدث هذا عادةً بسبب prompt يؤدي إلى تشغيل تصفية المحتوى. بسط الـ prompt وحاول مرة أخرى. تجنب النصوص التي تحتوي على عنف صريح أو محتوى جنسي أو محتوى قد يطابق مرشحات الأمان.

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

الاستقصاء البطيء: يختلف وقت التوليد حسب حمل الخادم. البدء بالاستقصاء على فترات 2 ثانية معقول. إذا كانت المهمة لا تزال TASK_STATUS_QUEUED بعد 10 ثوانٍ، استمر في الاستقصاء — يمكن أن يزداد عمق قائمة الانتظار خلال أوقات الذروة.

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

هل هناك نقطة نهاية متوافقة مع OpenAI لـ Qwen Image txt2img؟

لا. تستخدم نقطة النهاية /v3/async/qwen-image-txt2img واجهة الصور غير المتزامنة الأصلية لـ Novita AI، وليس تنسيق توليد الصور في OpenAI. إذا كنت بحاجة إلى توليد صور متوافق مع OpenAI، تقدم Novita AI نماذج FLUX و SDXL من خلال نقاط نهاية متوافقة — راجع وثائق Novita AI.

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

تولد نقطة النهاية هذه الصور من prompt نصي فقط — لا حاجة لصورة إدخال. تأخذ نقطة نهاية Qwen Image Edit صورة موجودة بالإضافة إلى تعليمات نصية وتعدل الصورة وفقًا لذلك. استخدم txt2img عندما تقوم بالتوليد من الصفر؛ استخدم edit عندما تحتاج إلى تغيير شيء في صورة موجودة.

هل يدعم النموذج نسب أبعاد غير المربع؟

نعم. استخدم معامل size لتعيين العرض والارتفاع بشكل مستقل في أي مكان من 256 إلى 1536 بكسل لكل بُعد. النسب الطويلة (على سبيل المثال، 1024*1536) تعمل بشكل جيد للمحتوى العمودي؛ النسب العريضة (على سبيل المثال، 1536*1024) مناسبة للافتات والصور المصغرة.

كيف أحصل على نتائج متسقة عبر عدة عمليات توليد؟

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

هل يمكنني استخدام هذه API في وظيفة دفعية؟

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

مقالات مقترحة

• Qwen-Image على Novita AI: عرض نص فائق مع نموذج 20B
• Qwen-Image-Edit على Novita AI: تحرير بجودة احترافية مقابل 0.02 دولار فقط
• بدء الاستخدام السريع لـ Z-Image Turbo API