النص

إنشاء رسالة

إنشاء رسالة باستخدام تنسيق Anthropic Messages API

POST
/v1/messages

نظرة عامة

يقبل هذا الـ endpoint تنسيق Anthropic Messages الأصلي، لذا فإن Anthropic SDKs والأدوات المبنية عليها تعمل مع عنوان URL الأساسي لـ TokenLab. وهو يعمل مع النماذج التي تدرج anthropic_messages ضمن accepted_request_formats: مثل نماذج Claude وبعض النماذج الأخرى.

يحتوي messages على أدوار user و assistant. ضع تعليمات النظام في حقل system على المستوى الأعلى. حقل max_tokens مطلوب. بالنسبة للرسائل بأسلوب OpenAI التي تحتوي على أدوار مثل system أو tool، استخدم Chat Completions.

عنوان URL الأساسي لـ Anthropic SDK: https://api.tokenlab.sh (بدون لاحقة /v1)

ترويسات الطلب (Request Headers)

x-api-keystringheader

مفتاح API الخاص بـ TokenLab. أرسل إما x-api-key أو Authorization: Bearer <API_KEY>. إذا أرسلت كليهما بقيم مختلفة، فسيستخدم TokenLab قيمة x-api-key.

anthropic-versionstringheader

إصدار Anthropic API. تقوم Anthropic SDKs بإرساله نيابة عنك؛ استخدم 2023-06-01 عند استدعاء الـ API مباشرة.

anthropic-betastringheader

أسماء ميزات Anthropic التجريبية (beta)، مفصولة بفواصل. يقوم TokenLab بتمرير الترويسة، ويعتمد عمل الميزة التجريبية على النموذج. المحتوى الذي يشير إلى file_id يحتاج إلى files-api-2025-04-14.

جسم الطلب (Request Body)

تعتمد المعلمات الاختيارية المدعومة والقيم المقبولة والقيم الافتراضية على النموذج المحدد. تحقق من تفاصيل النموذج قبل ضبط خيارات أخذ العينات (sampling) أو التفكير (reasoning) أو الأدوات (tool).

modelstringمطلوب

معرف النموذج الذي يدعم تنسيق anthropic_messages. تحقق من تفاصيل النموذج لمعرفة الإمكانيات الحالية.

messagesarrayمطلوب

مصفوفة من كائنات الرسائل مع role (user أو assistant) و content. تدعم حتى 100,000 رسالة.

يمكن أن يكون content سلسلة نصية عادية أو مصفوفة من كتل المحتوى. لإرسال صور، استخدم كتل محتوى مهيكلة بدلاً من وضع روابط الصور أو سلاسل Base64 مباشرة في النص العادي. يتم قبول كتل أصلية أخرى، مثل tool_use و tool_result و thinking و document للنماذج التي تدعمها.

أمثلة على كتل المحتوى:

  • كتلة نصية: { "type": "text", "text": "صف هذه الصورة" }
  • كتلة صورة عبر رابط: { "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } }
  • كتلة صورة عبر Base64: { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
max_tokensintegerمطلوب

الحد الأقصى للرموز (tokens) المراد إنشاؤها. مطلوب: لا يضيف TokenLab قيمة افتراضية. يعتمد الحد الأقصى القابل للاستخدام على النموذج؛ راجع max_output_tokens في تفاصيل النموذج. تؤدي القيمة الكبيرة إلى زيادة المبلغ الذي يحتجزه TokenLab من رصيدك أثناء تشغيل الطلب، وإذا كان الرصيد لا يغطي هذا الاحتجاز، فسيتم إرجاع 402.

systemstring | array

موجه النظام (system prompt) كسلسلة نصية أو مصفوفة من كتل المحتوى النصي، منفصلة عن مصفوفة messages.

temperaturenumber

درجة حرارة أخذ العينات (sampling temperature). يعتمد الدعم والقيم المسموح بها والقيمة الافتراضية على النموذج المحدد؛ احذف هذا الحقل لاستخدام القيمة الافتراضية للنموذج.

streambooleanالافتراضي: false

إرجاع الاستجابة كتدفق (stream) من أحداث الخادم (server-sent events). راجع البث.

thinkingobject

تكوين التفكير الأصلي، على سبيل المثال {"type":"enabled","budget_tokens":10000}. تعتمد الأنماط المدعومة والميزانيات والتركيبات مع المعلمات الأخرى على النموذج المحدد. بالنسبة للنموذج المعروف برفض ميزانية يدوية، يقوم TokenLab بتشغيل {"type":"enabled"} كتفكير تكيفي ويتجاهل budget_tokens.

toolsarray

الأدوات المتاحة للنموذج. يعتمد الدعم على النموذج المحدد.

tool_choiceobject

كائن اختيار الأداة الأصلي، على سبيل المثال {"type":"auto"}. تعتمد الأنواع المدعومة على النموذج المحدد.

cache_controlobject

علامة التخزين المؤقت للموجه (prompt-caching)، على سبيل المثال {"type":"ephemeral"}; أضف "ttl": "1h" لتخزين مؤقت لمدة ساعة واحدة. على المستوى الأعلى، يقوم هذا بتفعيل التخزين المؤقت التلقائي. يمكنك أيضاً ضبطه على كتل system والأدوات وكتل المحتوى. يعتمد الدعم على النموذج؛ النماذج التي تدعمه تدرج prompt-cache في capabilities.

top_pnumber

معلمة أخذ عينات النواة (Nucleus sampling). استخدم إما temperature أو top_p، وليس كلاهما. يعتمد الدعم على النموذج المحدد.

top_kinteger

أخذ عينات فقط من أفضل K خيار لكل رمز. يعتمد الدعم على النموذج المحدد.

stop_sequencesarray

تسلسلات إيقاف مخصصة ستتسبب في توقف النموذج عن الإنشاء. حتى 8,191 إدخالاً.

metadataobject

بيانات تعريف الطلب بتنسيق Anthropic. user_id هو معرف مبهم للمستخدم النهائي الخاص بك.

service_tierstring

فقط auto و standard_only لهما تأثير. يقوم TokenLab بتسعير المستوى القياسي فقط ويتجاهل أي قيمة أخرى.

الاستجابة (Response)

idstring

معرف الرسالة الفريد.

typestring

دائماً message.

rolestring

دائماً assistant.

contentarray

مصفوفة من كتل المحتوى، مثل text أو thinking أو tool_use.

modelstring

النموذج الذي أنتج الاستجابة.

stop_reasonstring

سبب توقف الإنشاء، مثل end_turn أو max_tokens أو stop_sequence أو tool_use. يمكن للنموذج إرجاع قيم أخرى، على سبيل المثال refusal.

stop_sequencestring | null

تسلسل الإيقاف الذي أنهى الإنشاء، أو null.

usageobject

استخدام الرموز مع input_tokens و output_tokens. عندما يبلغ النموذج عن رموز التخزين المؤقت للموجه، يحتوي usage أيضاً على cache_creation_input_tokens و cache_read_input_tokens.

تحمل كل استجابة معرف الطلب في ترويسات request-id و X-Request-ID. قم بذكره عند التواصل مع الدعم.

الطلب

curl -X POST "https://api.tokenlab.sh/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

الاستجابة

Response
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 10
  }
}

