كيفية استخدام واجهة برمجة التطبيقات Qwen4-Max

أصبحت واجهة برمجة التطبيقات Qwen4-Max متاحة الآن بسعر 1.50 دولار/4.50 دولار لكل مليون رمز. في هذا المقال ستتعرف على كيفية الحصول على مفتاح API، واختيار عنوان URL الأساسي، وبث عملية التفكير، وإرسال الصور، واستدعاء الأدوات، وفرض صيغة JSON، وتخزين المطالبات مؤقتًا، واستخدام مسار Anthropic، بالإضافة...

INEZA Felin-Michel

INEZA Felin-Michel

16 نوفمبر 2026

كيفية استخدام واجهة برمجة التطبيقات Qwen4-Max

Apidog للمؤسسات

النشر على الخوادم المحلية

SSO و RBAC

متوافق مع SOC 2

استكشف Apidog للمؤسسات

أصبحت واجهة 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 الأساسي المناسب

المفاتيح مرتبطة بمنطقة معينة، ويجب أن يتطابق نوع المفتاح مع نقطة النهاية.

  1. افتح لوحة تحكم QwenCloud واختر المنطقة من محدد أعلى يمين الشاشة.
  2. انتقل إلى API Keys، وانقر على Create API key، وأضف وصفًا ثم انقر على Generate Key.
  3. انسخ المفتاح فورًا؛ إذ يُعرض مرة واحدة فقط. تبدأ المفاتيح الجديدة بنظام الدفع حسب الاستخدام بالبادئة sk-ws-.
  4. صدّره كمتغير بيئة: 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
Diagram of one pay-as-you-go qwen4-max key reaching the Singapore domain, which serves three paths: /compatible-mode/v1 for the OpenAI SDK, /apps/anthropic for the Anthropic SDK and /api/v1 for DashScope

مفتاح خطة الرموز (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

ثلاث قواعد مهمة:

لتجاوز التفكير، مرّر {"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).

Flow from one prompt to a coding agent, which runs apidog environment create, endpoint create, test-case create with assertions on status, choices, usage and reasoning_content, then apidog run for a pass or fail report

جهّز الإعداد مرة واحدة:

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، ومفاتيح الدفع حسب الاستخدام تعمل فقط على نطاق منطقتها الخاصة.

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات