كيفية استخدام واجهة Muse Wonder API

واجهة Muse Wonder API هي Model API من Meta التي تقدم muse-wonder-1.0 عبر https://api.meta.ai/v1، بثلاث صيغ للطلبات: Responses API وChat Completions ونقطة نهاية Messages المتوافقة مع Anthropic. تقوم بالمصادقة بمفتاح bearer من dev.meta.ai، وتدفع $4 لكل مليون رمز إدخال و$20 لكل مليون رمز إخراج، وتحصل على نافذة سياق تبلغ مليون رمز مع جهد استدلال يتراوح من minimal إلى max. يعمل أي SDK من OpenAI بمجرد تغيير عنوان URL الأساسي.

جرّب Apidog اليوم

يرافقك هذا الدليل من المفتاح إلى حلقة وكيلة عاملة: الطلب الأول، واختيار نقطة النهاية، والتحكم في الاستدلال، وحالة الأدوار المتعددة، والأدوات، والبث، والتشغيل في الخلفية، وحقول الاستخدام التي تخبرك بتكلفة كل استدعاء. كل طلب مُهيأ أيضًا في Apidog ليتمكن فريقك من اختبار النموذج دون تداول المفتاح. ولمعرفة ما هو هذا النموذج وكيف يسجّل، ابدأ بـشرح Muse Wonder.

واجهة Muse Wonder API في لمحة

	القيمة
عنوان URL الأساسي	https://api.meta.ai/v1
معرّف النموذج	muse-wonder-1.0
المصادقة	Authorization: Bearer $MODEL_API_KEY
نقاط النهاية	POST /v1/responses، POST /v1/chat/completions، POST /v1/messages
السعر لكل مليون رمز	$4 للإدخال، $20 للإخراج، $0.20 للإدخال المخزَّن مؤقتًا
نافذة السياق	1,048,576 رمزًا، بلا علاوة على السياق الطويل
جهد الاستدلال	minimal، low، medium، high، xhigh، max
حدود المعدل	3,000 طلب و4 ملايين رمز في الدقيقة، لكل فريق ولكل نموذج
أداة البحث على الويب	$2.50 لكل 1,000 استعلام، فوق الرموز

أما Muse Wonder Full، النموذج الأكبر، فغير متوفر عبر الـAPI. إنه متاح فقط داخل Muse Code في خطتي Power وMaximum. وضبط الجهد على max في Wonder لا يحوّله إلى Full.

الخطوة 1: احصل على مفتاح وقم بأول استدعاء

أنشئ مفتاحًا في لوحة تحكم Model API ضمن مفاتيح API واحفظه باسم MODEL_API_KEY. ثم:

curl https://api.meta.ai/v1/responses \
  -H "Authorization: Bearer $MODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-wonder-1.0",
    "input": "List three risks in a lease clause that lets the landlord enter without notice.",
    "reasoning": {"effort": "medium"},
    "max_output_tokens": 2048
  }'

مع SDK الخاص بـOpenAI، غيّر سطرين:

from openai import OpenAI
import os