مثال على مدخلات الرؤية (Vision Input)

بالنسبة لنماذج Claude التي تدعم الرؤية، ضع الصور داخل messages[].content ككتل صور مهيكلة.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}
{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

مثال على التفكير الموسع (Extended Thinking)

استخدم نموذجاً يتمتع بقدرة reasoning. اضبط max_tokens و budget_tokens وفقاً لحدود النموذج؛ بعض النماذج تحتاج إلى تكوين تفكير مختلف.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this math problem..."}]
)

for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

البث (Streaming)

اضبط "stream": true لاستقبال أحداث الخادم من Anthropic: message_start و content_block_start و content_block_delta و content_block_stop و message_delta و message_stop. يصل استخدام الرموز في message_start و message_delta.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
  • أثناء عمل النموذج، يمكن أن يحمل البث أسطر تعليقات SSE مثل : keep-alive. تتجاهلها الـ SDKs.
  • يمكن أن تكون حالة HTTP 200 بالفعل عند حدوث فشل. يصل الفشل بعد بدء البث كحدث event: error مع نفس جسم الخطأ الموضح أدناه.

الأخطاء (Errors)

تستخدم الأخطاء تنسيق خطأ Anthropic. request_id هو معرف طلب TokenLab. تضيف بعض الأخطاء حقولاً مثل code و hint.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
  },
  "request_id": "req_01JEXAMPLE"
}
الحالةerror.typeالسبب المعتاد
400invalid_request_errorحقل مفقود أو غير صالح، أو نموذج غير معروف، أو نموذج لا يقبل تنسيق Messages
401authentication_errorمفتاح API مفقود أو غير صالح
402billing_errorالرصيد لا يغطي الطلب (error.code هو insufficient_balance). يحصل مفتاح API الذي وصل إلى حد الإنفاق الخاص به أيضاً على 402، مع error.code quota_exceeded و error.type rate_limit_error
403permission_errorلا يمكن لمفتاح API استخدام النموذج المطلوب، أو أن الحساب معلق أو مقيد
409conflict_errorإعادة محاولة باستخدام نفس Idempotency-Key. راجع إعادة المحاولة بأمان باستخدام مفتاح التكرار
413request_too_largeمدخلات الطلب كبيرة جداً
429rate_limit_errorالكثير من الطلبات
500, 502, 503api_error أو overloaded_errorتعذر إكمال الطلب، أو لا يوجد مسار متاح له الآن. أعد المحاولة لاحقاً
504timeout_errorانتهت مهلة الطلب

الواجهات ذات الصلة

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

مفتاح اختياري يمنع تشغيل الطلب نفسه مرة ثانية. أرسل قيمة فريدة جديدة، مثل UUID، لكل طلب، واحتفظ بها لعمليات إعادة المحاولة بعد انتهاء المهلة. إعادة المحاولة باستخدام نفس المفتاح لا تؤدي إلى تشغيل الطلب مجدداً: بل تُرجع 409 مع idempotency_replay_unavailable، أو عادةً idempotency_conflict عند تغيير نص الطلب. استثناء: عندما تكتمل نتيجة غير streaming بعد قطع اتصال العميل، فإن إعادة المحاولة بنفس المفتاح ونص الطلب خلال 24 ساعة تُرجع تلك النتيجة (بحد أقصى 1 ميجابايت) مع الترويسة Idempotent-Replayed: true دون احتساب تكلفة إضافية. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.

الطول1 <= length <= 255

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json