النص
إنشاء رسالة
إنشاء رسالة باستخدام تنسيق Anthropic Messages API
نظرة عامة
يقبل هذا الـ 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)
مفتاح API الخاص بـ TokenLab. أرسل إما x-api-key أو Authorization: Bearer <API_KEY>. إذا أرسلت كليهما بقيم مختلفة، فسيستخدم TokenLab قيمة x-api-key.
إصدار Anthropic API. تقوم Anthropic SDKs بإرساله نيابة عنك؛ استخدم 2023-06-01 عند استدعاء الـ API مباشرة.
أسماء ميزات Anthropic التجريبية (beta)، مفصولة بفواصل. يقوم TokenLab بتمرير الترويسة، ويعتمد عمل الميزة التجريبية على النموذج. المحتوى الذي يشير إلى file_id يحتاج إلى files-api-2025-04-14.
جسم الطلب (Request Body)
تعتمد المعلمات الاختيارية المدعومة والقيم المقبولة والقيم الافتراضية على النموذج المحدد. تحقق من تفاصيل النموذج قبل ضبط خيارات أخذ العينات (sampling) أو التفكير (reasoning) أو الأدوات (tool).
معرف النموذج الذي يدعم تنسيق anthropic_messages. تحقق من تفاصيل النموذج لمعرفة الإمكانيات الحالية.
مصفوفة من كائنات الرسائل مع 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..." } }
الحد الأقصى للرموز (tokens) المراد إنشاؤها. مطلوب: لا يضيف TokenLab قيمة افتراضية. يعتمد الحد الأقصى القابل للاستخدام على النموذج؛ راجع max_output_tokens في تفاصيل النموذج. تؤدي القيمة الكبيرة إلى زيادة المبلغ الذي يحتجزه TokenLab من رصيدك أثناء تشغيل الطلب، وإذا كان الرصيد لا يغطي هذا الاحتجاز، فسيتم إرجاع 402.
موجه النظام (system prompt) كسلسلة نصية أو مصفوفة من كتل المحتوى النصي، منفصلة عن مصفوفة messages.
درجة حرارة أخذ العينات (sampling temperature). يعتمد الدعم والقيم المسموح بها والقيمة الافتراضية على النموذج المحدد؛ احذف هذا الحقل لاستخدام القيمة الافتراضية للنموذج.
falseإرجاع الاستجابة كتدفق (stream) من أحداث الخادم (server-sent events). راجع البث.
تكوين التفكير الأصلي، على سبيل المثال {"type":"enabled","budget_tokens":10000}. تعتمد الأنماط المدعومة والميزانيات والتركيبات مع المعلمات الأخرى على النموذج المحدد. بالنسبة للنموذج المعروف برفض ميزانية يدوية، يقوم TokenLab بتشغيل {"type":"enabled"} كتفكير تكيفي ويتجاهل budget_tokens.
الأدوات المتاحة للنموذج. يعتمد الدعم على النموذج المحدد.
كائن اختيار الأداة الأصلي، على سبيل المثال {"type":"auto"}. تعتمد الأنواع المدعومة على النموذج المحدد.
علامة التخزين المؤقت للموجه (prompt-caching)، على سبيل المثال {"type":"ephemeral"}; أضف "ttl": "1h" لتخزين مؤقت لمدة ساعة واحدة. على المستوى الأعلى، يقوم هذا بتفعيل التخزين المؤقت التلقائي. يمكنك أيضاً ضبطه على كتل system والأدوات وكتل المحتوى. يعتمد الدعم على النموذج؛ النماذج التي تدعمه تدرج prompt-cache في capabilities.
معلمة أخذ عينات النواة (Nucleus sampling). استخدم إما temperature أو top_p، وليس كلاهما. يعتمد الدعم على النموذج المحدد.
أخذ عينات فقط من أفضل K خيار لكل رمز. يعتمد الدعم على النموذج المحدد.
تسلسلات إيقاف مخصصة ستتسبب في توقف النموذج عن الإنشاء. حتى 8,191 إدخالاً.
بيانات تعريف الطلب بتنسيق Anthropic. user_id هو معرف مبهم للمستخدم النهائي الخاص بك.
فقط auto و standard_only لهما تأثير. يقوم TokenLab بتسعير المستوى القياسي فقط ويتجاهل أي قيمة أخرى.
الاستجابة (Response)
معرف الرسالة الفريد.
دائماً message.
دائماً assistant.
مصفوفة من كتل المحتوى، مثل text أو thinking أو tool_use.
النموذج الذي أنتج الاستجابة.
سبب توقف الإنشاء، مثل end_turn أو max_tokens أو stop_sequence أو tool_use. يمكن للنموذج إرجاع قيم أخرى، على سبيل المثال refusal.
تسلسل الإيقاف الذي أنهى الإنشاء، أو null.
استخدام الرموز مع 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!"}
]
}'الاستجابة
{
"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 | السبب المعتاد |
|---|---|---|
| 400 | invalid_request_error | حقل مفقود أو غير صالح، أو نموذج غير معروف، أو نموذج لا يقبل تنسيق Messages |
| 401 | authentication_error | مفتاح API مفقود أو غير صالح |
| 402 | billing_error | الرصيد لا يغطي الطلب (error.code هو insufficient_balance). يحصل مفتاح API الذي وصل إلى حد الإنفاق الخاص به أيضاً على 402، مع error.code quota_exceeded و error.type rate_limit_error |
| 403 | permission_error | لا يمكن لمفتاح API استخدام النموذج المطلوب، أو أن الحساب معلق أو مقيد |
| 409 | conflict_error | إعادة محاولة باستخدام نفس Idempotency-Key. راجع إعادة المحاولة بأمان باستخدام مفتاح التكرار |
| 413 | request_too_large | مدخلات الطلب كبيرة جداً |
| 429 | rate_limit_error | الكثير من الطلبات |
| 500, 502, 503 | api_error أو overloaded_error | تعذر إكمال الطلب، أو لا يوجد مسار متاح له الآن. أعد المحاولة لاحقاً |
| 504 | timeout_error | انتهت مهلة الطلب |
الواجهات ذات الصلة
- حساب رموز الرسالة: تقدير رموز الإدخال لطلب ما قبل إرساله.
- تقوم دفعات الرسائل (Message Batches) بتشغيل العديد من طلبات الرسائل بشكل غير متزامن: إنشاء، سرد، استرجاع، إلغاء، الحصول على النتائج، و حذف.
التفويض
BearerAuth مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
الترويسات
سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.
القيم المتاحة
- "auto"
- "verified"
- "official"
مفتاح اختياري يمنع تشغيل الطلب نفسه مرة ثانية. أرسل قيمة فريدة جديدة، مثل 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