كيفية استخدام واجهة برمجة تطبيقات Qwen Image 3.0: التوليد، والتحرير، والتسعير

الملخص

يوحّد Qwen Image 3.0 بين توليد الصور من النص والتحرير المُوجَّه بالمرجع ضمن نسختي Standard (qwen-image-3.0) وPro (qwen-image-3.0-pro). ابدأ بموجه نصي، واختر حجم المخرجات، وقدّم طلب التوليد، ثم احفظ النتيجة فورًا. للتحرير، أرفق من صورة مرجعية واحدة إلى ثلاث، وأضف تعليمات صريحة عمّا يجب الحفاظ عليه. على CometAPI، تحقّق من المسار الفعلي ومخطط الطلب المتوافق قبل نشر الاستدعاءات النموذجية.

أهم النقاط

• يدعم Qwen Image 3.0 عبر واجهة API توليد الصور من النص والتحرير المُوجَّه بالمرجع من خلال نسختي Standard (qwen-image-3.0) وPro (qwen-image-3.0-pro)؛ صيغة الإخراج الأصلية هي PNG.
• تتوفر إمكانية الوصول إلى Qwen Image 3.0 API عبر CometAPI. يمكن للمطورين الحصول على مفتاح API، والتحقق من نقطة النهاية المدعومة، ودمج توليد الصور في تطبيقاتهم.
• تبدأ تسعيرة Qwen Image 3.0 API من $0.024/طلب على CometAPI، مقارنة بأسعار Alibaba Cloud في سنغافورة التي تبدأ من $0.030 لكل صورة مخرجة عبر Standard ومن $0.040 لكل صورة مخرجة 1K عبر Pro.
• يدعم تحرير الصور في Qwen Image 3.0 ما يصل إلى ثلاث صور مرجعية عبر واجهة Alibaba Cloud الأصلية، بينما يدعم التوليد من صورة واحدة إلى ست مخرجات لكل طلب.
• يتطلب تكامل Qwen Image 3.0 API من المطورين التحقق من المعلمات الخاصة بالمزوّد، وآلية المصادقة، ووحدات الفوترة، وعناوين الصور المؤقتة قبل نشر سير عمل الإنتاج.

ما هي Qwen Image 3.0 API؟

تحوّل Qwen Image 3.0 API التعليمات النصية إلى صور ويمكنها تحويل الصور الفوتوغرافية أو الأصول التصميمية المُقدَّمة. تشمل السيناريوهات المدعومة الملصقات متعددة اللغات، وتصوير التجارة الإلكترونية، ونماذج الحملات، واستبدال الخلفية، وتحرير الصور المركبة.

Qwen Image 3.0 Standard (qwen-image-3.0) هو الأساس المُركَّز على التكلفة لتوليد الصور من النص والتحرير المُوجَّه بالمرجع. انطلق به أولًا لسير العمل كثيف الحجم مثل تنويعات خلفيات التجارة الإلكترونية، ومسودات مرئية لوسائل التواصل الاجتماعي، واستكشاف أفكار الحملات. على سبيل المثال، استخدم Standard لإنتاج عدة خيارات لخلفية المنتج، ثم راجع دقة المنتج واختر الإصدارات الجديرة بالتنقيح.

Qwen Image 3.0 Pro (qwen-image-3.0-pro) يدعم التوليد والتحرير المُوجَّه بالمرجع، مع فئة إخراج أصلية بدقة 2K أعلى سعرًا. قيّمه للمخرجات الحساسة للجودة مثل صور البطل للحملات، والتكوينات التفصيلية للمنتجات، والملصقات الترويجية. على سبيل المثال، اختبر مفهومًا مُختارًا باستخدام Pro حينما تكون التفاصيل الدقيقة أو التخطيط مهمّين، وقارن النتائج المقبولة مع Standard قبل تخصيص ميزانية أكبر.

كيفية الاختيار: ابدأ بـStandard من أجل المسودات الحساسة للتكلفة والتنويعات. اختبر Pro على نفس الموجّه للأصول النهائية المتطلبة؛ اختره عندما يبرّر التحسن المقاس التكلفة الإضافية. لا تُغني أي تسمية عن اختبار خاص بالتطبيق يراعي الطباعة، ودقة المنتج، وعدد العناصر، أو دقة التخطيط.

ما المعلمات التي تدعمها Qwen Image 3.0 API؟

استخدم هذه المعلمات مع واجهة Alibaba Cloud الأصلية المتوافقة مع OpenAI. أضف الخيارات الخاصة بالمزوّد إلى طلبات CometAPI فقط عندما يوثّق المسار المحدد دعمها.

