كيفية استخدام Qwen Image 3 Pro API عبر DashScope: دليل للمطورين

qwen-image-3.0-pro من Alibaba هو النموذج الرائد لتوليد الصور الذي يتم تقديمه عبر Model Studio، المعروف أيضًا باسم DashScope أو Bailian. يستهدف هذا النموذج مطوري الواجهة الخلفية الذين يحتاجون إلى نقطة نهاية موثوقة لتحويل النص إلى صورة بأسعار يمكن التنبؤ بها. معرف النموذج الرسمي qwen-image-3.0-pro موثق في كتالوج Model Studio من Alibaba (وثائق Alibaba Cloud Model Studio، 2026)، ويمكنك استدعاؤه من أي عميل HTTP.

يشرح هذا الدليل التكامل الكامل. بحلول النهاية، سيكون لديك مفتاح API، استدعاء cURL فعال، مقتطف Python، ونظرة واضحة على هيكل التكلفة لكل صورة.

النقاط الرئيسية

معرف النموذج: qwen-image-3.0-pro، يتم تقديمه على Alibaba Cloud Model Studio / DashScope على https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud، 2026).

المصادقة: قم بتعيين DASHSCOPE_API_KEY كمتغير بيئة، ثم أرسله كرمز Bearer (Promptfoo، 2026).

السعر المرجعي: يكلف النموذج السابق qwen-image-2.0-pro 0.075 دولارًا لكل صورة تم إنشاؤها وفقًا للتسعير الرسمي لـ Alibaba (تسعير Alibaba Cloud، 2026).

لكل نموذج صور حصة مجانية للاختبار قبل أن تدفع سنتًا واحدًا (الأسئلة الشائعة حول Alibaba Image API، 2026).

المتطلبات الأساسية

قبل كتابة أي رمز، تأكد من أن لديك حساب Alibaba Cloud مع إمكانية الوصول إلى Model Studio. يذكر الدليل الرسمي "أول استدعاء API لـ Qwen" ثلاثة أشياء يحتاجها كل مطور: مفتاح API تم إنشاؤه في وحدة تحكم Model Studio، ومعرف مساحة عمل مرتبط بمشروعك، والوصول إلى نقطة نهاية DashScope HTTP (Alibaba Cloud، 2026).

تحتاج أيضًا إلى أدوات أساسية. تغطي محطة طرفية مع cURL، و Python 3.9 أو أحدث، ومكتبة requests كل شيء في هذا الدليل. لا يلزم وجود SDK خاص. إذا كنت قد استدعيت OpenAI API من نص برمجي من قبل، فسيبدو نمط DashScope مألوفًا، حيث يستخدم كلاهما رموز Bearer ونصوص طلب JSON.

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

الخطوة 1: احصل على مفتاح API ومعرف مساحة العمل الخاص بك

مفتاح API هو الاعتماد الذي يصرح بكل استدعاء تقوم به إلى qwen-image-3.0-pro. يوجه دليل البدء من Alibaba المطورين إلى إنشاء المفتاح داخل وحدة تحكم Model Studio ثم نسخ معرف مساحة العمل من نفس لوحة التحكم (Alibaba Cloud، 2026). تعامل مع كلتا القيمتين كأسرار.

لاستردادها:

سجل الدخول إلى وحدة تحكم Model Studio في بوابة Alibaba Cloud.
افتح قسم API Keys وانقر على Create API Key.
انسخ المفتاح الذي تم إنشاؤه فورًا. تخفي وحدة التحكم القيمة الكاملة بعد الإنشاء.
لاحظ Workspace ID المعروض في الجزء العلوي من لوحة التحكم.

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

ملخص الاقتباس: يوجه دليل Alibaba الرسمي "أول استدعاء API لـ Qwen" المطورين إلى إنشاء مفتاح API في وحدة تحكم Model Studio، ونسخ معرف مساحة العمل من نفس لوحة التحكم، واستدعاء النماذج عبر نقطة نهاية DashScope على https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud، 2026).

الخطوة 2: تعيين متغير البيئة DASHSCOPE_API_KEY

يؤدي تحميل المفتاح في متغير بيئة إلى إبقائه خارج التعليمات البرمجية الخاصة بك وخارج التحكم في الإصدار. النمط المجتمعي الموثق بواسطة Promptfoo هو تعيين متغير يسمى DASHSCOPE_API_KEY قبل تشغيل النص البرمجي الخاص بك، والذي يتم قراءته بعد ذلك بواسطة عميل HTTP في وقت الطلب (Promptfoo، 2026).

على macOS و Linux:

export DASHSCOPE_API_KEY="sk-your-key-here"

على Windows PowerShell:

$env:DASHSCOPE_API_KEY = "sk-your-key-here"

لإعداد دائم، أضف سطر التصدير إلى ~/.zshrc أو ~/.bashrc أو متغيرات بيئة مستخدم Windows. أعد تشغيل المحطة الطرفية بعد ذلك. تحقق من تحميل المتغير قبل المتابعة:

