أصبحت واجهة Qwen4-Max API متاحة الآن على QwenCloud بنموذج الدفع حسب عدد الرموز (tokens) وبالمعرّف qwen4-max. أنشئ مفتاح API بنظام الدفع حسب الاستخدام في منطقتك، ووجّه مكتبة OpenAI SDK إلى العنوان https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 (سنغافورة)، ثم ابدأ الاستدعاء. تبلغ التكلفة 1.50 دولار لكل مليون رمز إدخال و4.50 دولار لكل مليون رمز إخراج، مع نافذة سياق تصل إلى مليون رمز.
يغطي هذا الدليل مفتاح API، وعناوين URL الأساسية، ووضع التفكير، والرؤية (vision)، والأدوات، والمخرجات المهيكلة، والتخزين المؤقت، ومسار Anthropic، والحدود والأخطاء. كل الأمثلة البرمجية مأخوذة من وثائق QwenCloud كما وردت بتاريخ 16 نوفمبر 2026.
للاطلاع على الخلفية، اقرأ ما هو Qwen4-Max. وللحصول على الوصول عبر الاشتراك بدلًا من الدفع حسب الرموز، راجع جميع طرق استخدام Qwen4-Max ودليل خطة الرموز (Token Plan).
ماذا توفر لك واجهة Qwen4-Max API
تقدم واجهة Qwen4-Max API نموذج Alibaba الرائد عبر QwenCloud مع نقاط نهاية متوافقة مع OpenAI وAnthropic وDashScope. تقبل النموذج نصوصًا وصورًا وفيديوهات كمدخلات، وتعيد نصوصًا، وتفكر قبل الإجابة افتراضيًا، وتدعم استدعاء الدوال (function calling)، والمخرجات المهيكلة، والتخزين المؤقت للسياق، والمعالجة الدفعية (batch jobs)، والبحث في الويب، والضبط الدقيق (fine-tuning).

وفيما يلي الأرقام من صفحة النموذج qwen4-max:
| البند | القيمة |
|---|---|
| معرّف النموذج | qwen4-max |
| سعر الإدخال | 1.50 دولار لكل مليون رمز |
| سعر الإخراج | 4.50 دولار لكل مليون رمز |
| إدخال الذاكرة المؤقتة الضمنية / قراءة الذاكرة المؤقتة الصريحة | 0.075 دولار لكل مليون رمز |
| إنشاء الذاكرة المؤقتة الصريحة | 1.875 دولار (5 دقائق) أو 3 دولارات (ساعة واحدة) لكل مليون رمز |
| نافذة السياق | مليون رمز |
| الحد الأقصى للإدخال | 991 ألف رمز (983 ألفًا مع التفكير) |
| الحد الأقصى للإخراج | 393 ألف رمز |
| الحد الأقصى للاستدلال | 262 ألف رمز |
| معدل النقل | 5,000,000 رمز في الدقيقة (TPM) |
تُحتسب رموز التفكير ضمن رموز الإخراج. للحصول على تفصيل كامل للتكاليف، راجع دليل أسعار Qwen4-Max.
احصل على مفتاح واختر عنوان URL الأساسي المناسب
المفاتيح مرتبطة بمنطقة معينة، ويجب أن يتطابق نوع المفتاح مع نقطة النهاية.
- افتح لوحة تحكم QwenCloud واختر المنطقة من محدد أعلى يمين الشاشة.
- انتقل إلى API Keys، وانقر على Create API key، وأضف وصفًا ثم انقر على Generate Key.
- انسخ المفتاح فورًا؛ إذ يُعرض مرة واحدة فقط. تبدأ المفاتيح الجديدة بنظام الدفع حسب الاستخدام بالبادئة
sk-ws-. - صدّره كمتغير بيئة:
export DASHSCOPE_API_KEY="sk-ws-...".
تستخدم كل منطقة النطاق {region}.maas.qwencloudapi.com. سنغافورة هي ap-southeast-1، وفرانكفورت هي eu-central-1، وطوكيو هي ap-northeast-1، والولايات المتحدة (فرجينيا) هي us-east-1. ثم أضف مسار البروتوكول:
| البروتوكول | عنوان URL الأساسي (سنغافورة) |
|---|---|
| متوافق مع OpenAI (Chat Completions، Responses) | https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 |
| متوافق مع Anthropic | https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic |
| DashScope HTTP | https://ap-southeast-1.maas.qwencloudapi.com/api/v1 |