ينطبق على كلا النسختين: تدعم qwen-image-3.0 (Standard) وqwen-image-3.0-pro (Pro) نفس المعلمات المدرجة أدناه على واجهة Alibaba Cloud الأصلية المتوافقة مع OpenAI. اختر النسخة عبر model؛ أدوات التحكم في التوليد والتحرير مشتركة. لا يعني ذلك تماثل جودة المخرجات أو التسعير، ولا يضمن أن كل مسار في CometAPI يوفّر جميع المعلمات الأصلية.

للطلبات الأصلية، يجب أن يبقى نسب العرض إلى الارتفاع بين 1:8 و8:1. يجب ألا تتجاوز الصور المرجعية 10 MB، وأن يكون طول كل ضلع بين 1 و8,000 بكسل، ونسبة أطول ضلع إلى أقصر ضلع لا تزيد عن 10:1. استخدم data URI لإدخال Base64. يتطلب التفكير تفعيل prompt_extend=true؛ يدعم تعزيز agent التوليد من النص فقط.

يضع طلب الصورة المتوافق حقول التوليد في المستوى الأعلى من JSON ويُنسّق الأبعاد بصيغة 1024x1024. يستخدم DashScope الأصلي مُدخلات/معلمات متداخلة ويكتب الأبعاد غالبًا بصيغة 1024*1024. قد يفشل الطلب المنسوخ بين هاتين النقطتين دون تحويل.

كيف تستدعي Qwen Image 3.0 API عبر CometAPI؟

تفترض هذه الخطوات Python 3، و端 طرف متوافق مع Bash، وحساب CometAPI مع صلاحية الوصول إلى النموذج، ورصيدًا كافيًا. يستخدم الطلب الأول حقلي model وprompt فقط كما في مثال المزوّد. تم فحص الوثائق بتاريخ 16 أكتوبر 2026؛ لم تُنفَّذ هذه الأمثلة على حساب مدفوع.

إنشاء بيانات الاعتماد

أنشئ مفتاح API على جهة الخادم في لوحة تحكم CometAPI. لا تُضمنه أبدًا في عميل ويب أو جوال.

export COMETAPI_KEY="your_api_key"python -m pip install requests

إرسال طلب توليد مصغّر

يمكن للمطورين الوصول إلى Qwen Image 3.0 API في CometAPI باستخدام مسار توليد الصور الموثّق. ابدأ بالطلب الأدنى أدناه قبل إضافة المعلمات الاختيارية.

curl --fail-with-body https://api.cometapi.com/v1/images/generations \  -H "Authorization: Bearer $COMETAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"model":"qwen-image-3.0","prompt":"Premium skincare bottle on a stone pedestal, gentle studio lighting"}'

احفظ كل صورة مُعادة

احفظ السكربت التالي باسم generate.py وشغّل python generate.py. يرسل طلبًا، ويتعامل مع نتائج الصور بصيغة URL أو Base64، ويكتب كل صورة محليًا. إذا احتوت الاستجابة على معلومات مهمة بدلًا من مصفوفة data، سيتوقف بدل التخمين بشأن نقطة نهاية الاستطلاع؛ استخدم عقد المعالجة غير المتزامنة الخاص بحسابك لاسترداد النتيجة المكتملة.

import base64import osfrom pathlib import Pathimport requests​response = requests.post(    "https://api.cometapi.com/v1/images/generations",    headers={"Authorization": f"Bearer {os.environ['COMETAPI_KEY']}"},    json={"model": "qwen-image-3.0", "prompt": "A sunny bookstore cafe, editorial photograph"},    timeout=(15, 600),)response.raise_for_status()result = response.json()images = result.get("data")if not isinstance(images, list) or not images:    raise RuntimeError(f"No synchronous images; inspect task/error fields: {list(result)}")for index, item in enumerate(images, 1):    if item.get("url"):        download = requests.get(item["url"], timeout=(15, 120))        download.raise_for_status()        content = download.content    elif item.get("b64_json"):        content = base64.b64decode(item["b64_json"], validate=True)    else:        raise RuntimeError(f"Image {index} has no URL or Base64 payload")    path = Path(f"qwen_image_{index}.png")    path.write_bytes(content)    print(f"Saved {path}")

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

كيف تولّد صورًا متعددة باستخدام Qwen Image 3.0؟

على الواجهة الأصلية لـAlibaba Cloud، اضبط n بين اثنين وستة للحصول على تنويعات إبداعية. بالنسبة إلى CometAPI، فعِّل n فقط بعد تأكيد الدعم على مسارك المختار. تحقّق من كل أصل مُعاد بشكل منفصل؛ فزيادة n لا تضمن أن كل نتيجة ستمر عبر المراجعات اللاحقة.

يمكنك توليد ما يصل إلى 6 صور في طلب واحد مع Qwen Image 3.0 عبر ضبط معلمة n. يعمل ذلك مع كل من qwen-image-3.0 وqwen-image-3.0-pro، لكل من التوليد من النص وتحرير الصور. الافتراضي هو صورة واحدة فقط.