echo $DASHSCOPE_API_KEY

الإعداد الشائع هو ملف .env بالإضافة إلى محمل مثل python-dotenv، بحيث يعمل نفس التكوين عبر التطوير المحلي، CI، وعمليات نشر الحاويات. تذكر إضافة .env إلى .gitignore حتى لا يتم الالتزام بالمفتاح أبدًا.

الخطوة 3: قم بإجراء أول استدعاء لتوليد الصور باستخدام cURL

نقطة نهاية DashScope على https://dashscope-us.aliyuncs.com/api/v1 هي نقطة الدخول لكل نموذج Qwen، بما في ذلك qwen-image-3.0-pro (Alibaba Cloud، 2026). تستخدم الاستدعاءات رمز Bearer في رأس Authorization ونص JSON يسمي النموذج بالإضافة إلى طلبك.

فيما يلي طلب cURL توضيحي يعتمد على نقطة النهاية الموثقة ونمط المصادقة. تتبع أسماء الحقول ومسارات الطلب الدقيقة اتفاقية DashScope، ولكن يجب عليك تأكيد المخطط الحالي مقابل مرجع API الرسمي على Qwen API عبر DashScope قبل الشحن إلى الإنتاج.

# مثال توضيحي. تأكيد أسماء الحقول والمسارات الدقيقة مقابل:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
curl -X POST "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "input": {
      "prompt": "مقهى مكتبة مريح في الخريف، إضاءة دافئة، تفاصيل عالية"
    },
    "parameters": {
      "size": "1024*1024",
      "n": 1
    }
  }'

بعض الملاحظات العملية:

بعض نقاط نهاية صور DashScope غير متزامنة، مما يعني أن الاستجابة الأولى تُرجع معرف مهمة، وتقوم باستطلاع عنوان URL ثانٍ لجلب الصورة النهائية. تحقق من مرجع API للسلوك الدقيق لـ qwen-image-3.0-pro.
حافظ على الطلبات ضمن حد الرمز الموثق. يمكن أن يتم اقتطاع الطلبات الطويلة بصمت.
استخدم معلمة size المطابقة لأحد نسب العرض إلى الارتفاع المدعومة، وإلا فقد يعود الاستدعاء إلى قيمة افتراضية.

ملخص الاقتباس: نقطة نهاية DashScope الرسمية على https://dashscope-us.aliyuncs.com/api/v1 تخدم qwen-image-3.0-pro، مع مرجع كامل لمعلمات الإدخال والإخراج موثق بواسطة Alibaba Cloud (Alibaba Cloud، 2026).

الخطوة 4: تحليل الاستجابة في Python

Python هي اللغة الأكثر شيوعًا لتغليف واجهات برمجة تطبيقات الصور لأن مكتبة requests تجعل تحليل JSON أمرًا سهلاً. بمجرد عودة الاستدعاء، تقوم باستخراج عنوان URL للصورة التي تم إنشاؤها، وتنزيلها، وحفظها على القرص أو في تخزين الكائنات.

فيما يلي نص برمجي توضيحي قصير. كما هو الحال مع cURL، تأكد من أسماء حقول الاستجابة مقابل مرجع API الرسمي قبل الاعتماد عليها.

# مثال توضيحي. تأكيد مخطط الاستجابة مقابل:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
ENDPOINT = "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "qwen-image-3.0-pro",
    "input": {
        "prompt": "مقهى مكتبة مريح في الخريف، إضاءة دافئة، تفاصيل عالية"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}

response = requests.post(ENDPOINT, headers=headers, json=payload)
response.raise_for_status()
data = response.json()

# أسماء الحقول أدناه توضيحية. تحقق منها مقابل مرجع API الرسمي.
image_url = data["output"]["results"][0]["url"]
print("عنوان URL للصورة التي تم إنشاؤها:", image_url)

# تنزيل الملف
img = requests.get(image_url)
with open("output.png", "wb") as f:
    f.write(img.content)

بعض النصائح على مستوى الإنتاج:

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

يساعد إضافة طبقة تجريد رفيعة بين عميل API ومنطق العمل. بهذه الطريقة، فإن تبديل النماذج لاحقًا (على سبيل المثال إلى نقطة نهاية تحرير أو إصدار Qwen أحدث) يغير وحدة واحدة فقط.

كم يكلف Qwen Image 3 Pro؟

التسعير لكل صورة تم إنشاؤها، وتفوتر Alibaba فقط التوليدات الناجحة. تسرد صفحة التسعير الرسمية qwen-image-2.0-pro بسعر 0.075 دولارًا لكل صورة (تسعير Alibaba Cloud، 2026). يقدم موفرو الطرف الثالث نماذج صور Qwen بأسعار مختلفة: يسرد Fal نموذج صور Qwen بحوالي 0.021 دولارًا لكل صورة، ويفرض Replicate حوالي 0.030 دولارًا لكل صورة بدقة 1024x1024 (تفاصيل تسعير Puter، 2026؛ pricepertoken، 2026).