مفتاح خطة الرموز (sk-sp-) يعمل فقط على token-plan.maas.qwencloudapi.com، ومفتاح الدفع حسب الاستخدام يعمل فقط على نطاق منطقته الخاصة. خلط بينهما يسبب خطأ 401. راجع المناطق ونقاط النهاية.
أول استدعاء لك عبر Qwen4-Max API
ثبّت مكتبة OpenAI SDK (pip install openai) وشغّل مثال البدء السريع من الوثائق:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1"
)
completion = client.chat.completions.create(
model="qwen4-max",
messages=[{"role": "user", "content": "Summarize the benefits of solar energy in three bullet points."}]
)
print(completion.choices[0].message.content)
وضع التفكير مفعّل افتراضيًا في qwen4-max، لذا سيستهلك هذا الاستدعاء أيضًا رموز استدلال. للمدخلات الطويلة، استخدم البث (streaming) أو اضبط مهلة العميل على 180 ثانية أو أكثر.
وضع التفكير وبث reasoning_content
Qwen4-Max نموذج هجين يدعم التفكير. القيم الافتراضية الموثقة هي enable_thinking=true وreasoning_effort=high وthinking_budget=131072. مستويات الجهد هي low وhigh وxhigh؛ بينما none يعطّل التفكير.
بث الاستدلال والإجابة على مرحلتين (معدّل من نموذج صفحة النموذج):
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1",
)
messages = [{"role": "user", "content": "Who are you"}]
completion = client.chat.completions.create(
model="qwen4-max",
messages=messages,
extra_body={"enable_thinking": True},
stream=True
)
for chunk in completion:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if getattr(delta, "reasoning_content", None):
print(delta.reasoning_content, end="", flush=True) # phase 1: thinking
if delta.content:
print(delta.content, end="", flush=True) # phase 2: answer
ثلاث قواعد مهمة:
- حدّد حجم الإخراج باستخدام
max_completion_tokens. مع تفعيل التفكير، يقبلmax_tokensالقيم من 1 إلى 32,768 فقط (وإلا يُرجع خطأ 400). أماmax_completion_tokensفيغطي الاستدلال والرد معًا دون هذا الحد. - اضبط عمق التفكير عبر
extra_body. مرّر{"enable_thinking": True, "reasoning_effort": "xhigh"}للمسائل الصعبة، أو"low"للمسائل البسيطة. - احتفظ بالاستدلال في المحادثات متعددة الأدوار. يدعم
qwen4-maxخيارpreserve_thinkingمفعّلًا افتراضيًا، لذا أعد إرسال الاستدلال السابق في حقلreasoning_contentلكل رسالة من المساعد، ولا تضعه أبدًا داخلcontent.
لتجاوز التفكير، مرّر {"enable_thinking": False}.
إدخال الصور والفيديو
أرسل الصور كأجزاء من نوع image_url والفيديوهات كأجزاء من نوع video_url. هذا مثال معدّل من وثائق الرؤية مع ضبط النموذج على qwen4-max:
completion = client.chat.completions.create(
model="qwen4-max",
messages=[{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/invoice.jpg"}},
{"type": "text", "text": "Describe what you see in this image"},
],
}],
)
للفيديو، استخدم {"type": "video_url", "video_url": {"url": "..."}, "fps": 2}. وتُرسل الملفات المحلية كـ Base64 Data URIs.
يتيح دليل الرؤية حتى 2,048 صورة عبر URL بحجم 20 ميغابايت لكل صورة، و250 صورة Base64، و64 ميغابايت لكل طلب. تُضبط تفاصيل الصورة افتراضيًا على الوضع العالي (high)، وهو ما يستهلك رموز إدخال أكثر.
استدعاء الدوال
مرّر مصفوفة tools كما تفعل مع أي نموذج متوافق مع OpenAI:
tools = [{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Useful when you want to check the weather for a specific city.",
"parameters": {
"type": "object",
"properties": {"location": {"type": "string", "description": "City or county, such as Singapore or New York."}},
"required": ["location"],
},
},
}]
completion = client.chat.completions.create(model="qwen4-max", messages=messages, tools=tools)
اقرأ message.tool_calls، ونفّذ الدالة، وأضف رسالة من نوع tool، ثم استدعِ مرة أخرى.
في وضع التفكير، يقبل tool_choice القيمتين "auto" و"none" فقط؛ لفرض استدعاء دالة معينة، عطّل التفكير أولًا. ومع تفعيل التفكير، أعد إرسال reasoning_content مع نتائج الأدوات، وإلا ستنخفض الدقة.
المخرجات المهيكلة
يدعم qwen4-max وضع JSON Schema الصارم:
completion = client.chat.completions.create(
model="qwen4-max",
messages=[{"role": "user", "content": "Extract the name and age: Ana is 31."}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "user_info",
"strict": True,
"schema": {
"type": "object",
"properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
"required": ["name", "age"],
"additionalProperties": False,
},
},
},
)
في الوضع الأكثر مرونة {"type": "json_object"}، يجب أن تظهر كلمة "JSON" في إحدى الرسائل وإلا رفضت الواجهة الطلب. أما مدخلات الصور أو الفيديو فتعود تلقائيًا إلى json_object، أي لا يُفرض المخطط (schema) على الاستدعاءات متعددة الوسائط.
الذاكرة المؤقتة للسياق والمعالجة الدفعية
الذاكرة المؤقتة. بدون أي إعدادات، تطابق الذاكرة المؤقتة الضمنية البادئات لكنها لا تضمن حدوث المطابقة. للحصول على نتائج حتمية، استخدم الذاكرة المؤقتة الصريحة لـ Qwen4: ضع علامة على كتلة محتوى باستخدام "prompt_cache_breakpoint": {"mode": "explicit"} (يجب أن يكون حقل content للرسالة مصفوفة)، واضبط مدة البقاء (TTL) باستخدام extra_body={"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}}. قيم TTL هي 5m أو 1h، ويحتاج البادئة المخزنة إلى 1,024 رمزًا على الأقل. تكلّف عمليات القراءة 0.075 دولار لكل مليون رمز، أي أقل بنسبة 95% من الإدخال الجديد.
المعالجة الدفعية. يفوتر دليل المعالجة الدفعية الإدخال والإخراج بنسبة 50% من السعر الفوري، وتعود النتائج خلال 24 ساعة. بالنسبة إلى qwen4-max، تعمل ميزة Batch File في منطقة واحدة خارج سنغافورة ولا تدعم التخزين المؤقت للسياق، لذا راجع دليل المعالجة الدفعية قبل بناء خط معالجة يعتمد عليها.
مسار التوافق مع Anthropic
هل بني مشروعك بالفعل على مكتبة Anthropic SDK؟ غيّر عنوان URL الأساسي والمفتاح فقط:
import anthropic
import os
client = anthropic.Anthropic(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic",
)
message = client.messages.create(
model="qwen4-max",
max_tokens=1024,
messages=[{"role": "user", "content": "Who are you?"}],
thinking={"type": "disabled"},
)
print(message.content)
هذا المثال يعطّل التفكير، تمامًا كمثال الوثائق الرسمي. أنهِ عنوان URL الأساسي عند /apps/anthropic. إضافة /v1/ تنتج مسارًا مثل /v1/v1/... وخطأ 404. التفكير مفعّل افتراضيًا هنا أيضًا، ومع تفعيله يجب أن يتجاوز max_tokens ميزانية التفكير. يُضبط الجهد عبر output_config.effort (بقيم low وhigh وxhigh)، وأداتا web_search وweb_fetch المدمجتان متاحتان على هذا المسار.
حدود معدل الاستدعاء في Qwen4-Max API
من صفحة حدود المعدل:
| المنطقة | RPM | TPM |
|---|---|---|
| سنغافورة | ديناميكي | فئات ديناميكية: 5 ملايين، 10 ملايين، 20 مليون |
| فرانكفورت، طوكيو، الولايات المتحدة (فرجينيا) ومناطق النطاق العالمي الأخرى | 30,000 | 5,000,000 |
تُطبق الحدود على كل حساب في كل منطقة، وكذلك في كل ثانية (RPS = RPM / 60)، لذا قد يؤدي دفعة مفاجئة من الطلبات إلى تقييدك حتى وإن كنت تحت الإجمالي الدقيقة الواحدة.
توضح صفحة الحصة المجانية أن الحصة المجانية متوفرة في سنغافورة فقط، وتُحتسب لكل نموذج (مليون رمز عادةً)، وتبقى صالحة لمدة 90 يومًا، وتتطلب إدخال بيانات الدفع. ولا تذكر qwen4-max بالاسم، لذا تحقق من صفحة الخطة المجانية (Free Tier) في لوحة التحكم، أو اقرأ كيفية استخدام Qwen4-Max مجانًا.
أخطاء Qwen4-Max API الشائعة
| الرمز | المعنى | الحل |
|---|---|---|
401 InvalidApiKey |
المفتاح وعنوان URL الأساسي من منطقتين مختلفتين، أو أن مفتاح خطة الرموز وصل إلى نقطة نهاية بنظام الدفع حسب الاستخدام | استخدم مفتاحًا منشأًا في نفس منطقة عنوان URL |
400 InvalidParameter |
غالبًا max_tokens خارج النطاق من 1 إلى 32,768 مع تفعيل التفكير |
انتقل إلى max_completion_tokens |
403 AllocationQuota.FreeTierOnly |
نُفدت الحصة المجانية قبل إعداد الدفع | أضف بيانات الدفع في صفحة الخطة المجانية |
404 ModelNotFound |
qwen4-max غير متاح في المنطقة التي استدعيتها |
تحقق من أسعار النماذج في تلك المنطقة |
429 Throttling |
تم بلوغ حد RPM أو TPM | انتظر ثم أعد المحاولة، أو وزّع الحمل على ثوانٍ متعددة |
دع وكيل البرمجة الخاص بك يختبر Qwen4-Max API عبر Apidog CLI
وكيل البرمجة لديك يكتب التكامل، فدعه يكتب اختبار الانحدار أيضًا. تتيح له Apidog CLI حفظ نقطة النهاية، وتخزين المفتاح، وتشغيل التحققات (assertions).

جهّز الإعداد مرة واحدة:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
ثم امنح وكيلك طلبًا واحدًا (prompt):
In Apidog project <projectId>, create an environment "Qwen Singapore" with base URL
https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 and a secret
variable DASHSCOPE_API_KEY. Add POST /chat/completions with a Bearer auth header,
model qwen4-max and enable_thinking true. Create a test case asserting status 200,
a non-empty choices array, a usage object, and reasoning_content present on the
first choice's message. Run it and summarize any failures.
يقرأ الوكيل مخطط كل حمولة (payload) قبل الكتابة، ثم يشغّل حالة الاختبار:
apidog environment create "Qwen Singapore" --project <projectId> --base-url https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
apidog cli-schema get environment-update
apidog environment update <envId> --project <projectId> --file env.json
apidog cli-schema get endpoint-create
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json
يعرض مُقرّر cli النجاح أو الفشل؛ بينما يكتب json تقريرًا يقرأه الوكيل. انقل الأمر نفسه apidog run ... -r junit إلى خط أنابيب CI عبر دليل CI/CD لـ Apidog CLI، واطلع على Apidog CLI في Claude Code لمزيد من الأوامر. تغطي خطة Apidog المجانية حتى 4 مستخدمين.
الأسئلة الشائعة
ما هو معرّف النموذج في Qwen4-Max API؟
المعرّف الثابت هو qwen4-max. أما المعرّف السابق qwen4-max-preview فكان خاصًا بخطة الرموز فقط خلال فترة المعاينة التي بدأت في 11 نوفمبر 2026.
هل تتوافق Qwen4-Max API مع OpenAI؟
نعم. استخدم مكتبة OpenAI SDK مع عنوان URL الأساسي /compatible-mode/v1 لكل من Chat Completions وواجهة Responses API. وتتوفر أيضًا نقطة نهاية متوافقة مع Anthropic وواجهة DashScope API.
كيف أعطّل التفكير في Qwen4-Max API؟
مرّر extra_body={"enable_thinking": False}. ستفقد reasoning_content، لكن زمن الاستجابة ورموز الإخراج ستنخفض. لمقارنة النماذج، راجع Qwen4-Max مقابل Qwen3.8.
كم تكلّف Qwen4-Max API؟
1.50 دولار لكل مليون رمز إدخال و4.50 دولار لكل مليون رمز إخراج، مع قراءة مخزنة مؤقتًا بتكلفة 0.075 دولار لكل مليون رمز.
هل يمكنني استخدام مفتاح خطة الرموز مع واجهة الدفع حسب الرموز؟
لا. مفاتيح خطة الرموز (sk-sp-) تعمل فقط على token-plan.maas.qwencloudapi.com، ومفاتيح الدفع حسب الاستخدام تعمل فقط على نطاق منطقتها الخاصة.