هناك طريقتان رئيسيتان: استخدام واجهة رسومية إذا كانت منصتك توفّر الخيار، أو استدعاء الـAPI مباشرة.

توليد صور متعددة باستخدام الـAPI

1. افتح وثائق الـAPI.
2. احصل على مفتاح API من QwenCloud console/ CometAPI.
3. اختر qwen-image-3.0 أو qwen-image-3.0-pro.
4. اضبط n على عدد الصور المطلوبة، من 1 إلى 6.
5. قدّم موجهك واحفظ الصور المُعادة.

على سبيل المثال، اضبط "n": 4 لطلب أربع تنويعات لموجه واحد.

مثال Python

إليك مثالًا جاهزًا للتعديل باستخدام الواجهة المتوافقة مع OpenAI.

from openai import OpenAIimport requestsclient = OpenAI(    api_key="YOUR_QWEN_API_KEY",    base_url="https://maas.qwencloudapi.com/compatible-mode/v1")
result = client.images.generate(    model="qwen-image-3.0-pro",    
prompt=(        "A cozy Japanese cafe on a rainy evening, "        "warm glowing lights, cinematic photography, "        "rich details, realistic reflections"    ),    
n=4,    
size="1024x1024")# Save each generated image
for i, item in enumerate(result.data, start=1):    response = requests.get(item.url)    response.raise_for_status()    with open(f"qwen_image_{i}.png", "wb") 
as f:        
f.write(response.content)print("Finished generating images!")

ثبّت الحزم المطلوبة أولًا:

pip install openai requests

تعيد الـAPI عنوان URL لكل نتيجة. عناوين URL للصور المُولَّدة مؤقتة، لذلك نزّل الصور بسرعة.

إعدادات مهمة

الحد الأقصى لعدد المخرجات هو ست لكل طلب. ضع في الاعتبار أن طلب المزيد من الصور يزيد تكلفة التوليد.

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

كيف تحرّر الصور باستخدام Qwen Image 3.0؟

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

يستخدم المثال التالي بيانات اعتماد Alibaba Cloud وحقل JSON الخاص بالصور للتحرير. أنشئ مفتاح Model Studio إقليميًا، واحصل على معرّف مساحة العمل، ووجّه إلى نقطة النهاية المطابقة. لا تستبدل مفتاح CometAPI بهذا الطلب.

export DASHSCOPE_API_KEY="your_model_studio_key"export ALIBABA_WORKSPACE_ID="your_workspace_id"export ALIBABA_IMAGE_ENDPOINT="https://${ALIBABA_WORKSPACE_ID}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations"

تأتي الصورة المرجعية أدناه مباشرة من المثال الرسمي للواجهة. إنها صورة إدخال، وليست نتيجة مُولَّدة من هذا المقال.

import os, requests
endpoint = os.environ["ALIBABA_IMAGE_ENDPOINT"]  
# documented regional .../images/generations endpoint
payload = {
"model": "qwen-image-3.0", 
"prompt": "Change the outfit to a charcoal business suit in a cafe. Preserve the face and hairstyle.", 
"image": ["https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"], 
"size": "1024x1024", 
"n": 1}
r = requests.post(endpoint, headers={
"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"}, json=payload, timeout=(15, 600))
r.raise_for_status()
print(r.json())

تستخدم نقطة النهاية الأصلية المتوافقة JSON على /images/generations، وليس تحميلات متعددة الأجزاء على /images/edits. لا تدعم الأقنعة أو البث. اقرأ مصفوفة data المعادة واحفظ كل عنوان URL باستخدام نفس حلقة التنزيل أعلاه.

لصورتين مرجعيتين، أدرج عنواني URL في مصفوفة image وحدد أدوارهما في الموجه (مثل المنتج من الصورة الأولى، ومشهد الغرفة من الصورة الثانية). لا تقبل سلسلة Qwen Image 3.0 أكثر من ثلاث صور مرجعية؛ استخدم نموذجًا مختلفًا أو سير معالجة مسبقة لمجموعات مصادر أكبر.

ما تكلفة Qwen Image 3.0 API؟

تختلف تسعيرة Qwen Image 3.0 API حسب نسخة النموذج، ودقة الإخراج، والمزوّد. يكمل الجدول أدناه مقارنة Alibaba Cloud في سنغافورة بأسعار CometAPI الواردة في جدول التسعير المُرفق من المراجع. تسرد المرفقات أسعار الإخراج بالدولار الأمريكي لكل صورة وخصم 20% لجميع التركيبات الأربع للنموذج/الدقة. لم يُعاد التحقق من هذه الأسعار بشكل مستقل مقابل فوترة حسابات حية؛ أكّد جدول الأسعار المعمول به قبل الاستخدام الإنتاجي.

