وثائق Anthropic Messages API: نقاط النهاية، الطلبات، الرؤية، والخلفيات الوكيلة

Anthropic Messages API هي الواجهة الرئيسية لـ HTTP لإرسال الاستفسارات إلى Claude. نقطة النهاية الأساسية هي POST /v1/messages: تقدم نموذجًا، قائمة من كتل المحتوى النصية المحددة النوع، وحدًا أقصى للرموز، ثم تتلقى رسالة مساعد تحتوي على كتلة إخراج واحدة أو أكثر.

يحول هذا الدليل وثائق Anthropic API إلى قائمة تحقق تنفيذية. يغطي عقد الطلب، الحالة متعددة الدورات، التدفق، الرؤية، ملفات API، استخدام الأدوات، والخيارات المتاحة عندما تحتاج خلفية وكيلة إلى دعم كل من موفري النماذج الأصلي لـ Anthropic والمتوافق مع OpenAI.

نقطة نهاية Messages API ورؤوس HTTP المطلوبة

تستخدم Messages API الأصلية لـ Anthropic نقطة النهاية التالية:

POST https://api.anthropic.com/v1/messages

عادةً ما تتضمن طلبات HTTP المباشرة هذه الرؤوس:

الرأس	الغرض
x-api-key	مصادقة حساب Anthropic
anthropic-version	يختار عقد إصدار API الموثق
content-type: application/json	يعلن عن نص طلب بتنسيق JSON

رأس إصدار API ليس إصدار نموذج. يتحكم في سلوك HTTP API، بينما يحدد حقل model نموذج Claude المستخدم للاستدلال. احتفظ بكلا القيمتين في التكوين بدلاً من توزيعهما في كود التطبيق.

هيكل الطلب والاستجابة

يحتوي الطلب الأساسي على ثلاثة حقول:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "اشرح مفاتيح idempotency في فقرتين."
    }
  ]
}

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

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "مفتاح idempotency هو..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 126
  }
}

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

طلب curl بسيط

قم بتخزين بيانات الاعتماد في متغير بيئة واستخدم معرف نموذج متاح حاليًا لحساب Anthropic الخاص بك:

export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="your-claude-model-id"

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "أعد ثلاث طرق عملية لتقليل زمن استجابة API."
      }
    ]
  }'

لا تقم بتعيين اسم نموذج منسوخ من برنامج تعليمي قديم. يمكن أن تتغير توفر النماذج وأسماءها المستعارة، لذا يجب أن يستخدم تكوين النشر معرف نموذج تم التحقق منه في وثائق النموذج الحالية للمزود أو في لوحة التحكم.

استخدام Python مع SDK الرسمي لـ Anthropic

يتولى SDK الرسمي لـ Python رؤوس المصادقة ويحول الاستجابة إلى كائنات محددة النوع:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": "اكتب دالة Python تتحقق من صحة سلسلة UUID.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

التكرار على كتل المحتوى أكثر أمانًا من افتراض أن message.content[0] هو دائمًا نص. قد تتلقى التطبيقات الوكيلة كتل استخدام الأدوات، ويمكن للميزات متعددة الوسائط إضافة أنواع كتل أخرى إلى المحادثة.

محادثات متعددة الدورات ورسائل النظام

Messages API هي عديمة الحالة. يرسل تطبيقك سجل المحادثة ذي الصلة مرة أخرى مع كل طلب:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 512,
  "system": "أنت مساعد موجز لوثائق API.",
  "messages": [
    {"role": "user", "content": "ماذا يعني رمز HTTP 429؟"},
    {"role": "assistant", "content": "يشير إلى تحديد المعدل."},
    {"role": "user", "content": "كيف يجب أن يعيد عميلي المحاولة؟"}
  ]
}

تضع Anthropic تعليمات النظام في الحقل العلوي system بدلاً من رسالة تحتوي على role: "system". هذا أحد الاختلافات الهامة التي يجب مراعاتها عند ترجمة الطلبات من مخططات متوافقة مع OpenAI.

لجلسات طويلة الأمد، لا تقم بإعادة إرسال نص غير محدود. احتفظ بأحدث الأدوار، واحتفظ بالقرارات ونتائج الأدوات التي لا تزال تؤثر على المهمة، ولخص السياق الأقدم قبل أن يقترب الاستفسار من حد سياق النموذج المحدد.

استجابات التدفق

اضبط stream: true عندما يجب أن تعرض الواجهة الإخراج بشكل تزايدي:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with client.messages.stream(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "اشرح تجميع اتصالات قاعدة البيانات."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

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

طلبات رؤية Claude API

تستخدم رؤية Claude API نفس نقطة نهاية Messages. أضف كتلة محتوى صورة قبل سؤال النص ذي الصلة. يمكن تقديم الصور كبيانات base64 مدعومة أو من خلال نوع مصدر مسموح به موصوف في وثائق الرؤية الحالية.

import base64
import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with open("architecture.png", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode("utf-8")

message = client.messages.create(
    model=os.environ["ANTHROPIC_VISION_MODEL"],
    max_tokens=700,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "حدد خطرين موثوقية في مخطط العمارة هذا.",
                },
            ],
        }
    ],
)

