بدء استخدام Qwen Image لتوليد الصور من النصوص

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

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

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

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

نموذج Qwen Image قوي بشكل خاص في توليد الصور التي تحتوي على نصوص مقروءة ومصممة ضمن المخرجات – فكر في الملصقات، اللافتات، نماذج المنتجات، والرسومات على الأغلفة. إذا كانت حالة الاستخدام تتعلق بتحرير صورة موجودة بدلاً من التوليد من الصفر، راجع واجهة برمجة تطبيقات تحرير الصور Qwen Image بدلاً من ذلك. إذا كنت تريد نظرة عامة كاملة حول قدرات نموذج 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. تحقق من السعر الحالي على صفحة تسعير 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 في نقطة النهاية هذه – يقوم النموذج بمعالجة تلك القرارات داخلياً. ركز طلبك على ما يجب أن تحتويه الصورة وأسلوبها البصري.

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

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

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

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

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

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

الأخطاء الشائعة وإصلاحاتها

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

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

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

انتهاء صلاحية رابط الصورة (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؟

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

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

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

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

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

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

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

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

• Qwen-Image على Novita AI: عرض نصوص فائق مع نموذج 20B
• Qwen-Image-Edit على Novita AI: تحرير بجودة احترافية مقابل 0.02 دولار فقط
• FLUX.1 Kontext Pro vs Max vs Dev على Novita AI