**تغطي أمثلة الحجم أعلاه صور الإخراج فقط: تكلفة 100 صورة 1K عبر Standard هي $2.40 وتكلفة 100 صورة 1K عبر Pro هي $3.20؛ تكلفة 1,000 صورة 2K عبر Standard هي $24.00 وتكلفة 1,000 صورة 2K عبر Pro هي $60.00. للتحرير، أضف $0.0024 لكل صورة مرجعية قابلة للفوترة. لا تشمل قواعد المهام الفاشلة والضرائب والتعديلات الخاصة بالحساب.*

باستخدام أسعار الإدخال والإخراج المُرفقة، قدّر رسوم الصور لأي مزوّد كما يلي:

إجمالي التكلفة = (عدد الصور المرجعية القابلة للفوترة × سعر صورة الإدخال) + (عدد المخرجات الناجحة × سعر صورة الإخراج).

بالنسبة لمهمة تُفوَّت لصورتين مرجعيتين مُدخلتين وثلاث صور إخراج 1K عبر Standard، تكون رسوم الصور لدى Alibaba Cloud هي (2 × $0.0030) + (3 × $0.0300) = $0.0960. أما رسوم الصور المقابلة على CometAPI فهي (2 × $0.0024) + (3 × $0.0240) = $0.0768، استنادًا إلى الأسعار المُرفقة.

يتقاضى CometAPI مبلغ $0.0024 لكل صورة مرجعية مُدخلة لكلتا النسختين. أسعار الإخراج هي $0.0240 لكل صورة Standard عند 1K أو 2K، و$0.0320 لكل صورة Pro عند 1K، و$0.0600 لكل صورة Pro عند 2K. يسرد الجدول المُرفق كل سعر إدخال وإخراج أقل بنسبة 20% من السعر الرسمي المقابل. وبذلك تكون رسوم الصور أقل بنسبة 20% لنفس أعداد الصور القابلة للفوترة؛ قد تغيّر الرسوم الإضافية أو شروط الحساب الفاتورة النهائية.

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

كيف تتعامل مع أخطاء Qwen Image 3.0 API؟

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

هل ينبغي إعادة محاولة طلب Qwen Image 3.0 بعد انتهاء المهلة؟

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

كيف يمكنني استخدام صور مرجعية محلية مع Qwen Image 3.0؟

بالنسبة للواجهة الأصلية المتوافقة، اقرأ الملف كبايتات، ورمّزه Base64، وأضف بادئة data URI مثل data:image/png;base64,. ضع تلك السلسلة الكاملة في image. يجب أن يستوفي إدخال Base64 حدود حجم وأبعاد الصورة؛ مسار نظام الملفات المحلي ليس عنوان URL يمكن للخدمة جلبه.

كيف أمرّر خيارات خاصة بـQwen عبر OpenAI SDK؟

احتفظ بالحقول القياسية للصور في معاملات SDK المعتادة وضع حقول Model Studio الإضافية، مثل image وprompt_extend، داخل extra_body. تضع طلبات HTTP الخام هذه الحقول مباشرة في المستوى الأعلى من JSON. تنطبق هذه الإرشادات على الواجهة الأصلية المتوافقة؛ تحقّق من المسار المحدد على CometAPI قبل تمرير الخيارات الخاصة بالمزوّد.

ماذا أفعل عندما يُرجع Qwen Image 3.0 عدد صور أقل مما طُلب؟

احفظ المخرجات الناجحة أولًا وسجّل العدد الفعلي. بالنسبة لفوترة Alibaba Cloud الأصلية، تتبع رسوم الإخراج الصور المُولَّدة بنجاح. إذا كانت هناك حاجة إلى أصول إضافية، فاطلب فقط الكمية الناقصة بعد مراجعة الاستجابة وسجل الاستخدام؛ يجب تسوية فوترة CometAPI وفق شروط الحساب الخاصة بها.

الخلاصة

يُعد Qwen Image 3.0 خيارًا عمليًا للفرق التي تحتاج إلى التوليد والتحرير الموجّه بالمرجع ضمن عائلة نموذج واحدة. استخدم Standard كأساس مُركّز على التكلفة، واختبر Pro للمهام الإبداعية أو بدقة 2K الأكثر تطلبًا، وقِس تكلفة المخرجات المقبولة بدل الحكم بسعر كل طلب. ابدأ باستدعاء التوليد الأدنى، واحفظ مخرجاته، ثم أضف التحرير أو تعدد المخرجات عبر عقد المزوّد المناسب. حافظ على فصل بيانات الاعتماد ومخططات الطلبات، وتعامل مع الأخطاء بوضوح، وساوِ استخدام الصور مع جدول الأسعار المختار.