تأكد من تغيير حجم الصورات الكبرة قبإرسالها. تزد الصورات الكبرة وق النقل وتسلاهم الرموز دون تحسن الإجابة بالضرورة. تحقق أيصا من نع MIME؛ إعلان بياتات JPEG على أنها PNG هو سبب شائع لرفض الطلبات.

استخدام ملفات API لـ Anthropic

ملفات API لـ Anthropic مفيدة عنما يحب رفع ملف مرة واحدة والإشارة إليه بواسطة استدعاءات Messages API لاحقة بدلاً من تشفيره وإرساله مرارًا وتكرارًا. قد يختلف التوفر الدقيق وأنواع الملفات المدعومة وحقول الطلب حسب حالة الميزة، لذا تحقق من وثائق Files API الحالية قبل الاعتماد عليها في الإنتاج.

التكامل النموذجي له مرحلتان:

1. رفع الملف وحفظ معرف الملف الذي تم إرجاعه مع سجل المستند الخاص بتطبيقك.
2. الإشارة إلى ذلك المعرف في كتلة محتوى مدعومة عند إنشاء رسالة.

تعامل مع معرفات الملفات كمحددة للمزود. سجل أي مزود وحساب أنشأ كل معرف، وطبق ضوابط الوصول الخاصة بك، وحدد سياسة الحذف. يجب عدم قبول معرف الملف مباشرة من مستخدم غير موثوق دون فحوصات التصريح.

للصور الصغيرة العرضية، تكون base64 مبشطة. للمستندات المسخدمة عبر طلبات متعددة، يمكن لمورد ملف المزود تقليل الرفع المتكرر. إذا كاان تطبيقك يجب أن يعمل عبر مزودين متعددين، احتفظ بالكائن الأصلي في تخزينك الخاص وأنشئ معرفات ملف خاصة بالمزود كذاكرة مؤقتة.

استخدام الأدوات للخلفيات الوكيلة

تسمح الأدوات لـ Claude بطلب دالة محددة من التطبيق. تصف خلفيتك كل أدة باسم، وغرص، وعقد إدخال JSON Schema. يمكن للنموذج بعد ذلك إرجاع كتلة tool_use بدلاً من التظاهر بأنه نفذ العملية.

{
  "name": "get_order_status",
  "description": "ابحث عن الحالة الحالية لطلب عميل.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "معرف الطلب الذي يظه للعميل."
      }
    },
    "required": ["order_id"]
  }
}

حلقة التنفيذ الأمنة هي:

1. إرسال الرسائل وتعريفات الأدوات إلى النموذج.
2. اكتشاف كتلة محتوى tool_use.
3. التحقق من صح إدخالها مقابل المخطط وقواعد التصريح الخاصة بك.
4. تنفيذ الأداة في بيئة مضبوطة.
5. إرجاع كتلة tool_result مطابقة في دور المستخدم التالي.
6. الاستمرار حتى ينتج النموذج إجابة عادية أو يصل إلى حد الحلقة.

لا تقم أبدًا بتنفيذ وسائط الأداة كأوامر shell أو SQL أو مسارات ملفات موثوقة. للوكلاء البرمجة، قم بتشغيل الأوامر المولدة داخل بيئة معزولة مثل Novita Agent Sandbox، مع حدود زمنية، وشبكية، ونظام الملفات، والموارد صرية.

طلبات Anthropic الأصلية مقابل طلبات المتوافقة مع OpenAI

تحل APIs الأصلية لـ Anthropic والمتوافقة مع OpenAI نفس المشكلة العامة، لكن تنسيقات الاتصال السلكي ليست متطابقة.

الجانب	Anthropic Messages API	OpenAI-compatible chat API
نقطة النهاية الشائعة	/v1/messages	/v1/chat/completions
تعليمة النظام	حقل system على المستوى الأعلى	غالبًا رسالة system أو developer
تمثيل الإخراج	كتل محتوى محددة النوع	غالبًا choices[].message
طلب الأداة	كتلة tool_use	غالبًا tool_calls
نتيجة الأداة	كتلة محتوى tool_result	غالبًا رسالة دور tool

نقطة النهاية المتوافقة مع OpenAI ذات قيمة عندما يستخدم تطبيقك بالفعل SDK لـ OpenAI أو يحتاج إلى التبديل بين نماذج مفتوحة المصدر مع تغييرات نقل ضئيلة. تعرض Novita AI واجهة LLM متوافقة مع OpenAI، لذا يمكن لنفس هيكل العميل استهداف عدة نماذج متاحة عن طريق تغيير عنوان URL الأساسي وتكوين النموذج.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/v3/openai",
)