client = OpenAI(base_url="https://api.meta.ai/v1", [REDACTED CREDENTIAL]

resp = client.responses.create(
    model="muse-wonder-1.0",
    input="List three risks in a lease clause that lets the landlord enter without notice.",
    reasoning={"effort": "medium"},
    max_output_tokens=2048,
)
print(resp.output_text)
print(resp.usage)

تحمل الاستجابة النص مع كتلة usage. راجعها في كل استدعاء: يخبرك output_tokens_details.reasoning_tokens بمقدار ميزانية الإخراج الذي ذهب إلى التفكير، ويخبرك input_tokens_details.cached_tokens بمقدار الإدخال الذي فُوتر بسعر التخزين المؤقت.

الخطوة 2: اختر نقطة نهاية

يستخدم الدليل التمهيدي من Meta واجهة Responses API، وهي الخيار الافتراضي الصحيح لأي عمل متعدد الخطوات. فهي تحافظ على الاستدلال عبر الأدوار ويمكنها إدارة سجل المحادثة نيابةً عنك. أما Chat Completions فموجود للكود الذي لديك أصلًا والمرتبط بـSDK من OpenAI. وتقبل نقطة نهاية Messages على https://api.meta.ai/v1/messages الطلبات بصيغة Anthropic، وهو ما يشغّل Claude Code فوق Muse Wonder.

الاحتياج	استخدم
وكيل جديد، حلقات أدوات، جلسات طويلة	Responses
كود موجود بنمط OpenAI، أدوار مفردة	Chat Completions
Claude Code أو إطار آخر بصيغة Anthropic	Messages
ملخصات الاستدلال	Responses فقط

تختلف الصيغ الثلاث في أسماء المعاملات. جهد الاستدلال هو reasoning.effort في Responses، وreasoning_effort في المستوى الأعلى في Chat Completions. وسقفا الإخراج هما max_output_tokens وmax_tokens على التوالي. والمخرجات المهيكلة في Responses تستخدم text.format لا response_format.

الخطوة 3: اضبط جهد الاستدلال

يستدل Muse Wonder دائمًا. ويعيد none الخطأ HTTP 400. المستويات المقبولة هي minimal وlow وmedium وhigh وxhigh وmax، وإذا حذفت المعامل اختار النموذج مستواه بنفسه. ونصيحة Meta هي المعتادة: استخدم أدنى مستوى يعطي نتائج مقبولة، لأن رموز الاستدلال تُفوتر بسعر الإخراج البالغ $20 وتُحتسب ضمن سقف الإخراج.

تترتب على ذلك قاعدتان عمليتان. أولًا، اجعل max_output_tokens سخيًا عند الجهد العالي؛ فعند max يشكّل الاستدلال حصة كبيرة من الإخراج، والسقف الضيّق يقتطع الإجابة. ثانيًا، سجّل reasoning_tokens لكل نوع طلب لترى ما يكلفه كل مستوى جهد على حركتك أنت، لا على معيار قياس. وقد استخدمت تشغيلات Artificial Analysis التي منحت النموذج 52 جهد max ونحو 54,000 رمز إخراج لكل مهمة.

في واجهة Responses يمكنك طلب ملخص للاستدلال بضبط reasoning.summary على auto أو concise أو detailed. الملخصات غير مضمونة؛ فقد يعود المصفوفة فارغة. والاستدلال الخام لا يُعاد أبدًا.

الخطوة 4: احمل الحالة عبر الأدوار

تقدم واجهة Responses نمطين، ولا يمكن الجمع بينهما.

إعادة التشغيل المشفّرة عديمة الحالة هي توصية Meta. أرسل store: false وinclude: ["reasoning.encrypted_content"]، واحتفظ بعناصر reasoning التي تعيدها الاستجابة، ثم مررها في الدور التالي مع encrypted_content وحقل summary (والمصفوفة الفارغة تكفي). ينجو استدلال النموذج عبر الدور دون أن تخزّن Meta شيئًا.

السجل المُدار من الخادم أبسط: مرر previous_response_id وأرسل الإدخال الجديد فقط. ولاحظ أن instructions لا يُحمل عبر الأدوار، فأعد إرسال تعليمات النظام في كل طلب.

first = client.responses.create(model="muse-wonder-1.0", input="Summarize this API's auth flow: ...", instructions="You are an API reviewer.")
second = client.responses.create(model="muse-wonder-1.0", previous_response_id=first.id, instructions="You are an API reviewer.", input="Now list the endpoints that need an OAuth scope.")

الخطوة 5: الأدوات والمخرجات المهيكلة والبحث على الويب

تتبع أدوات الدوال (function tools) صيغة OpenAI في Responses وChat Completions. ويستدعي Muse Wonder الأدوات بالتوازي ومدرَّب على التعافي من استدعاءات الأدوات الفاشلة، وهو أحد ما تعنيه تدوينة إطلاق Meta بمصطلح Active Focus. عرّف الأدوات بمخطط JSON، ونفّذ عناصر function_call التي يعيدها النموذج، وأرسل عناصر function_call_output في المقابل.

للحصول على إجابة يستطيع كودك تحليلها، اضبط text.format على مخطط JSON في Responses. وللمعلومات الحالية، أضف البحث المستضاف من Meta عبر tools=[{"type": "web_search"}]؛ وهو يُفوتر $2.50 لكل 1,000 استعلام فوق الرموز. وإذا كنت تختبر استدعاءات الأدوات لنماذج أخرى أصلًا، فإن منصة اختبار استدعاءات الأدوات للوكلاء في Apidog تعمل هنا دون تغيير: صيغة الطلب هي ذاتها التي تستخدمها OpenAI.

الخطوة 6: بث النتائج أو التشغيل في الخلفية

اضبط stream: true واستهلك تدفق الأحداث: response.created ثم response.output_item.added ثم response.output_text.delta ثم response.function_call_arguments.delta ثم response.completed. وينتهي الفشل بـresponse.failed. وتصل ملخصات الاستدلال بصيغة response.reasoning_summary_text.delta عند طلبها.

للمهام الطويلة، أرسل background: true. تؤكد الـAPI الاستلام بـ"status": "queued"، ويمكنك الاستقصاء أو بث أحداث دورة الحياة من GET /v1/responses/{id}?stream=true. ولا يمكن الجمع بين background وstream: true في طلب POST، ويُسقَّف جسم الطلب عند 1 MiB، وهناك حد منفصل يبلغ 600 طلب جديد في الخلفية في الدقيقة لكل فريق. ألغِ عبر POST /v1/responses/{id}/cancel.

الخطوة 7: خزّن مؤقتًا ما يتكرر

الإدخال المخزَّن مؤقتًا يكلف $0.20 لكل مليون، بخصم 95% عن سعر $4، وتُبلغ عنه Meta في usage.input_tokens_details.cached_tokens. والنمط الذي يكسب ذلك هو نفسه لدى المزودين الآخرين: ضع المادة الثابتة (تعليمات النظام، تعريفات الأدوات، المستندات المرجعية) أولًا والمحتوى الخاص بكل طلب أخيرًا. ويغطي دليل التخزين المؤقت للمطالبات تصميم البادئة. راقب جانب الكتابة في ذاكرة التخزين المؤقت أيضًا: في تشغيل Artificial Analysis، كانت $1.92 من تكلفة Wonder البالغة $4.52 لكل مهمة كتابات في الذاكرة المؤقتة، أي أكثر من $1.44 في إصابات الذاكرة.

اختبر واجهة Muse Wonder API في Apidog

يحافظ مشروع Apidog مشترك على المفتاح بعيدًا عن محادثات الدردشة ويمنح الجميع الطلبات ذاتها.

1. أنشئ بيئة باسم Meta Model API بمعامل base_url يساوي https://api.meta.ai/v1 وبـMODEL_API_KEY كـمتغير سري. تُحجب القيم السرية في الواجهة ولا تُصدَّر أبدًا.
2. أضف ثلاثة طلبات، واحدًا لكل نقطة نهاية، كل منها مع Authorization: Bearer {{MODEL_API_KEY}}. وكرر طلب Responses بجهد low وmedium وmax لتقارن التكلفة جنبًا إلى جنب.
3. أضف تحققات على الاستخدام. أضف تحققات JSONPath على $.usage.output_tokens_details.reasoning_tokens و$.usage.input_tokens_details.cached_tokens. فقيمة رموز مخزنة مؤقتًا تساوي صفرًا في طلب كنت تتوقع فيه إصابة الذاكرة المؤشر على خلل في البادئة، يُلتقط قبل الوصول إلى الإنتاج.
4. حاكِ خطأ 429. تقول وثائق Meta بأن تتراجع أُسّيًا مع jitter انطلاقًا من نحو 500 ms وأن تحترم Retry-After. وجّه عميلك إلى mock في Apidog يعيد 429 مع تلك الترويسة وأثبت منطق إعادة المحاولة قبل أن تشارك بقية فريقك حد 3,000 طلب في الدقيقة.
5. شغّلها في CI عبر Apidog CLI ليتعطل خط الأنابيب عند تغيّر النموذج أو الأسعار بدلًا من أن يتعطل عميل.

نزّل Apidog واستورد نقاط النهاية الثلاث من أمثلة الطلبات أعلاه.

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

هل لواجهة Muse Wonder API مستوى مجاني؟ لا. الفوترة لكل رمز بلا حد أدنى، فحفنة استدعاءات تجريبية تكلف سنتات، لكن لا توجد أرصدة مجانية. ويغطي دليل الوصول المجاني أرخص المسارات.

هل تُستخدم بياناتي من الـAPI في التدريب؟ ليس في وضع Standard للـAPI. واشتراكات Muse Code تستخدم افتراضيًا وضع Contributor الذي يستخدم بياناتك فعلًا؛ وهذا الإعداد موجود في Muse Code لا في الـAPI.

هل يمكنني استخدام Muse Wonder Full عبر الـAPI؟ لا. ليس له معرّف نموذج قابل للاستدعاء ولا سعر لكل رمز. فقط مشتركو Muse Code Power وMaximum يمكنهم اختياره.

ما حدود المعدل وهل يمكن رفعها؟ 3,000 طلب و4 ملايين رمز في الدقيقة لكل نموذج، تُحتسب عبر كل مفاتيح فريقك. وصفحة أسعار Meta لا تدرج مستويات ولا عملية لرفعها. ويتناول دليل حدود المعدل كيف تبقى دونها.

الخطوة التالية

أجرِ الاستدعاءات الثلاثة أعلاه بجهد low وmedium وmax على مهمة حقيقية من منتجك، وقارن reasoning_tokens قبل أن تختار قيمة افتراضية. ذلك الرقم، لا عنوان الـ$4، هو ما ستتبعه فاتورتك.