بالنسبة لـ qwen-image-3.0-pro على وجه التحديد، تعامل مع سعر 2.0-pro كأقرب مرجع رسمي، ثم تحقق من الرقم الحالي في صفحة تسعير Model Studio قبل وضع الميزانية.

ملخص الاقتباس: تسعر Model Studio من Alibaba qwen-image-2.0-pro بسعر 0.075 دولارًا لكل صورة تم إنشاؤها، وتفوتر فقط التوليدات الناجحة، بينما يسرد موفرو الطرف الثالث مثل Fal و Replicate نماذج صور Qwen بحوالي 0.021 دولارًا و 0.030 دولارًا لكل صورة على التوالي (Alibaba Cloud، 2026؛ Puter، 2026).

قد تبدو الميزانية الشهرية التقريبية لتطبيق صغير كما يلي:

الحجم (صور / شهر)	التكلفة بسعر 0.075 دولار (Alibaba)	التكلفة بسعر 0.021 دولار (Fal)
1,000	75 دولارًا	21 دولارًا
10,000	750 دولارًا	210 دولارًا
100,000	7,500 دولار	2,100 دولار

الأسعار اعتبارًا من يوليو 2026.

الحصة المجانية والقيود

يأتي كل نموذج صور على Model Studio بحصة مجانية، حتى تتمكن من الاختبار قبل الالتزام بالإنفاق (الأسئلة الشائعة حول Alibaba Image API، 2026). يتم إعادة تعيين الحصة وفقًا لجدول زمني موثق في الأسئلة الشائعة.

بعض المؤشرات العملية:

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

ما وراء تحويل النص إلى صورة: واجهة برمجة تطبيقات التحرير

تتضمن عائلة Qwen أيضًا نقطة نهاية مخصصة لتحرير الصور. تدعم إدخال وإخراج صور متعددة، وتحرير النص داخل الصورة، وإضافة الكائنات وإزالتها وتحريكها، وتغييرات الوضعية (Qwen-Image Edit API، 2026).

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

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

ما هو معرف النموذج لـ Qwen Image 3 Pro؟

معرف النموذج الرسمي هو qwen-image-3.0-pro، يتم تقديمه على Alibaba Cloud Model Studio / DashScope على https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud، 2026). استخدم هذه السلسلة الدقيقة في حقل model في نص طلبك.

كيف أقوم بمصادقة استدعاءات DashScope API؟

قم بتعيين متغير البيئة DASHSCOPE_API_KEY، ثم أرسله كرمز Bearer في رأس Authorization لكل طلب (Promptfoo، 2026). لا تقم أبدًا بتضمين المفتاح في ملفات المصدر أو الالتزام به في التحكم في الإصدار.

كم يكلف Qwen Image 3 Pro لكل صورة؟

تسعر Alibaba النموذج السابق qwen-image-2.0-pro بسعر 0.075 دولارًا لكل صورة وتفوتر فقط التوليدات الناجحة (تسعير Alibaba Cloud، 2026). يسرد موفرو الطرف الثالث مثل Fal و Replicate نماذج صور Qwen بحوالي 0.021 دولارًا و 0.030 دولارًا لكل صورة. تحقق من تسعير 3.0-pro الحالي في الصفحة الرسمية.

هل هناك حصة مجانية؟

نعم. لكل نموذج صور على Model Studio حصة مجانية يمكنك استخدامها للاختبار قبل بدء الفوترة المدفوعة (الأسئلة الشائعة حول Alibaba Image API، 2026). تحقق من الأسئلة الشائعة لمعرفة وتيرة إعادة التعيين والقيود، والتي تختلف حسب النموذج.

هل يدعم Qwen Image 3 Pro تحرير الصور؟

يتم التعامل مع التحرير بواسطة نقطة نهاية منفصلة تسمى Qwen-Image Edit، والتي تدعم إدخال وإخراج صور متعددة، وتحرير النص داخل الصور، وإضافة الكائنات وإزالتها وتحريكها، وتغييرات الوضعية (Qwen-Image Edit API، 2026). تختلف واجهات برمجة تطبيقات تحويل النص إلى صورة والتحرير في شكل الطلب.

الخلاصة

لديك الآن المسار الكامل لأول استدعاء لـ qwen-image-3.0-pro: مفتاح API من وحدة تحكم Model Studio، ومتغير البيئة DASHSCOPE_API_KEY محملًا، وطلب cURL فعال، ومقتطف Python يقوم بتحليل وتنزيل النتيجة. نموذج التسعير لكل صورة، بدءًا من 0.075 دولارًا على تسعير Alibaba الرسمي، يجعل التكلفة قابلة للتنبؤ مع التوسع.

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

ابنِ صغيرًا، راقب حصتك، واشحن.

كيفية استخدام Qwen Image 3 Pro API عبر DashScope: دليل للمطورين