response = client.chat.completions.create(
    model=os.environ["NOVITA_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "راجع استراتيجية إعادة المحاولة هذه لأنماط الفشل.",
        }
    ],
)

print(response.choices[0].message.content)

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

بناء خلفية وكيلة محايدة للمزود

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

1. نموذج المحادثة: تخزين الأدوار، النص، الصور، استدعاءات الأدوات، ونتائج الأدوات في مخطط داخلي.
2. محول المزود: ترجمة المخطط الداخلي إلى حمولات Anthropic Messages أو متوافقة مع OpenAI.
3. سجل القدرات: تتبع ما إذا كان النموذج المحدد يدعم الرؤية، الأدوات، الإخراج المنظم، أو أي سلوك مطلوب آخر.
4. طبقة التنفيذ: تشغيل الأدوات والكود بشكل منفصل عن مزود الاستدلال.

يسمح هذا الفصل للفريق باستخدام Claude حيث يكون السلوك الأصلي لـ Anthropic مهمًا مع توجيه أعباء العمل المتوافقة إلى نموذج مفتوح المصدر عبر Novita AI. يمكن أن يكون المسار مفتوح المصدر مفيدًا للتحكم في التكاليف، أو تجربة النماذج، أو متطلبات موقع البيانات، أو تجنب الاعتماد على مزود واحد. اختبر جودة الإخراج وموثوقية الأداة على مهامك الخاصة بدلاً من افتراض أن نموذجين قابلان للتبادل لأن كلاهما يقبل رسائل الدردشة.

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

الأخطاء الشائعة وتصحيح الأخطاء

400 طلب سيء

تحقق من شكل JSON، وأنواع كتل المحتوى، والحقول المطلوبة، وما إذا كان النموذج المحدد يدعم الميزة المطلوبة. سجل معرف طلب المزود وجسم الخطأ المنظم، لكن قم بإخفاء بيانات الاعتماد وبيانات الملفات base64.

401 خطأ في المصادقة

تأكد من وجود مفتاح API في بيئة التشغيل وأنه ينتمي إلى المزود المقصود. تستخدم Anthropic x-api-key لطلبات HTTP المباشرة؛ عادةً ما يرسل عميل متوافق مع OpenAI رمز bearer تلقائيًا.

404 النموذج أو المورد غير موجود

تحقق من معرف النموذج مقابل وثائق المزود الحالية أو لوحة التحكم. لموارد Files API، تحقق أيضًا من أن الملف ينتمي إلى نفس الحساب والبيئة المستخدمة في الطلب.

429 حد المعدل

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

أخطاء حد السياق أو الرموز

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

مقالات موصى بها

• ما هي وكلاء البرمجة؟ البنية، الأدوات، وحلقات التنفيذ
• ما هو MCP؟ دليل المطور لبروتوكل سياق النموذج
• دليل LLM مفتوح المصدر 2026: نماذج، مفايزات، ونشر

قائمة تحقق التنفيذ

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

Messages API بسيطة على مستوى HTTP. العمل الهندسي الأصعب يظهر عنما يضيف تطبيق التدفق، الإدخال المتعدد الوسائط، الأدوات، الملفات الدائمة، أو مزودي نماذج متعددين. احتفظ بهذه المهمات خلف محولات صريحة، ويمكن لخلفيتك الوكيلة أن تتطور دون ربط منطق الأعمال بتنسيق طلب واحد.

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

ما هي نقطة نهاية Anthropic Messages API؟

نقطة النهاية الأصلية هي POST https://api.anthropic.com/v1/messages. تتطلب الطلبات المصادقة، رأس إصدار Anthropic API، معرف نموذج، حد رموز، ومصفوفة رسائل.

هل Anthropic Messages API متوافقة مع OpenAI؟

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

هل تستخدم رؤية Claude API نقطة نهاية منفصلة؟

لا. تستخدم طلبات الرؤية Messages API مع صور وكتل محتوى نصية. يجب أن يدعم نموذج Claude المحدد إدخال الصور.

متى يجب استخدام ملفات API لـ Anthropic؟

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

هل يمكن لـ Claude Code استخدام خلفية API مخصصة؟

يعتمد تكامل Claude Code على المصادقة وتكوين المزود المدعوم من قبل إصدار Claude Code الحالي. لا تفترض أن نقطة نهاية متوافقة مع OpenAI تنفذ Messages API لـ Anthropic. لوكيل مخصص، يكون المحول المحايد للمزود أكثر وضوحًا عادةً من محاولة جعل بروتوكلات مختلفة تبدو متطابقة.

متى يجب اختيار نموذج مفتوح المصدر عبر Novita AI؟

فكر فيه عنما تريد تبديل نماذج متوافقة مع OpenAI، أو تجربة نماذج مفتوحة المصدر، أو مزود ثاني لأعباء العمل المتوافقة. احتفظ بطلبات Anthropic الأصلية للميزات التي تتطلب سلوك API خاص بـ Claude، وقم بتقييم كلا المسارين على استفساراتك وأدواتك الخاصة.