diff --git a/ar/guides/claude/claude_messages.mdx b/ar/guides/claude/claude_messages.mdx index dd0b8601..084d8fb5 100644 --- a/ar/guides/claude/claude_messages.mdx +++ b/ar/guides/claude/claude_messages.mdx @@ -1,44 +1,43 @@ --- -title: "التقديم واستخدام واجهة Claude Messages API" +title: "طلب واستخدام Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -يُعد Anthropic Claude نظام محادثة بالذكاء الاصطناعي قويًا للغاية، فما عليك سوى إدخال نص توجيهي ليُنشئ ردودًا سلسة وطبيعية في غضون ثوانٍ قليلة. تُعد Claude Messages API صيغة API أصلية رسمية من Anthropic، وتختلف عن الصيغة المتوافقة مع OpenAI (Chat Completion)، إذ تستخدم بنية طلبات واستجابات خاصة بـ Anthropic، مما يتيح الاستفادة بشكل أفضل من قدرات Claude الفريدة، مثل إدخال المحتوى متعدد الوسائط، واستدعاء الأدوات، والتفكير العميق (Extended Thinking) وغيرها من الميزات المتقدمة. +Anthropic Claude هو نظام محادثة بالذكاء الاصطناعي قوي للغاية، فما عليك سوى إدخال نص توجيهي ليُنشئ ردودًا سلسة وطبيعية في غضون ثوانٍ قليلة. Claude Messages API هو تنسيق API أصلي رسمي من Anthropic، ويختلف عن التنسيق المتوافق مع OpenAI (Chat Completion)، إذ يستخدم بنية الطلبات والاستجابات الخاصة بـ Anthropic، مما يتيح الاستفادة بصورة أفضل من قدرات Claude الفريدة، مثل إدخال المحتوى متعدد الوسائط، واستدعاء الأدوات، والتفكير العميق (Extended Thinking)، وغيرها من الميزات المتقدمة. -يقدم هذا المستند بشكل أساسي عملية استخدام عمليات Claude Messages API، وباستخدامها يمكننا استخدام واجهة أصلية متوافقة مع Anthropic الرسمية لاستدعاء وظائف محادثة Claude. +توضح هذه الوثيقة بشكل أساسي عملية استخدام عمليات Claude Messages API، وباستخدامها يمكننا استدعاء وظيفة المحادثة في Claude عبر واجهة أصلية متسقة مع Anthropic الرسمية. ## عملية التقديم -لاستخدام Claude Messages API، انتقل أولاً إلى [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. +لاستخدام Claude Messages API، انتقل أولًا إلى [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. ![](https://cdn.acedata.cloud/dvc3cg.jpg) إذا لم تكن قد سجلت الدخول أو أنشأت حسابًا بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية. -**يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة.** سيُمنحك رصيد مجاني عند أول تقديم، ويمكنك التجربة مجانًا؛ وعندما يكون الرصيد غير كافٍ، يمكنك شحن الرصيد العام من [وحدة التحكم](https://platform.acedata.cloud/console/coin). +**يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة.** سيمنحك أول تقديم رصيدًا مجانيًا لتجربة الخدمة مجانًا؛ وعندما يكون الرصيد غير كافٍ، يمكنك شحن الرصيد العام من [وحدة التحكم](https://platform.acedata.cloud/console/coin). > 📘 الوثائق الكاملة: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## الاستخدام الأساسي -مسار طلب Claude Messages API هو `/v1/messages`، وهو متوافق مع Anthropic API الرسمية. نحتاج على الأقل إلى توفير ثلاث معاملات مطلوبة: +مسار طلب Claude Messages API هو `/v1/messages`، وهو متوافق مع Anthropic API الرسمي. نحتاج إلى توفير ثلاثة معلمات إلزامية على الأقل: -- `model`: اختيار نموذج Claude المراد استخدامه. يتوفر `claude-opus-5-5` فقط عبر Messages API، ويدعم سياقًا من مليون Token، وحدًا أقصى للإخراج يبلغ 128K Token، ويفعّل دائمًا التفكير التكيفي. أحدث نموذج رائد هو `claude-fable-5-1` (سياق مليون Token، وحد أقصى للإخراج 128K Token)؛ ولا يزال `claude-fable-5` السابق محفوظًا للتوافق. انضم `claude-sonnet-5-5` إلى واجهات سلسلة Messages الأصلية، ويدعم إدخال الصور والتفكير التكيفي؛ وتبلغ الأسعار المرجعية الرسمية للإدخال والإخراج وقراءة التخزين المؤقت لكل مليون Token على التوالي 2 و10 و0.20 دولار أمريكي. +- `model`: اختر نموذج Claude المراد استخدامه. لا يتوفر `claude-opus-5-5` إلا عبر Messages API، ويدعم سياقًا من مليون Token، وحدًا أقصى للإخراج يبلغ 128K Token، ويُفعّل دائمًا التفكير التكيفي. أحدث نموذج رائد هو `claude-fable-5-1` (سياق مليون Token، وحد أقصى للإخراج يبلغ 128K Token)؛ ولا يزال `claude-fable-5` السابق محفوظًا للتوافق. انضم `claude-sonnet-5-5` إلى واجهة سلسلة Messages الأصلية، ويدعم إدخال الصور والتفكير التكيفي؛ وأسعار المراجع الرسمية للمدخلات والمخرجات وقراءة التخزين المؤقت هي 2 و10 و0.20 دولار لكل مليون Token على التوالي. - `messages`: مصفوفة الرسائل المُدخلة، تحتوي كل رسالة على `role` (الدور) و`content` (المحتوى)، حيث يدعم `role` كلاً من `user` و`assistant`. -- `max_tokens`: الحد الأقصى لعدد Token في الإخراج، ويُستخدم لتقييد طول الرد الواحد. +- `max_tokens`: الحد الأقصى لعدد token في الإخراج، ويُستخدم لتقييد طول الرد الواحد. -المعاملات الاختيارية الشائعة: +المعلمات الاختيارية الشائعة: -- `system`: نص التوجيه النظامي، يُستخدم لتحديد سلوك النموذج ودوره. -- `temperature`: عشوائية التوليد، بين 0 و1، وكلما زادت القيمة أصبحت الردود أكثر تشتتًا. -- `stream`: ما إذا كان سيتم استخدام استجابة متدفقة، ويمكن ضبطه على `true` لتحقيق تأثير الإرجاع حرفًا بحرف. -- `stop_sequences`: تسلسلات توقف مخصصة، سيتوقف النموذج عن التوليد عند مواجهة هذه النصوص. -- `top_p`: معامل أخذ العينات النووي، ويتعاون مع temperature للتحكم في عشوائية التوليد. -- `top_k`: أخذ العينات فقط من بين K خيارات ذات أعلى احتمالية. -- `tools`: تعريفات الأدوات، تُستخدم للسماح للنموذج باستدعاء وظائف خارجية. -- `tool_choice`: التحكم في كيفية استخدام النموذج للأدوات المُقدمة. -- `cache_control`: إنشاء نقطة توقف للتخزين المؤقت تلقائيًا عند آخر كتلة محتوى قابلة للتخزين المؤقت في الطلب؛ ويمكن أيضًا كتابته على كتلة محتوى محددة. -- `metadata`: كائن بيانات وصفية اختياري للطلب. `metadata.user_id` عبارة عن سلسلة نصية، ويمكن تمرير معرّف مستخدم مخصص من جهة المستدعي، مثل `{"user_id":"example-user-001"}`؛ ويُنصح باستخدام معرّف ثابت لا يحتوي على معلومات شخصية. وهو لا يحل محل مصادقة `Authorization`، ولا يحتاج إلى كتابته ضمن محتوى محادثة `messages`. +- `system`: نص التوجيه النظامي، يُستخدم لتعيين سلوك النموذج ودوره. +- `temperature`: عشوائية التوليد، بين 0 و1، وكلما زادت القيمة أصبح الرد أكثر تشتتًا. +- `stream`: ما إذا كان سيتم استخدام استجابة متدفقة، ويمكن بتعيينه إلى `true` تحقيق تأثير الإرجاع حرفًا بحرف. +- `stop_sequences`: تسلسلات إيقاف مخصصة، يتوقف النموذج عن التوليد عند مواجهة هذه النصوص. +- `top_p`: معلمة أخذ العينات النوية، وتتحكم مع temperature في عشوائية التوليد. +- `top_k`: أخذ العينات من بين أعلى K خيارات احتمالًا فقط. +- `tools`: تعريف الأدوات، يُستخدم للسماح للنموذج باستدعاء وظائف خارجية. +- `tool_choice`: التحكم في كيفية استخدام النموذج للأدوات المقدمة. +- `cache_control`: إنشاء نقطة توقف للتخزين المؤقت تلقائيًا عند آخر كتلة محتوى قابلة للتخزين المؤقت في الطلب؛ ويمكن أيضًا كتابتها على كتلة محتوى محددة. ### مثال cURL @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -86,7 +83,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -بعد الاستدعاء، تكون نتيجة الإرجاع كما يلي: +بعد الاستدعاء، تكون النتيجة المعادة كما يلي: ```json { @@ -109,25 +106,25 @@ print(response.json()) } ``` -شرح حقول نتيجة الإرجاع: -- `id`：المعرّف الفريد لهذه الرسالة. -- `type`：دائمًا `message`. -- `role`：دائمًا `assistant`. -- `content`：مصفوفة محتوى الرد، يحتوي كل عنصر على `type` (مثل `text`) والمحتوى المقابل. -- `model`：اسم النموذج الذي يعالج الطلب. -- `stop_reason`：سبب التوقف. تشمل القيم المستقرة `end_turn`، و`max_tokens`، و`stop_sequence`، و`tool_use`، و`pause_turn` (يمكن إعادة محتوى assistant الحالي كما هو للمتابعة)، و`refusal`، و`model_context_window_exceeded`. -- `stop_sequence`：إذا توقف بسبب تسلسل توقف مخصص، يعرض نص تسلسل التوقف المطابق. -- `stop_details`：عندما يكون `stop_reason` هو `refusal`، قد يتضمن فئة الرفض ووصفًا. -- `usage`：إحصاءات استخدام الـ token. `input_tokens` هي المدخلات غير المخزنة مؤقتًا؛ و`cache_creation_input_tokens` و`cache_read_input_tokens` هما كتابة وقراءة ذاكرة التخزين المؤقت على التوالي؛ و`output_tokens` هو إجمالي عدد رموز الإخراج. إذا تم إرجاع `output_tokens_details.thinking_tokens`، فإن هذه القيمة جزء من `output_tokens`، ولا تُضف مرة أخرى عند حساب الإجمالي أو التكلفة. قد تكون هذه التفاصيل `null` أو محذوفة عندما لا يكون هناك عدّ موثوق. -- `usage.cache_creation`：تفاصيل اختيارية لمهلة صلاحية كتابة ذاكرة التخزين المؤقت، تتضمن `ephemeral_5m_input_tokens` و`ephemeral_1h_input_tokens`. عند وجود الكائن، يساوي مجموع العنصرين `cache_creation_input_tokens`؛ وتعني الحقول التي تكون `null` أو محذوفة أنه لا يوجد تقسيم متاح لمهلة الصلاحية في الاستجابة الحالية، ولا يمكن تفسيرها على أنها `0`. -- `usage.cost`：قد تتضمن الاستجابات غير المتدفقة كائن استهلاك الرصيد المسجل بواسطة Ace Data Cloud، حيث تمثل `amount` الاستهلاك الفعلي لهذه المرة، و`currency` وحدة القياس، و`list_amount` المبلغ قبل الخصم (إن وجد). يبلغ السعر الأساسي الرسمي لقراءة ذاكرة التخزين المؤقت في Fable 5.1 مقدار $0.25/مليون Token، بينما تبلغ الأسعار الأساسية لكتابة ذاكرة التخزين المؤقت لمدة 5 دقائق وساعة واحدة $12.50 و$20/مليون Token على التوالي؛ وتُحوَّل الأسعار الفعلية للمنصة وفقًا لخصومات الباقة. +شرح حقول النتيجة المعادة: -## موجه النظام +- `id`: المعرّف الفريد لهذه الرسالة. +- `type`: يكون دائمًا `message`. +- `role`: يكون دائمًا `assistant`. +- `content`: مصفوفة محتوى الرد، يحتوي كل عنصر على `type` (مثل `text`) والمحتوى المقابل. +- `model`: اسم النموذج الذي يعالج الطلب. +- `stop_reason`: سبب التوقف. تشمل القيم المستقرة `end_turn` و`max_tokens` و`stop_sequence` و`tool_use` و`pause_turn` (يمكن إرجاع محتوى assistant الحالي كما هو للمتابعة) و`refusal` و`model_context_window_exceeded`. +- `stop_sequence`: إذا توقف بسبب تسلسل إيقاف مخصص، يعرض نص تسلسل الإيقاف المطابق. +- `stop_details`: عندما يكون `stop_reason` هو `refusal`، قد يتضمن فئة الرفض ووصفًا. +- `usage`: إحصائيات استخدام token. يمثل `input_tokens` المدخلات غير المخزنة مؤقتًا؛ ويمثل `cache_creation_input_tokens` و`cache_read_input_tokens` الكتابة إلى التخزين المؤقت والقراءة منه على التوالي؛ ويمثل `output_tokens` إجمالي عدد token في الإخراج. إذا أُعيد `output_tokens_details.thinking_tokens`، فهذه القيمة مجموعة فرعية من `output_tokens`، ولا تُضف مرة أخرى عند حساب الإجمالي أو التكلفة. قد تكون هذه التفاصيل `null` أو يتم حذفها عند عدم وجود عدّ موثوق. +- `usage.cache_creation`: تفاصيل اختيارية لمدة TTL للكتابة إلى التخزين المؤقت، تشمل `ephemeral_5m_input_tokens` و`ephemeral_1h_input_tokens`. عند وجود الكائن، يساوي مجموع القيمتين `cache_creation_input_tokens`؛ ويعني كون الحقل `null` أو محذوفًا عدم وجود تفصيل TTL متاح في الاستجابة الحالية، ولا يمكن تفسيره على أنه `0`. +- `usage.cost`: قد تتضمن الاستجابات غير المتدفقة كائن استهلاك الرصيد المسجل من Ace Data Cloud، حيث يمثل `amount` الاستهلاك الفعلي لهذه المرة، ويمثل `currency` وحدة القياس، ويمثل `list_amount` المبلغ قبل الخصم (إن وجد). سعر قراءة التخزين المؤقت الرسمي الأساسي لـ Fable 5.1 هو $0.25/مليون Token، وأسعار الكتابة إلى التخزين المؤقت الأساسية لمدة 5 دقائق وساعة واحدة هي $12.50 و$20/مليون Token على التوالي؛ ويُحتسب السعر الفعلي للمنصة وفق خصم الباقة. -تدعم Claude Messages API تعيين موجه النظام عبر الحقل `system`، ويُستخدم لتعريف سلوك النموذج ودوره وسياقه. +## نص التوجيه النظامي -### مثال Python +يدعم Claude Messages API تعيين نص التوجيه النظامي عبر حقل `system`، ويُستخدم لتعريف سلوك النموذج ودوره وسياقه. +### مثال Python ```python import requests @@ -152,11 +149,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -من خلال تعيين موجه `system`، يمكن التحكم بدقة في دور Claude وطريقة سلوكه. +من خلال تعيين موجّه `system`، يمكن التحكم بدقة في دور Claude وسلوكه. ## الاستجابة المتدفقة -تدعم هذه الواجهة أيضًا الاستجابة المتدفقة؛ اضبط المعلمة `stream` على `true` للحصول على تأثير الإرجاع التدريجي، وهو مناسب جدًا لتنفيذ العرض حرفًا بحرف في صفحات الويب. +تدعم هذه الواجهة أيضًا الاستجابة المتدفقة؛ ما عليك سوى تعيين المعلمة `stream` إلى `true` للحصول على تأثير الإرجاع التدريجي، وهو مناسب جدًا لتنفيذ العرض حرفًا بحرف في صفحات الويب. ### مثال Python @@ -186,14 +183,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -تُرجع الاستجابة المتدفقة بتنسيق Server-Sent Events (SSE)، ويبدأ كل سطر بـ `event:` و`data:`. تشمل أنواع الأحداث المتدفقة: +تُرجع الاستجابة المتدفقة بتنسيق Server-Sent Events ‏(SSE)، حيث يبدأ كل سطر بالبادئتين `event:` و`data:`. وتشمل أنواع الأحداث المتدفقة: -- `message_start`：بداية الرسالة، تتضمن المعلومات الأساسية للرسالة واسم النموذج. -- `content_block_start`：بداية كتلة المحتوى. -- `content_block_delta`：تحديث تدريجي لكتلة المحتوى، يتضمن مقطع النص المُنشأ حديثًا. -- `content_block_stop`：نهاية كتلة المحتوى. -- `message_delta`：تحديث تدريجي على مستوى الرسالة، يتضمن `stop_reason` ومعلومات `usage` النهائية. يجب قراءة القيمة الموثوقة لـ `output_tokens_details.thinking_tokens` من آخر `message_delta.usage` فقط، ولا تجمعها عبر الأحداث. -- `message_stop`：نهاية الرسالة. +- `message_start`: بداية الرسالة، وتتضمن المعلومات الأساسية للرسالة واسم النموذج. +- `content_block_start`: بداية كتلة المحتوى. +- `content_block_delta`: تحديث تزايدي لكتلة المحتوى، ويتضمن جزء النص المُنشأ حديثًا. +- `content_block_stop`: نهاية كتلة المحتوى. +- `message_delta`: تحديث تزايدي على مستوى الرسالة، ويتضمن `stop_reason` ومعلومات `usage` النهائية. يجب قراءة القيمة الموثوقة لـ `output_tokens_details.thinking_tokens` من آخر `message_delta.usage` فقط، ولا تجمعها عبر الأحداث. +- `message_stop`: نهاية الرسالة. يكون تأثير الإخراج كما يلي: @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -يمكن ملاحظة أن حدث `content_block_delta` في الاستجابة المتدفقة يتضمن محتوى النص المُنشأ تدريجيًا، ويمكن الحصول على الرد الكامل من خلال دمج جميع `text_delta`. +يمكن ملاحظة أن حدث `content_block_delta` في الاستجابة المتدفقة يتضمن محتوى النص المُنشأ تدريجيًا، ويمكن الحصول على الرد الكامل عبر دمج جميع `text_delta`. ### مثال JavaScript @@ -254,9 +251,9 @@ while (true) { } ``` -## المحادثات متعددة الجولات +## محادثات متعددة الجولات -إذا كنت ترغب في دمج وظيفة المحادثات متعددة الجولات، فيجب ترتيب رسائل الأدوار `user` و`assistant` بالتناوب في مصفوفة `messages`، وتمرير سجل المحادثة السابق معًا. +إذا كنت ترغب في ربط وظيفة المحادثات متعددة الجولات، فيجب ترتيب رسائل دورَي `user` و`assistant` بالتناوب في مصفوفة `messages`، وتمرير سجل المحادثة السابق بالكامل معها. ### مثال Python @@ -286,6 +283,7 @@ print(response.json()) ``` تكون نتيجة الإرجاع كما يلي: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ print(response.json()) } ``` -من خلال تمرير سجل المحادثة الكامل في `messages`، يمكن لـ Claude تقديم إجابات دقيقة بالاستناد إلى السياق. +من خلال تمرير سجل المحادثة الكامل في `messages`، يستطيع Claude تقديم إجابات دقيقة بالاستناد إلى السياق. -## نماذج التفكير العميق +## نموذج التفكير العميق -إن thinking و thinking summary في Claude مفهومان مختلفان: يمكن للنموذج إجراء استدلال داخلي، لكن API لا يعيد سلسلة التفكير الأصلية. عند الحاجة إلى عرض عملية الاستدلال، فإن ما يعيده API هو ملخص مُعالَج. +إن thinking وthinking summary لدى Claude مفهومان مختلفان: يمكن للنموذج إجراء استدلال داخلي، لكن واجهة API لن تُرجع سلسلة التفكير الأصلية. عند الحاجة إلى عرض عملية الاستدلال، فإن ما تُرجعه API هو ملخص مُعالَج. -يوصى للنماذج الحالية باستخدام adaptive thinking، والتحكم في إجمالي جهد الاستدلال عبر `output_config.effort`: +يوصى حاليًا باستخدام adaptive thinking، والتحكم في إجمالي جهد الاستدلال عبر `output_config.effort`: ```python import requests @@ -343,7 +341,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -يكون شكل كتلة thinking في الاستجابة كما يلي: +تكون كتلة thinking في الاستجابة بالشكل التالي: ```json { @@ -352,25 +350,24 @@ print(response.json()) "signature": "opaque-signature" } ``` +- `display: "summarized"` يعيد ملخصًا مقروءًا للتفكير؛ وهو ليس سلسلة التفكير الأصلية. +- `display: "omitted"` يعيد `thinking: ""`، لكنه يحتفظ بـ `opaque signature` لدعم المحادثات اللاحقة. +- `display: "updates"` هو وضع Anthropic التجريبي (beta)، ويتطلب إرفاق `anthropic-beta: thinking-display-updates-2026-08-18`. التعريف الرسمي هو إخفاء نص الاستدلال وعرض تحديثات تقدم قصيرة بين استدعاءات الأدوات. تقوم المنصة بتمرير هذا المعامل ورأس beta كما هو، ولن تجبره على التحويل إلى `summarized`؛ ويعتمد المحتوى الناتج الفعلي على دعم النموذج المحدد. +- يتم تمرير `thinking` و`output_config` وeffort ومعاملات أخذ العينات والحقول الإضافية الجديدة كما هي. لا تحافظ المنصة على تعداد قيم أو قيود تركيبية مشفرة مسبقًا حسب النموذج، ولا تقوم تلقائيًا بتعديل أوضاع thinking؛ وما إذا كانت هذه المعاملات مقبولة يتم تحديده بواسطة النموذج المحدد، وسيتم إرجاع أخطاء المعاملات التي يعيدها النموذج إلى العميل. +- القيمة الافتراضية لـ display في Fable 5.1 وFable 5 وOpus 5 وSonnet 5 وOpus 4.8 وOpus 4.7 هي `omitted`؛ أما Opus 4.6 وSonnet 4.6 والنماذج الأقدم التي تدعم thinking فتستخدم افتراضيًا `summarized`. +- يؤثر Display فقط على المحتوى المعاد وزمن الاستجابة في البث، ولا يعطل الاستدلال ولا يقلل من تكلفة رموز thinking. +- ما إذا كان thinking مفعّلًا افتراضيًا وقيمة display الافتراضية هما مسألتان مستقلتان. يقوم Opus 5 وSonnet 5 بتمكين adaptive thinking افتراضيًا؛ بالنسبة إلى Opus 5، فإن حذف `thinking` يعادل adaptive، وحذف `output_config.effort` يعادل `high`. أما Opus 4.8 و4.7 و4.6 فتحتاج إلى تفعيل صريح. +- يشترك التفكير والنص النهائي معًا في ميزانية إخراج `max_tokens`. عندما تكون الميزانية صغيرة جدًا، قد يستهلك thinking معظم الحصة، مما يجعل النص الأساسي فارغًا أو يتم اقتطاعه؛ يرجى زيادة `max_tokens`، أو استخدام `low` / `medium` effort للتحكم في استثمار الاستدلال. +- بالنسبة للنماذج التي تسمح بإيقاف thinking، يمكن تمرير `thinking: {"type":"disabled"}`. تعتمد الأوضاع الجديدة مثل `between_tools` وتركيبات effort على النموذج المحدد؛ ولا تقوم المنصة بالرفض المسبق بناءً على قواعد النماذج القديمة. +- يمكن تمرير ميزانية التفكير الثابتة عبر `budget_tokens`؛ وعادةً ما تستخدم النماذج الجديدة `thinking.type=adaptive` و`output_config.effort`. يعتمد دعم الميزانية الثابتة أو إيقاف التفكير على القدرات الحالية للنموذج المحدد. +- في المحادثات متعددة الجولات واستدعاءات الأدوات، يجب إعادة تمرير كتلة thinking الكاملة التي يعيدها assistant بالإضافة إلى signature كما هي؛ لا تقم بتعديل أو إنشاء signature بشكل ذاتي. +- تمرير المعاملات كما هي لا يعني أن كل نموذج يدعم جميع الوظائف. لا تزال الاستدعاءات عبر البروتوكولات المختلفة تحتاج إلى تحويل، كما أن نطاق دعم `redacted_thinking` والأخطاء يتم تحديده بواسطة خدمة النموذج التي تعالج الطلب فعليًا. -- يعيد `display: "summarized"` ملخص تفكير قابلًا للقراءة؛ وهو ليس سلسلة التفكير الأصلية. -- يعيد `display: "omitted"` القيمة `thinking: ""`، لكنه يحتفظ بـ `signature` معتم لدعم المحادثات اللاحقة. -- `display: "updates"` هو وضع beta من Anthropic، ويتطلب تضمين `anthropic-beta: thinking-display-updates-2026-08-18`. التعريف الرسمي هو إخفاء نص الاستدلال وعرض تحديثات تقدم قصيرة بين استدعاءات الأدوات. تمرر المنصة هذه المعلمة وترويسة طلب beta بقيمتهما الأصلية، ولن تفرض إعادة كتابتهما إلى `summarized`؛ ويعتمد المحتوى الفعلي للمخرجات على دعم النموذج المختار. -- يتم تمرير `thinking` و`output_config` وeffort ومعلمات أخذ العينات وحقول الامتداد الجديدة بقيمها الأصلية. لا تحتفظ المنصة بتعدادات قيم مضمّنة في الشيفرة حسب النموذج أو قيود على التركيبات، ولا تعيد كتابة وضع thinking تلقائيًا؛ ويحدد النموذج المختار ما إذا كان يقبل هذه المعلمات، وتُعاد أخطاء المعلمات التي يعيدها النموذج إلى العميل. -- القيمة الافتراضية لـ display في Fable 5.1 وFable 5 وOpus 5 وSonnet 5 وOpus 4.8 وOpus 4.7 هي `omitted`؛ بينما تستخدم Opus 4.6 وSonnet 4.6 والنماذج الأقدم التي تدعم thinking القيمة الافتراضية `summarized`. -- يؤثر Display فقط في المحتوى المُعاد وتأخير البث، ولا يعطل الاستدلال ولا يقلل تكلفة رموز thinking. -- ما إذا كان thinking مفعّلًا افتراضيًا والقيمة الافتراضية لـ display مسألتان منفصلتان. يفعّل Opus 5 وSonnet 5 adaptive thinking افتراضيًا؛ وبالنسبة إلى Opus 5، فإن حذف `thinking` يعادل adaptive، وحذف `output_config.effort` يعادل `high`. وتتطلب Opus 4.8 و4.7 و4.6 تفعيلًا صريحًا. -- يشترك thinking والنص النهائي في ميزانية مخرجات `max_tokens`. عند انخفاض الميزانية كثيرًا، قد يستهلك thinking معظم الحصة، مما يجعل النص فارغًا أو مقتطعًا؛ يرجى زيادة `max_tokens`، أو استخدام effort بقيمة `low` / `medium` للتحكم في جهد الاستدلال. -- بالنسبة إلى النماذج التي تسمح بتعطيل thinking، يمكن تمرير `thinking: {"type":"disabled"}`. تعتمد الأوضاع الجديدة مثل `between_tools` وتركيبات effort على النموذج المختار؛ ولا ترفض المنصة مسبقًا بناءً على قواعد الطرازات القديمة. -- يمكن تمرير ميزانية تفكير ثابتة عبر `budget_tokens`؛ تستخدم النماذج الجديدة عادةً `thinking.type=adaptive` و`output_config.effort`. ويعتمد دعم الميزانية الثابتة أو تعطيل التفكير على الإمكانات الحالية للنموذج المختار. -- في المحادثات متعددة الجولات واستدعاءات الأدوات، يجب إعادة تمرير كتلة thinking الكاملة وsignature اللذين أعادهما assistant كما هما؛ لا تعدل signature ولا تنشئه بنفسك. -- لا يعني تمرير المعلمات أن كل نموذج يدعم جميع الميزات. لا تزال الاستدعاءات عبر البروتوكولات تتطلب التحويل، ويحدد نموذج الخدمة الذي يعالج الطلب فعليًا نطاق دعم محتوى مثل `redacted_thinking` والأخطاء المتعلقة به. - -في طلبات البث، ينتج `summarized` قيمة `thinking_delta`؛ ولا ينتج `omitted` قيمة `thinking_delta`، بل يحتفظ فقط بدورة حياة كتلة thinking و`signature_delta`. +في طلبات البث، ينتج `summarized` قيمة `thinking_delta`؛ بينما لا ينتج `omitted` قيمة `thinking_delta`، ويحتفظ فقط بدورة حياة كتلة thinking و`signature_delta`. -## نماذج الرؤية +## النماذج المرئية -يدعم Claude الإدخال متعدد الوسائط، ويمكنه معالجة النصوص والصور في الوقت نفسه. في Messages API، يمكن استخدام قدرات الرؤية عبر ضبط `content` على صيغة مصفوفة وتمرير كتلة محتوى صورة. +يدعم Claude الإدخالات متعددة الوسائط، ويمكنه معالجة النصوص والصور في الوقت نفسه. في Messages API، يمكن استخدام القدرات المرئية من خلال ضبط `content` على تنسيق مصفوفة وتمرير كتل محتوى الصور. ### استخدام صور بترميز Base64 @@ -386,7 +383,7 @@ headers = { "content-type": "application/json" } -# 读取并编码图片 +# قراءة الصورة وترميزها with open("image.png", "rb") as f: image_data = base64.standard_b64encode(f.read()).decode("utf-8") @@ -407,7 +404,7 @@ payload = { }, { "type": "text", - "text": "What's in this image?" + "text": "ما الموجود في هذه الصورة؟" } ] } @@ -418,7 +415,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### استخدام صور URL +### استخدام صور عبر URL ```python import requests @@ -447,7 +444,7 @@ payload = { }, { "type": "text", - "text": "What's in this image?" + "text": "ما الموجود في هذه الصورة؟" } ] } @@ -459,6 +456,7 @@ print(response.json()) ``` ### مثال cURL + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -488,11 +486,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -تشمل تنسيقات الصور المدعومة: `image/jpeg` و`image/png` و`image/gif` و`image/webp`. +تشمل تنسيقات الصور المدعومة: `image/jpeg`، `image/png`، `image/gif`، `image/webp`. ## المستندات وPDF -يستخدم PDF كتلة محتوى `document`، ويدعم مصدرين مستقرين هما Base64 وURL. يجب أن يستخدم مصدر Base64 `application/pdf`: +يستخدم PDF كتلة محتوى `document`، ويدعم مصدرين مستقرين هما Base64 وURL. يجب أن يستخدم مصدر Base64 نوع `application/pdf`: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -يُكتب مصدر URL بالشكل `{"type":"url","url":"https://example.com/report.pdf"}`. يدعم `document` أيضًا `text/plain` ومصدر `content` المكوّن من كتل text/image؛ وتشمل الحقول الاختيارية `title` و`context` و`citations`. مصدر `file_id` الخاص بـ Files API هو وظيفة beta مستقلة، وليس ضمن العقد المستقر لهذه الواجهة. +يُكتب مصدر URL بصيغة `{"type":"url","url":"https://example.com/report.pdf"}`. كما يدعم `document` مصادر `text/plain` و`content` المكوّنة من كتل text/image؛ وتشمل الحقول الاختيارية `title` و`context` و`citations`. مصدر `file_id` الخاص بـ Files API هو وظيفة beta مستقلة، ولا يدخل ضمن العقد المستقر لهذه الواجهة. -## التخزين المؤقت للمطالبات +## التخزين المؤقت للتلميحات -يضع `cache_control` على المستوى الأعلى نقطة توقف التخزين المؤقت تلقائيًا على آخر كتلة قابلة للتخزين المؤقت: +يقوم `cache_control` في المستوى الأعلى تلقائيًا بوضع نقطة التخزين المؤقت عند آخر كتلة قابلة للتخزين المؤقت: ```python payload = { @@ -536,12 +534,11 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +عند الحاجة إلى التحكم الدقيق في الموضع، يمكن أيضًا كتابة `cache_control` نفسه على كتل محتوى text وimage وdocument وtool_use وtool_result أو على تعريفات الأدوات. يدعم `ttl` القيمتين `5m` (الافتراضية) و`1h`؛ يرجى تحديد كتابة التخزين المؤقت وإصابته عبر `usage.cache_creation_input_tokens` و`usage.cache_read_input_tokens`. -عند الحاجة إلى تحكم دقيق في الموضع، يمكن أيضًا كتابة `cache_control` نفسه على كتل محتوى text وimage وdocument وtool_use وtool_result أو على تعريفات الأدوات. يدعم `ttl` القيمتين `5m` (الافتراضية) و`1h`؛ يُرجى تحديد كتابة التخزين المؤقت والإصابة به عبر `usage.cache_creation_input_tokens` و`usage.cache_read_input_tokens`. - -عندما توفر الاستجابة `usage.cache_creation`، فإن `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. إذا كانت `cache_creation` تساوي `null` أو تم حذفها، فهذا يعني وجود إجمالي كتابة التخزين المؤقت فقط، من دون تقسيم موثوق لـ TTL؛ في هذه الحالة، لا تعتبر أي bucket على أنها 0 معروفة، وتبقى الفوترة والإجمالي مستندين إلى الحقل aggregate. +عندما توفّر الاستجابة `usage.cache_creation`، فإن `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. إذا كانت `cache_creation` تساوي `null` أو تم حذفها، فهذا يعني أن هناك فقط إجمالي كتابة التخزين المؤقت، ولا يوجد تقسيم موثوق لـ TTL؛ في هذه الحالة لا تتعامل مع أي bucket على أنه 0 معروف، وتظل الفوترة والإجمالي معتمدين على حقل aggregate. -مثال على النتيجة المعادة: +مثال على النتيجة المُعادة: ```json { @@ -566,7 +563,7 @@ payload = { ## استدعاء الأدوات (Tool Use) -تدعم Claude Messages API أصلًا وظيفة استدعاء الأدوات، مما يسمح للنموذج باستدعاء الأدوات/الدوال التي عرّفتها مسبقًا عند الحاجة. +تدعم Claude Messages API أصليًا ميزة استدعاء الأدوات، مما يسمح للنموذج باستدعاء أدوات/دوال تقومون بتعريفها مسبقًا عند الحاجة. ### مثال Python @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -عندما يقرر النموذج استدعاء أداة، ستتضمن `content` في النتيجة المعادة كتلة محتوى من نوع `tool_use`: +عندما يقرر النموذج استدعاء أداة، سيحتوي `content` في النتيجة المُعادة على كتلة محتوى من نوع `tool_use`: ```json { @@ -640,7 +637,7 @@ print(response.json()) } ``` -لاحظ أن `stop_reason` هي `tool_use`، مما يشير إلى أن النموذج يحتاج إلى استدعاء الأداة. بعد تلقي هذه النتيجة، تحتاج إلى تنفيذ دالة الأداة وإعادة النتيجة إلى النموذج على هيئة `tool_result`: +لاحظ أن `stop_reason` هو `tool_use`، مما يشير إلى أن النموذج يحتاج إلى استدعاء الأداة. بعد استلام هذه النتيجة، تحتاجون إلى تنفيذ دالة الأداة وإعادة النتيجة إلى النموذج بصيغة `tool_result`: ```python payload = { @@ -688,36 +685,37 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -سينشئ النموذج، استنادًا إلى النتيجة التي تعيدها الأداة، ردًا نهائيًا باللغة الطبيعية. +سيولّد النموذج الرد النهائي باللغة الطبيعية بناءً على النتيجة التي تُعيدها الأداة. ## الفرق عن Chat Completion API -توفر Ace Data Cloud صيغتين من Claude API في الوقت نفسه، والفروقات الرئيسية بينهما كما يلي: +يوفّر Ace Data Cloud في الوقت نفسه تنسيقي Claude API، والفروقات الرئيسية بينهما كما يلي: -تمثل `usage.input_tokens` في Messages API المدخلات غير المخزنة مؤقتًا فقط، بينما يُعد `cache_read_input_tokens` و`cache_creation_input_tokens` قسمي فوترة مستقلين؛ وسيُحسب الثلاثة كلٌّ منها وفق السعر المقابل. -| الميزة | واجهة برمجة تطبيقات Messages (`/v1/messages`) | واجهة برمجة تطبيقات Chat Completion (`/v1/chat/completions`) | +يمثل `usage.input_tokens` في Messages API الإدخال غير المخزن مؤقتًا فقط، ويُعد `cache_read_input_tokens` و`cache_creation_input_tokens` فئات فوترة مستقلة؛ وتُحسب الثلاثة بشكل منفصل وفقًا للأسعار المقابلة. + +| الميزة | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | التنسيق | تنسيق Anthropic الأصلي | تنسيق متوافق مع OpenAI | -| موجه النظام | حقل `system` مستقل | يُمرَّر عبر `role: "system"` ضمن `messages` | +| مطالبة النظام | حقل `system` مستقل | يتم تمريرها عبر `role: "system"` في `messages` | | بنية الاستجابة | مصفوفة `content` (تدعم أنواعًا متعددة) | مصفوفة `choices` (تتضمن `message`) | | تنسيق البث | أحداث SSE (أنواع أحداث متعددة) | أسطر SSE `data` | | التفكير العميق | `thinking` الأصلي و`output_config.effort` | الاستراتيجية الافتراضية للنموذج والمعلمات المتوافقة | | استدعاء الأدوات | `tools` الأصلي + `input_schema` | تنسيق `tools` المتوافق مع OpenAI | | إحصاءات Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -إذا كان نظامك قد تكامل بالفعل مع واجهة برمجة تطبيقات بتنسيق OpenAI، فيمكنك استخدام واجهة برمجة تطبيقات Chat Completion للتبديل بسلاسة. إذا كنت بحاجة إلى استخدام جميع الإمكانات الأصلية لـ Claude، فيوصى باستخدام واجهة برمجة تطبيقات Messages. +إذا كان نظامكم قد تكامل بالفعل مع API بتنسيق OpenAI، فيمكنكم استخدام Chat Completion API للتبديل بسلاسة. إذا كنتم تحتاجون إلى استخدام جميع القدرات الأصلية لـ Claude، فيوصى باستخدام Messages API. ## معالجة الأخطاء -تستخدم استجابات الأخطاء للواجهات العامة envelope لمنصة Ace Data Cloud: يمثل `error.code` رمز خطأ ثابتًا، ويمثل `error.message` وصفًا، ويُستخدم `trace_id` لتتبّع الطلبات. تشمل حالات HTTP الشائعة ما يلي: +تستخدم استجابات الأخطاء للواجهة العامة envelope منصة Ace Data Cloud: `error.code` هو رمز خطأ ثابت، و`error.message` هو الوصف، ويُستخدم `trace_id` لتتبع الطلب. تتضمن حالات HTTP الشائعة ما يلي: - `400`: معلمات الطلب أو محتوى البروتوكول غير صالح. - `401`: رمز التفويض غير صالح أو مفقود أو منتهي الصلاحية. -- `403`: الوصول محظور، أو الرصيد غير كافٍ، أو الحصة مقيّدة. -- `404`: واجهة برمجة التطبيقات أو النموذج غير موجود. +- `403`: الوصول محظور أو الرصيد غير كافٍ أو الحصة مقيدة. +- `404`: API أو النموذج غير موجود. - `413`: جسم الطلب كبير جدًا. -- `429`: عدد كبير جدًا من الطلبات. -- `500` / `503` / `504`: خطأ في الخدمة، أو عدم توفر مؤقت، أو انتهاء مهلة المعالجة. +- `429`: طلبات كثيرة جدًا. +- `500` / `503` / `504`: خطأ في الخدمة، أو غير متاحة مؤقتًا، أو انتهت مهلة المعالجة. ### مثال على استجابة خطأ @@ -731,8 +729,7 @@ print(response.json()) } ``` -بنية الخطأ هذه هي عقد وقت التشغيل لـ Ace Data Cloud، ولا تعادل envelope الخطأ الرسمي لـ Anthropic؛ يُرجى التعامل معها وفقًا لحالة HTTP و`error.code`. +بنية الخطأ هذه هي عقد وقت التشغيل الخاص بـ Ace Data Cloud، وليست مساوية لـ envelope الخطأ الرسمي لـ Anthropic؛ يرجى التعامل معها وفقًا لحالة HTTP و`error.code`. ## الخلاصة - -من خلال هذا المستند، أصبحت تعرف كيفية استخدام واجهة برمجة تطبيقات Claude Messages لاستدعاء وظائف المحادثة في Claude بتنسيق Anthropic الأصلي. تدعم واجهة برمجة تطبيقات Messages ميزات غنية مثل المحادثة الأساسية، وموجهات النظام، والاستجابات المتدفقة، والمحادثات متعددة الجولات، والتفكير العميق، والفهم البصري، وPDF، والتخزين المؤقت للموجهات، واستدعاء الأدوات. إذا كانت لديك أي أسئلة، فيُرجى الاتصال بفريق الدعم الفني لدينا في أي وقت. +من خلال هذا المستند، تعرّفتَ بالفعل على كيفية استخدام Claude Messages API لاستدعاء قدرات المحادثة في Claude بتنسيق Anthropic الأصلي. يدعم Messages API وظائف غنية مثل المحادثات الأساسية، ومطالبات النظام، والاستجابات المتدفقة، والمحادثات متعددة الجولات، والتفكير العميق، والفهم البصري، وملفات PDF، والتخزين المؤقت للمطالبات، واستدعاء الأدوات. إذا كانت لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا. diff --git a/de/guides/claude/claude_messages.mdx b/de/guides/claude/claude_messages.mdx index 9450e50c..1795337d 100644 --- a/de/guides/claude/claude_messages.mdx +++ b/de/guides/claude/claude_messages.mdx @@ -3,42 +3,41 @@ title: "Beantragung und Nutzung der Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude ist ein sehr leistungsstarkes KI-Dialogsystem, das nach der Eingabe eines Prompt-Worts innerhalb weniger Sekunden flüssige und natürliche Antworten generieren kann. Die Claude Messages API ist das offizielle native API-Format von Anthropic. Anders als das mit OpenAI kompatible Format (Chat Completion) verwendet sie die eigene Anfrage- und Antwortstruktur von Anthropic und kann die einzigartigen Fähigkeiten von Claude besser nutzen, wie multimodale Inhaltseingaben, Tool-Aufrufe, Deep Thinking (Extended Thinking) und andere erweiterte Funktionen. +Anthropic Claude ist ein sehr leistungsstarkes KI-Dialogsystem, das durch die Eingabe eines Prompts in nur wenigen Sekunden flüssige und natürliche Antworten erzeugen kann. Die Claude Messages API ist das offizielle native API-Format von Anthropic. Anders als das mit OpenAI kompatible Format (Chat Completion) verwendet sie die eigene Anfrage- und Antwortstruktur von Anthropic und kann die einzigartigen Fähigkeiten von Claude besser nutzen, wie multimodale Inhaltseingaben, Tool-Aufrufe, Deep Thinking (Extended Thinking) und andere erweiterte Funktionen. -Dieses Dokument stellt hauptsächlich den Nutzungsablauf der Claude Messages API vor. Mit ihr können wir die Dialogfunktionen von Claude über eine native Schnittstelle aufrufen, die mit der offiziellen von Anthropic übereinstimmt. +Dieses Dokument stellt hauptsächlich den Nutzungsablauf der Claude Messages API vor. Damit können wir die Dialogfunktionen von Claude über eine native Schnittstelle aufrufen, die mit der offiziellen Schnittstelle von Anthropic übereinstimmt. ## Beantragungsprozess -Um die Claude Messages API zu verwenden, rufen Sie zunächst die [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) auf, um Ihr API-Token zu erhalten, und bewahren Sie es als Reserve auf. +Um die Claude Messages API zu verwenden, rufen Sie zunächst die [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) auf, um Ihren API-Token zu erhalten, und bewahren Sie ihn als Reserve auf. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück. +Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Danach kehren Sie automatisch zu dieser Seite zurück. -**Ein API-Token kann alle Plattformdienste aufrufen; es ist nicht erforderlich, jeden Dienst einzeln zu beantragen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben und können den Dienst kostenlos testen; bei unzureichendem Guthaben können Sie in der [Konsole](https://platform.acedata.cloud/console/coin) ein allgemeines Guthaben aufladen. +**Ein API-Token kann alle Dienste der Plattform aufrufen, ohne dass jeder Dienst einzeln beantragt werden muss.** Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben, das kostenlos ausprobiert werden kann; bei unzureichendem Guthaben können Sie in der [Konsole](https://platform.acedata.cloud/console/coin) ein allgemeines Guthaben aufladen. > 📘 Vollständige Dokumentation: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) -## Grundlegende Verwendung +## Grundlegende Nutzung -Der Anfragepfad der Claude Messages API lautet `/v1/messages` und stimmt mit der offiziellen API von Anthropic überein. Wir müssen mindestens drei Pflichtparameter bereitstellen: +Der Anfragepfad der Claude Messages API lautet `/v1/messages` und entspricht der offiziellen API von Anthropic. Wir müssen mindestens drei Pflichtparameter bereitstellen: -- `model`: Wählen Sie das zu verwendende Claude-Modell aus. `claude-opus-5-5` wird nur über die Messages API bereitgestellt, unterstützt 1 Million Token Kontext, maximal 128K Ausgabe-Token und aktiviert stets adaptives Denken. Das neueste Flaggschiff ist `claude-fable-5-1` (1 Million Token Kontext, maximal 128K Ausgabe-Token); das ursprüngliche `claude-fable-5` bleibt weiterhin kompatibel verfügbar. `claude-sonnet-5-5` wurde zur nativen Messages-Serienschnittstelle hinzugefügt und unterstützt Bildeingaben sowie adaptives Denken; die offiziellen Referenzpreise für Eingabe, Ausgabe und Cache-Lesen betragen jeweils 2, 10 und 0,20 US-Dollar pro Million Token. -- `messages`: Das Array der eingegebenen Nachrichten, wobei jede Nachricht `role` (Rolle) und `content` (Inhalt) enthält und `role` `user` und `assistant` unterstützt. -- `max_tokens`: Die maximale Anzahl der Ausgabe-Token, um die Länge einer einzelnen Antwort zu begrenzen. +- `model`: Wählt das zu verwendende Claude-Modell aus. `claude-opus-5-5` wird nur über die Messages API bereitgestellt, unterstützt 1 Million Token Kontext, maximal 128K Ausgabe-Token und aktiviert stets adaptives Denken. Das neueste Flaggschiff ist `claude-fable-5-1` (1 Million Token Kontext, maximal 128K Ausgabe-Token); das ursprüngliche `claude-fable-5` bleibt weiterhin kompatibel verfügbar. `claude-sonnet-5-5` wurde zur nativen Messages-Schnittstellenserie hinzugefügt und unterstützt Bildeingaben sowie adaptives Denken; die offiziellen Referenzpreise für Eingabe, Ausgabe und Cache-Lesen betragen jeweils 2, 10 und 0,20 US-Dollar pro Million Token. +- `messages`: Das Array der eingegebenen Nachrichten. Jede Nachricht enthält `role` (Rolle) und `content` (Inhalt), wobei `role` `user` und `assistant` unterstützt. +- `max_tokens`: Die maximale Anzahl an Ausgabe-Token, um die Länge einer einzelnen Antwort zu begrenzen. Häufig verwendete optionale Parameter: -- `system`: System-Prompt, der zum Festlegen des Verhaltens und der Rolle des Modells verwendet wird. -- `temperature`: Generierungszufälligkeit, zwischen 0 und 1; je größer der Wert, desto stärker streuen die Antworten. -- `stream`: Ob Streaming-Antworten verwendet werden; bei Einstellung auf `true` kann ein Effekt der zeichenweisen Rückgabe erzielt werden. +- `system`: System-Prompt, der verwendet wird, um das Verhalten und die Rolle des Modells festzulegen. +- `temperature`: Zufälligkeit der Generierung, zwischen 0 und 1; je größer der Wert, desto stärker streuen die Antworten. +- `stream`: Ob eine Streaming-Antwort verwendet wird; bei Einstellung auf `true` kann eine zeichenweise Rückgabe erzielt werden. - `stop_sequences`: Benutzerdefinierte Stoppsequenzen; das Modell beendet die Generierung, wenn es auf diese Texte trifft. -- `top_p`: Parameter für Nukleus-Sampling, der zusammen mit temperature die Zufälligkeit der Generierung steuert. -- `top_k`: Es wird nur aus den K Optionen mit der höchsten Wahrscheinlichkeit gesampelt. -- `tools`: Tool-Definitionen, die verwendet werden, damit das Modell externe Funktionen aufruft. +- `top_p`: Kern-Sampling-Parameter, der zusammen mit temperature die Zufälligkeit der Generierung steuert. +- `top_k`: Sampling erfolgt nur aus den K Optionen mit der höchsten Wahrscheinlichkeit. +- `tools`: Tool-Definitionen, die dem Modell ermöglichen, externe Funktionen aufzurufen. - `tool_choice`: Steuert, wie das Modell die bereitgestellten Tools verwendet. -- `cache_control`: Erstellt automatisch einen Cache-Haltepunkt beim letzten cachefähigen Inhaltsblock der Anfrage; kann auch auf einen konkreten Inhaltsblock geschrieben werden. -- `metadata`: Optionales Anfrage-Metadatenobjekt. `metadata.user_id` ist eine Zeichenfolge und kann eine vom Aufrufer benutzerdefinierte Benutzerkennung übergeben, beispielsweise `{"user_id":"example-user-001"}`; es wird empfohlen, eine stabile Kennung ohne personenbezogene Informationen zu verwenden. Sie ersetzt nicht die `Authorization`-Authentifizierung und muss auch nicht in den Dialoginhalt von `messages` geschrieben werden. +- `cache_control`: Erstellt automatisch einen Cache-Haltepunkt beim letzten zwischenspeicherbaren Inhaltsblock der Anfrage; kann auch in einem konkreten Inhaltsblock geschrieben werden. ### cURL-Beispiel @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -110,24 +107,24 @@ Nach dem Aufruf lautet das Rückgabeergebnis wie folgt: ``` Erläuterung der Felder des Rückgabeergebnisses: -- `id`: Die eindeutige Kennung dieser Nachricht. + +- `id`: Eindeutige Kennung dieser Nachricht. - `type`: Immer `message`. - `role`: Immer `assistant`. -- `content`: Ein Array mit Antwortinhalten, wobei jedes Element `type` (z. B. `text`) und den entsprechenden Inhalt enthält. -- `model`: Der Name des Modells, das die Anfrage verarbeitet. -- `stop_reason`: Der Grund für das Beenden. Stabile Werte umfassen `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (der aktuelle Assistant-Inhalt kann unverändert zurückgegeben werden, um fortzufahren), `refusal` und `model_context_window_exceeded`. -- `stop_sequence`: Wenn aufgrund einer benutzerdefinierten Stoppsequenz beendet wurde, wird der Text der übereinstimmenden Stoppsequenz angezeigt. +- `content`: Array mit Antwortinhalten, wobei jedes Element `type` (wie `text`) und den entsprechenden Inhalt enthält. +- `model`: Name des Modells, das die Anfrage verarbeitet. +- `stop_reason`: Grund für das Beenden. Stabile Werte umfassen `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (der aktuelle assistant-Inhalt kann unverändert zurückgesendet werden, um fortzufahren), `refusal` und `model_context_window_exceeded`. +- `stop_sequence`: Wenn aufgrund einer benutzerdefinierten Stoppsequenz angehalten wurde, wird der übereinstimmende Text der Stoppsequenz angezeigt. - `stop_details`: Wenn `stop_reason` `refusal` ist, kann dies die Ablehnungskategorie und eine Erläuterung enthalten. -- `usage`: Statistiken zur Token-Nutzung. `input_tokens` sind nicht zwischengespeicherte Eingaben; `cache_creation_input_tokens` und `cache_read_input_tokens` stehen jeweils für Cache-Schreibvorgänge und -Lesevorgänge; `output_tokens` ist die Gesamtzahl der Ausgabe-Token. Wenn `output_tokens_details.thinking_tokens` zurückgegeben wird, ist dieser Wert eine Teilmenge von `output_tokens` und darf bei der Berechnung der Gesamtsumme oder der Kosten nicht erneut hinzugefügt werden. Wenn für diese Detailangabe keine maßgebliche Zählung vorliegt, kann sie `null` sein oder weggelassen werden. -- `usage.cache_creation`: Optionale TTL-Details für Cache-Schreibvorgänge, einschließlich `ephemeral_5m_input_tokens` und `ephemeral_1h_input_tokens`. Wenn das Objekt vorhanden ist, entspricht die Summe beider Werte `cache_creation_input_tokens`; ein Feld mit `null` oder ein weggelassenes Feld bedeutet, dass für die aktuelle Antwort keine verfügbare TTL-Aufschlüsselung vorliegt und nicht als `0` interpretiert werden kann. -- `usage.cost`: Nicht-streamende Antworten können ein von Ace Data Cloud erfasstes Objekt zum Kreditverbrauch enthalten, wobei `amount` der tatsächlich bei diesem Vorgang verbrauchte Betrag, `currency` die Maßeinheit und `list_amount` der Betrag vor Rabatt (falls vorhanden) ist. Der offizielle Grundpreis für Cache-Lesevorgänge von Fable 5.1 beträgt 0,25 $/Million Token, und die Grundpreise für Cache-Schreibvorgänge mit 5 Minuten bzw. 1 Stunde betragen 12,50 $ bzw. 20 $/Million Token; die tatsächlichen Plattformpreise werden anhand des Tarifrabatts umgerechnet. +- `usage`: Token-Nutzungsstatistik. `input_tokens` sind nicht zwischengespeicherte Eingaben; `cache_creation_input_tokens` und `cache_read_input_tokens` stehen jeweils für Cache-Schreiben und -Lesen; `output_tokens` ist die Gesamtzahl aller Ausgabe-Token. Wenn `output_tokens_details.thinking_tokens` zurückgegeben wird, ist dieser Wert eine Teilmenge von `output_tokens`; bei der Berechnung der Gesamtmenge oder der Kosten darf er nicht erneut addiert werden. Wenn keine maßgebliche Zählung für diese Aufschlüsselung vorhanden ist, kann sie `null` sein oder ausgelassen werden. +- `usage.cache_creation`: Optionale TTL-Details für Cache-Schreiben, einschließlich `ephemeral_5m_input_tokens` und `ephemeral_1h_input_tokens`. Wenn das Objekt vorhanden ist, entspricht die Summe beider Werte `cache_creation_input_tokens`; ein Feld mit `null` oder ein ausgelassenes Feld bedeutet, dass für die aktuelle Antwort keine verfügbare TTL-Aufschlüsselung besteht und nicht als `0` interpretiert werden darf. +- `usage.cost`: Nicht-streamende Antworten können ein von Ace Data Cloud aufgezeichnetes Objekt zum Guthabenverbrauch enthalten, wobei `amount` der tatsächliche Verbrauch dieser Anfrage, `currency` die Maßeinheit und `list_amount` der Betrag vor Rabatt ist (falls vorhanden). Der offizielle Grundpreis für das Cache-Lesen von Fable 5.1 beträgt 0,25 $/Million Token, und die Grundpreise für 5-Minuten- und 1-Stunden-Cache-Schreiben betragen jeweils 12,50 und 20 $/Million Token; die tatsächlichen Plattformpreise werden entsprechend dem Tarifrabatt umgerechnet. ## System-Prompt Die Claude Messages API unterstützt das Festlegen eines System-Prompts über das Feld `system`, um das Verhalten, die Rolle und den Kontext des Modells zu definieren. ### Python-Beispiel - ```python import requests @@ -154,9 +151,9 @@ print(response.json()) Durch das Festlegen des `system`-Prompts können die Rolle und das Verhalten von Claude präzise gesteuert werden. -## Streamende Antworten +## Streaming-Antworten -Diese Schnittstelle unterstützt auch streamende Antworten. Setzen Sie den Parameter `stream` auf `true`, um eine schrittweise Rückgabe zu erhalten, was sich hervorragend für die zeichenweise Anzeige auf Webseiten eignet. +Diese Schnittstelle unterstützt auch Streaming-Antworten. Setzen Sie den Parameter `stream` auf `true`, um einen schrittweisen Rückgabe-Effekt zu erhalten, der sich hervorragend für die zeichenweise Anzeige auf Webseiten eignet. ### Python-Beispiel @@ -186,14 +183,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Streamende Antworten werden im Server-Sent Events (SSE)-Format zurückgegeben, wobei jede Zeile mit `event:` und `data:` beginnt. Die Typen der Streaming-Ereignisse umfassen: +Streaming-Antworten werden im Server-Sent-Events-(SSE)-Format zurückgegeben, wobei jede Zeile mit `event:` und `data:` beginnt. Zu den Streaming-Ereignistypen gehören: -- `message_start`: Die Nachricht beginnt und enthält grundlegende Informationen zur Nachricht sowie den Modellnamen. -- `content_block_start`: Der Inhaltsblock beginnt. +- `message_start`: Nachricht beginnt und enthält die grundlegenden Informationen der Nachricht sowie den Modellnamen. +- `content_block_start`: Inhaltsblock beginnt. - `content_block_delta`: Inkrementelle Aktualisierung des Inhaltsblocks, die neu generierte Textfragmente enthält. -- `content_block_stop`: Der Inhaltsblock endet. -- `message_delta`: Inkrementelle Aktualisierung auf Nachrichtenebene, die `stop_reason` und die endgültigen `usage`-Informationen enthält. Der maßgebliche Wert von `output_tokens_details.thinking_tokens` sollte nur aus dem letzten `message_delta.usage` gelesen und nicht ereignisübergreifend addiert werden. -- `message_stop`: Die Nachricht endet. +- `content_block_stop`: Inhaltsblock endet. +- `message_delta`: Inkrementelle Aktualisierung auf Nachrichtenebene, die `stop_reason` und die endgültigen `usage`-Informationen enthält. Der maßgebliche Wert von `output_tokens_details.thinking_tokens` sollte nur aus dem letzten `message_delta.usage` gelesen und nicht ereignisübergreifend summiert werden. +- `message_stop`: Nachricht endet. Die Ausgabe sieht wie folgt aus: @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Wie man sehen kann, enthalten die `content_block_delta`-Ereignisse in streamenden Antworten schrittweise generierte Textinhalte. Durch das Zusammenfügen aller `text_delta` kann die vollständige Antwort erhalten werden. +Wie zu sehen ist, enthalten die `content_block_delta`-Ereignisse in der Streaming-Antwort den schrittweise generierten Textinhalt. Durch das Zusammenfügen aller `text_delta` kann die vollständige Antwort erhalten werden. ### JavaScript-Beispiel @@ -254,9 +251,9 @@ while (true) { } ``` -## Mehrturn-Dialoge +## Mehrere Dialogrunden -Wenn Sie eine Mehrturn-Dialogfunktion anbinden möchten, müssen Sie Nachrichten mit den Rollen `user` und `assistant` abwechselnd im Array `messages` anordnen und den bisherigen Dialogverlauf gemeinsam übermitteln. +Wenn Sie die Funktion für mehrere Dialogrunden anbinden möchten, müssen Sie Nachrichten mit den Rollen `user` und `assistant` abwechselnd im `messages`-Array anordnen und den bisherigen Dialogverlauf gemeinsam übergeben. ### Python-Beispiel @@ -286,6 +283,7 @@ print(response.json()) ``` Das Rückgabeergebnis lautet wie folgt: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ Das Rückgabeergebnis lautet wie folgt: } ``` -Durch die Übergabe des vollständigen Gesprächsverlaufs in `messages` kann Claude den Kontext für präzise Antworten nutzen. +Durch die Übergabe des vollständigen Dialogverlaufs in `messages` kann Claude unter Berücksichtigung des Kontexts präzise antworten. -## Tiefdenkende Modelle +## Modell für tiefgehendes Denken -Claudes thinking und thinking summary sind zwei unterschiedliche Konzepte: Das Modell kann intern Schlussfolgerungen ziehen, aber die API gibt nicht die ursprüngliche Gedankenkette zurück. Wenn der Denkprozess angezeigt werden muss, gibt die API eine verarbeitete Zusammenfassung zurück. +Claude's Thinking und Thinking Summary sind zwei unterschiedliche Konzepte: Das Modell kann interne Schlussfolgerungen durchführen, aber die API gibt nicht die ursprüngliche Gedankenkette zurück. Wenn der Schlussfolgerungsprozess angezeigt werden soll, gibt die API eine verarbeitete Zusammenfassung zurück. -Für aktuelle Modelle wird empfohlen, adaptive thinking zu verwenden und den gesamten Schlussfolgerungsaufwand über `output_config.effort` zu steuern: +Für aktuelle Modelle wird die Verwendung von Adaptive Thinking empfohlen, wobei der gesamte Schlussfolgerungsaufwand über `output_config.effort` gesteuert wird: ```python import requests @@ -343,7 +341,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Der thinking-Block in der Antwort sieht wie folgt aus: +Der Thinking-Block in der Antwort sieht wie folgt aus: ```json { @@ -352,25 +350,24 @@ Der thinking-Block in der Antwort sieht wie folgt aus: "signature": "opaque-signature" } ``` - -- `display: "summarized"` gibt eine lesbare Denkzusammenfassung zurück; sie ist nicht die ursprüngliche Gedankenkette. -- `display: "omitted"` gibt `thinking: ""` zurück, behält jedoch die undurchsichtige `signature` zur Unterstützung nachfolgender Gespräche bei. -- `display: "updates"` ist der Beta-Modus von Anthropic und erfordert `anthropic-beta: thinking-display-updates-2026-08-18`. Die offizielle Definition lautet, dass der Text der versteckten Schlussfolgerungen ausgeblendet und kurze Fortschrittsaktualisierungen zwischen Tool-Aufrufen angezeigt werden. Die Plattform leitet diesen Parameter und den Beta-Anfrage-Header unverändert weiter und schreibt ihn nicht zwangsweise in `summarized` um; der tatsächliche Ausgabeinhalt hängt von der Unterstützung des ausgewählten Modells ab. -- `thinking`, `output_config`, effort, Sampling-Parameter und neue Erweiterungsfelder werden unverändert weitergeleitet. Die Plattform pflegt keine hartcodierten Werteaufzählungen oder Kombinationsbeschränkungen nach Modell und schreibt den thinking-Modus auch nicht automatisch um; ob diese Parameter akzeptiert werden, wird vom ausgewählten Modell bestimmt, und vom Modell zurückgegebene Parameterfehler werden an den Client weitergeleitet. +- `display: "summarized"` gibt eine lesbare Zusammenfassung der Überlegungen zurück; es ist nicht die ursprüngliche Gedankenkette. +- `display: "omitted"` gibt `thinking: ""` zurück, behält jedoch die opaque `signature` zur Unterstützung nachfolgender Gespräche bei. +- `display: "updates"` ist ein Beta-Modus von Anthropic und muss `anthropic-beta: thinking-display-updates-2026-08-18` enthalten. Die offizielle Definition ist, den Textkörper der Überlegungen auszublenden und kurze Fortschrittsupdates zwischen Tool-Aufrufen anzuzeigen. Die Plattform leitet diesen Parameter und den Beta-Request-Header unverändert weiter und schreibt ihn nicht zwangsweise zu `summarized` um; der tatsächliche Ausgabeinhalt hängt von der Unterstützung des ausgewählten Modells ab. +- `thinking`, `output_config`, effort, Sampling-Parameter und neu hinzugefügte Erweiterungsfelder werden unverändert weitergeleitet. Die Plattform verwaltet keine hartcodierten Werteaufzählungen oder Kombinationsbeschränkungen nach Modell und schreibt den thinking-Modus auch nicht automatisch um; ob diese Parameter akzeptiert werden, entscheidet das ausgewählte Modell, und vom Modell zurückgegebene Parameterfehler werden an den Client weitergeleitet. - Der Standardwert für display bei Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 und Opus 4.7 ist `omitted`; Opus 4.6, Sonnet 4.6 und frühere Modelle mit thinking-Unterstützung verwenden standardmäßig `summarized`. -- Display beeinflusst nur den Rückgabeinhalt und die Streaming-Latenz, deaktiviert die Schlussfolgerungen nicht und reduziert auch nicht die Abrechnung von thinking-Tokens. -- Ob thinking standardmäßig aktiviert ist und welcher display-Standardwert verwendet wird, sind zwei unabhängige Fragen. Opus 5 und Sonnet 5 aktivieren adaptive thinking standardmäßig; bei Opus 5 entspricht das Weglassen von `thinking` adaptive, und das Weglassen von `output_config.effort` entspricht `high`. Opus 4.8, 4.7 und 4.6 müssen explizit aktiviert werden. -- Thinking und der endgültige Text teilen sich das Ausgabe-Budget von `max_tokens`. Bei einem zu kleinen Budget kann thinking den Großteil des Kontingents verbrauchen, sodass der Text leer bleibt oder abgeschnitten wird; erhöhen Sie bitte `max_tokens` oder verwenden Sie `low` / `medium` effort, um den Schlussfolgerungsaufwand zu steuern. +- Display beeinflusst nur den zurückgegebenen Inhalt und die Streaming-Latenz, deaktiviert die Überlegungen nicht und reduziert auch nicht die Abrechnung von thinking-Token. +- Ob thinking standardmäßig aktiviert ist und welcher display-Standardwert gilt, sind zwei unabhängige Fragen. Opus 5 und Sonnet 5 aktivieren standardmäßig adaptive thinking; bei Opus 5 entspricht das Weglassen von `thinking` adaptive, und das Weglassen von `output_config.effort` entspricht `high`. Opus 4.8, 4.7 und 4.6 müssen explizit aktiviert werden. +- Thinking und der endgültige Textkörper teilen sich das Ausgabebudget von `max_tokens`. Ist das Budget zu klein, kann thinking den Großteil des Budgets belegen, sodass der Textkörper leer bleibt oder abgeschnitten wird; erhöhen Sie bitte `max_tokens`, oder verwenden Sie `low` / `medium` effort, um den Aufwand für die Überlegungen zu steuern. - Für Modelle, bei denen thinking deaktiviert werden darf, kann `thinking: {"type":"disabled"}` übergeben werden. Neue Modi wie `between_tools` sowie effort-Kombinationen hängen vom ausgewählten Modell ab; die Plattform lehnt sie nicht vorab anhand alter Modellregeln ab. -- Ein festes Denkbudget kann über `budget_tokens` übergeben werden; neue Modelle verwenden üblicherweise `thinking.type=adaptive` und `output_config.effort`. Ob ein festes Budget oder das Deaktivieren des Denkens unterstützt wird, richtet sich nach den aktuellen Fähigkeiten des ausgewählten Modells. -- Bei mehrteiligen Gesprächen und Tool-Aufrufen sollten der vollständige thinking-Block und die signature, die vom assistant zurückgegeben wurden, unverändert zurückgesendet werden; ändern oder erzeugen Sie die signature nicht selbst. -- Die Parameterweiterleitung bedeutet nicht, dass jedes Modell alle Funktionen unterstützt. Protokollübergreifende Aufrufe müssen weiterhin konvertiert werden, und der Unterstützungsumfang sowie Fehler bei Inhalten wie `redacted_thinking` werden vom Modellservice bestimmt, der die Anfrage tatsächlich verarbeitet. +- Ein festes Überlegungsbudget kann über `budget_tokens` weitergegeben werden; neue Modelle verwenden normalerweise `thinking.type=adaptive` und `output_config.effort`. Ob ein festes Budget oder das Deaktivieren von thinking unterstützt wird, richtet sich nach den aktuellen Fähigkeiten des ausgewählten Modells. +- Bei mehrstufigen Gesprächen und Tool-Aufrufen sollten der vollständige vom assistant zurückgegebene thinking-Block sowie die signature unverändert zurückgegeben werden; ändern oder generieren Sie die signature nicht selbst. +- Die Parameterweiterleitung bedeutet nicht, dass jedes Modell alle Funktionen unterstützt. Protokollübergreifende Aufrufe müssen weiterhin konvertiert werden; der Unterstützungsumfang und Fehler von Inhalten wie `redacted_thinking` werden vom Modelldienst bestimmt, der die Anfrage tatsächlich verarbeitet. -In Streaming-Anfragen erzeugt `summarized` `thinking_delta`; `omitted` erzeugt kein `thinking_delta`, sondern behält nur den Lebenszyklus des thinking-Blocks und `signature_delta` bei. +In Streaming-Anfragen erzeugt `summarized` `thinking_delta`; `omitted` erzeugt kein `thinking_delta` und behält nur den Lebenszyklus des thinking-Blocks und `signature_delta` bei. ## Visuelle Modelle -Claude unterstützt multimodale Eingaben und kann Text und Bilder gleichzeitig verarbeiten. In der Messages API können visuelle Fähigkeiten verwendet werden, indem `content` auf ein Array-Format gesetzt und Bildinhaltsblöcke übergeben werden. +Claude unterstützt multimodale Eingaben und kann Text und Bilder gleichzeitig verarbeiten. In der Messages API können Sie visuelle Fähigkeiten verwenden, indem Sie `content` auf ein Array-Format setzen und Bildinhaltsblöcke übergeben. ### Verwendung von Base64-kodierten Bildern @@ -459,6 +456,7 @@ print(response.json()) ``` ### cURL-Beispiel + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -488,11 +486,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Zu den unterstützten Bildformaten gehören: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Unterstützte Bildformate umfassen: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Dokumente und PDF -PDF verwendet den Inhaltsblock `document` und unterstützt zwei stabile Quellen: Base64 und URL. Die Base64-Quelle muss `application/pdf` verwenden: +PDF verwendet den `document`-Inhaltsblock und unterstützt zwei stabile Quellen: Base64 und URL. Die Base64-Quelle muss `application/pdf` verwenden: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -Die URL-Quelle wird als `{"type":"url","url":"https://example.com/report.pdf"}` geschrieben. `document` unterstützt außerdem `text/plain` sowie `content`-Quellen, die aus text/image-Blöcken bestehen; optionale Felder umfassen `title`, `context` und `citations`. Die `file_id`-Quelle der Files API gehört zu einer eigenständigen Beta-Funktion und ist nicht Teil des stabilen Vertrags dieser Schnittstelle. +Die URL-Quelle wird als `{"type":"url","url":"https://example.com/report.pdf"}` geschrieben. `document` unterstützt außerdem `text/plain` sowie eine `content`-Quelle, die aus text/image-Blöcken besteht; optionale Felder umfassen `title`, `context` und `citations`. Die `file_id`-Quelle der Files API gehört zu einer eigenständigen Beta-Funktion und ist nicht Teil des stabilen Vertrags dieser Schnittstelle. ## Prompt-Caching -Das oberste `cache_control` platziert den Cache-Unterbrechungspunkt automatisch auf dem letzten zwischenspeicherbaren Block: +Das übergeordnete `cache_control` setzt den Cache-Haltepunkt automatisch auf den letzten cachebaren Block: ```python payload = { @@ -536,12 +534,11 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Wenn eine präzise Positionssteuerung erforderlich ist, kann derselbe `cache_control` auch auf text-, image-, document-, tool_use-, tool_result-Inhaltsblöcke oder Werkzeugdefinitionen geschrieben werden. `ttl` unterstützt `5m` (Standard) und `1h`; bitte verwenden Sie `usage.cache_creation_input_tokens` und `usage.cache_read_input_tokens`, um Cache-Schreibvorgänge und Cache-Treffer zu bestimmen. -Wenn eine präzise Positionskontrolle erforderlich ist, kann dasselbe `cache_control` auch auf text-, image-, document-, tool_use-, tool_result-Inhaltsblöcke oder Werkzeugdefinitionen geschrieben werden. `ttl` unterstützt `5m` (Standard) und `1h`; bestimmen Sie Cache-Schreibvorgänge und Treffer über `usage.cache_creation_input_tokens` und `usage.cache_read_input_tokens`. - -Wenn die Antwort `usage.cache_creation` bereitstellt, gilt `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Wenn `cache_creation` `null` ist oder ausgelassen wird, bedeutet dies, dass nur die Gesamtmenge der Cache-Schreibvorgänge und keine verlässliche TTL-Aufschlüsselung vorhanden ist; behandeln Sie in diesem Fall keinen Bucket als bekannten Wert von 0, Abrechnung und Gesamtmenge richten sich weiterhin nach dem aggregierten Feld. +Wenn die Antwort `usage.cache_creation` bereitstellt, gilt `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Wenn `cache_creation` `null` ist oder weggelassen wird, bedeutet dies, dass nur die Gesamtmenge der Cache-Schreibvorgänge vorliegt und keine autoritative TTL-Aufschlüsselung vorhanden ist; behandeln Sie in diesem Fall keinen Bucket als bekanntermaßen 0, Abrechnung und Gesamtmenge richten sich weiterhin nach dem Aggregatfeld. -Beispiel eines Rückgabeergebnisses: +Beispiel für ein Rückgabeergebnis: ```json { @@ -566,7 +563,7 @@ Beispiel eines Rückgabeergebnisses: ## Werkzeugaufrufe (Tool Use) -Die Claude Messages API unterstützt nativ Werkzeugaufrufe und ermöglicht dem Modell, bei Bedarf Ihre vordefinierten Werkzeuge/Funktionen aufzurufen. +Die Claude Messages API unterstützt nativ Werkzeugaufrufe und ermöglicht es dem Modell, bei Bedarf Ihre vordefinierten Werkzeuge/Funktionen aufzurufen. ### Python-Beispiel @@ -640,7 +637,7 @@ Wenn das Modell entscheidet, ein Werkzeug aufzurufen, enthält `content` im Rüc } ``` -Beachten Sie, dass `stop_reason` `tool_use` ist, was bedeutet, dass das Modell ein Werkzeug aufrufen muss. Nach Erhalt dieses Ergebnisses müssen Sie die Werkzeugfunktion ausführen und das Ergebnis in Form von `tool_result` an das Modell zurückgeben: +Beachten Sie, dass `stop_reason` den Wert `tool_use` hat, was bedeutet, dass das Modell ein Werkzeug aufrufen muss. Nachdem Sie dieses Ergebnis erhalten haben, müssen Sie die Werkzeugfunktion ausführen und das Ergebnis in Form von `tool_result` an das Modell zurücksenden: ```python payload = { @@ -688,34 +685,35 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Das Modell generiert auf Grundlage des vom Werkzeug zurückgegebenen Ergebnisses eine abschließende Antwort in natürlicher Sprache. +Das Modell generiert auf Grundlage des vom Werkzeug zurückgegebenen Ergebnisses die endgültige Antwort in natürlicher Sprache. ## Unterschiede zur Chat Completion API -Ace Data Cloud bietet gleichzeitig zwei Claude-API-Formate an, deren Hauptunterschiede wie folgt sind: +Ace Data Cloud bietet gleichzeitig zwei Claude-API-Formate an. Die wichtigsten Unterschiede zwischen beiden sind wie folgt: -`usage.input_tokens` der Messages API steht nur für nicht zwischengespeicherte Eingaben, während `cache_read_input_tokens` und `cache_creation_input_tokens` eigenständige Abrechnungs-Buckets sind; alle drei werden jeweils nach den entsprechenden Preisen berechnet. -| Funktion | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +`usage.input_tokens` der Messages API steht nur für nicht zwischengespeicherte Eingaben, `cache_read_input_tokens` und `cache_creation_input_tokens` sind unabhängige Abrechnungs-Buckets; alle drei werden jeweils nach dem entsprechenden Preis berechnet. + +| Merkmal | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Format | Anthropic-natives Format | OpenAI-kompatibles Format | -| System-Prompt | Eigenständiges `system`-Feld | Über `role: "system"` in `messages` übergeben | +| System-Prompt | Eigenständiges `system`-Feld | Übergabe über `role: "system"` in `messages` | | Antwortstruktur | `content`-Array (unterstützt mehrere Typen) | `choices`-Array (enthält `message`) | | Streaming-Format | SSE-Ereignisse (mehrere Ereignistypen) | SSE-`data`-Zeilen | -| Tiefes Denken | Natives `thinking` und `output_config.effort` | Standardstrategie des Modells und Kompatibilitätsparameter | -| Tool-Aufrufe | Natives `tools` + `input_schema` | OpenAI-kompatibles `tools`-Format | +| Tiefes Nachdenken | Natives `thinking` und `output_config.effort` | Standardstrategie des Modells und Kompatibilitätsparameter | +| Werkzeugaufrufe | Natives `tools` + `input_schema` | OpenAI-kompatibles `tools`-Format | | Token-Statistiken | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Wenn Ihr System bereits eine API im OpenAI-Format integriert hat, können Sie die Chat Completion API für einen nahtlosen Wechsel verwenden. Wenn Sie alle nativen Fähigkeiten von Claude nutzen müssen, wird die Messages API empfohlen. +Wenn Ihr System bereits an eine API im OpenAI-Format angebunden ist, können Sie die Chat Completion API für einen nahtlosen Wechsel verwenden. Wenn Sie alle nativen Fähigkeiten von Claude nutzen müssen, wird empfohlen, die Messages API zu verwenden. ## Fehlerbehandlung -Die Fehlerantworten der öffentlichen Schnittstelle verwenden das Ace Data Cloud-Plattform-Envelope: `error.code` ist ein stabiler Fehlercode, `error.message` ist eine Beschreibung, und `trace_id` wird zur Untersuchung von Anfragen verwendet. Häufige HTTP-Statuswerte umfassen: +Die Fehlerantworten der öffentlichen Schnittstelle verwenden das Ace Data Cloud Plattform-Envelope: `error.code` ist ein stabiler Fehlercode, `error.message` ist eine Beschreibung, und `trace_id` wird zur Untersuchung von Anfragen verwendet. Häufige HTTP-Statuswerte umfassen: -- `400`: Anforderungsparameter oder Protokollinhalt sind ungültig. -- `401`: Das Autorisierungstoken ist ungültig, fehlt oder ist abgelaufen. -- `403`: Zugriff verweigert, unzureichendes Guthaben oder eingeschränkte Quote. +- `400`: Anfrageparameter oder Protokollinhalt ungültig. +- `401`: Autorisierungstoken ungültig, fehlt oder ist abgelaufen. +- `403`: Zugriff verboten, unzureichendes Guthaben oder eingeschränktes Kontingent. - `404`: API oder Modell existiert nicht. -- `413`: Anfragekörper ist zu groß. +- `413`: Anfragekörper zu groß. - `429`: Zu viele Anfragen. - `500` / `503` / `504`: Dienstfehler, vorübergehend nicht verfügbar oder Verarbeitungs-Timeout. @@ -731,8 +729,7 @@ Die Fehlerantworten der öffentlichen Schnittstelle verwenden das Ace Data Cloud } ``` -Diese Fehlerstruktur ist der Laufzeitvertrag von Ace Data Cloud und entspricht nicht dem offiziellen Anthropic-Fehler-Envelope; bitte behandeln Sie sie anhand des HTTP-Status und von `error.code`. +Diese Fehlerstruktur ist der Laufzeitvertrag von Ace Data Cloud und entspricht nicht dem offiziellen Fehler-Envelope von Anthropic; bitte behandeln Sie sie anhand des HTTP-Status und von `error.code`. ## Fazit - -Durch dieses Dokument haben Sie bereits erfahren, wie Sie die Konversationsfunktionen von Claude über die Claude Messages API im Anthropic-nativen Format aufrufen können. Die Messages API unterstützt umfangreiche Funktionen wie grundlegende Konversationen, System-Prompts, Streaming-Antworten, mehrstufige Konversationen, tiefes Denken, visuelles Verständnis, PDFs, Prompt-Caching und Tool-Aufrufe. Bei Fragen können Sie sich jederzeit an unser technisches Support-Team wenden. +Durch dieses Dokument haben Sie bereits erfahren, wie Sie die Claude Messages API verwenden können, um Claudes Konversationsfunktionen im nativen Anthropic-Format aufzurufen. Die Messages API unterstützt umfangreiche Funktionen wie grundlegende Konversationen, System-Prompts, Streaming-Antworten, mehrteilige Konversationen, tiefes Denken, visuelles Verständnis, PDFs, Prompt-Caching und Tool-Aufrufe. Bei Fragen können Sie sich jederzeit an unser technisches Support-Team wenden. diff --git a/el/guides/claude/claude_messages.mdx b/el/guides/claude/claude_messages.mdx index 5fdc28fa..f017878c 100644 --- a/el/guides/claude/claude_messages.mdx +++ b/el/guides/claude/claude_messages.mdx @@ -3,9 +3,9 @@ title: "Αίτηση και χρήση του Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Το Anthropic Claude είναι ένα πολύ ισχυρό σύστημα συνομιλίας AI, το οποίο μπορεί να δημιουργήσει ομαλές και φυσικές απαντήσεις μέσα σε λίγα δευτερόλεπτα, αρκεί να εισαχθεί ένα prompt. Το Claude Messages API είναι η επίσημη εγγενής μορφή API της Anthropic. Σε αντίθεση με τη μορφή συμβατή με OpenAI (Chat Completion), χρησιμοποιεί τη δική του δομή αιτημάτων και αποκρίσεων της Anthropic, επιτρέποντας την καλύτερη αξιοποίηση των μοναδικών δυνατοτήτων του Claude, όπως η πολυτροπική εισαγωγή περιεχομένου, η κλήση εργαλείων, η βαθιά σκέψη (Extended Thinking) και άλλα προηγμένα χαρακτηριστικά. +Το Anthropic Claude είναι ένα εξαιρετικά ισχυρό σύστημα διαλόγου AI, το οποίο μπορεί να δημιουργήσει ομαλές και φυσικές απαντήσεις μέσα σε λίγα δευτερόλεπτα αρκεί να εισαχθεί ένα prompt. Το Claude Messages API είναι η επίσημη εγγενής μορφή API της Anthropic. Σε αντίθεση με τη μορφή συμβατή με OpenAI (Chat Completion), υιοθετεί τη δική του δομή αιτήματος και απόκρισης της Anthropic, επιτρέποντας την καλύτερη αξιοποίηση των μοναδικών δυνατοτήτων του Claude, όπως η πολυτροπική είσοδος περιεχομένου, η κλήση εργαλείων, η εκτεταμένη σκέψη (Extended Thinking) και άλλα προηγμένα χαρακτηριστικά. -Αυτό το έγγραφο παρουσιάζει κυρίως τη διαδικασία χρήσης των λειτουργιών του Claude Messages API. Με αυτό μπορούμε να χρησιμοποιήσουμε εγγενείς διεπαφές συνεπείς με τις επίσημες της Anthropic για να καλέσουμε τις λειτουργίες συνομιλίας του Claude. +Αυτό το έγγραφο παρουσιάζει κυρίως τη διαδικασία χρήσης των λειτουργιών του Claude Messages API. Χρησιμοποιώντας το, μπορούμε να καλέσουμε τη λειτουργία διαλόγου του Claude μέσω εγγενών διεπαφών συνεπών με τις επίσημες της Anthropic. ## Διαδικασία αίτησης @@ -13,32 +13,31 @@ description: "Claude AI API guide - Ace Data Cloud" ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Αν δεν έχετε συνδεθεί ή εγγραφεί ακόμη, θα ανακατευθυνθείτε αυτόματα στη σελίδα σύνδεσης, όπου θα σας προσκληθεί να εγγραφείτε και να συνδεθείτε. Μετά την ολοκλήρωση, θα επιστρέψετε αυτόματα στην τρέχουσα σελίδα. +Εάν δεν έχετε ακόμη συνδεθεί ή εγγραφεί, θα ανακατευθυνθείτε αυτόματα στη σελίδα σύνδεσης για να εγγραφείτε και να συνδεθείτε, και μετά την ολοκλήρωση θα επιστρέψετε αυτόματα στην τρέχουσα σελίδα. -**Ένα API Token αρκεί για την κλήση όλων των υπηρεσιών της πλατφόρμας, χωρίς να χρειάζεται ξεχωριστή αίτηση για κάθε υπηρεσία.** Η πρώτη αίτηση προσφέρει δωρεάν πίστωση για δωρεάν δοκιμή· όταν η πίστωση δεν επαρκεί, μπορείτε να φορτίσετε γενικό υπόλοιπο στην [κονσόλα](https://platform.acedata.cloud/console/coin). +**Ένα API Token αρκεί για την κλήση όλων των υπηρεσιών της πλατφόρμας, χωρίς να απαιτείται ξεχωριστή αίτηση για κάθε υπηρεσία.** Η πρώτη αίτηση περιλαμβάνει δωρεάν πίστωση για δωρεάν δοκιμή· όταν η πίστωση δεν επαρκεί, μπορείτε να φορτίσετε γενικό υπόλοιπο στην [κονσόλα](https://platform.acedata.cloud/console/coin). > 📘 Πλήρης τεκμηρίωση: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Βασική χρήση -Η διαδρομή αιτήματος του Claude Messages API είναι `/v1/messages`, συνεπής με το επίσημο API της Anthropic. Πρέπει να παρέχουμε τουλάχιστον τρεις υποχρεωτικές παραμέτρους: +Η διαδρομή αιτήματος του Claude Messages API είναι `/v1/messages`, συνεπής με το επίσημο API της Anthropic. Χρειάζεται να παρέχουμε τουλάχιστον τρεις υποχρεωτικές παραμέτρους: -- `model`: Επιλέγει το μοντέλο Claude που θα χρησιμοποιηθεί. Το `claude-opus-5-5` παρέχεται μόνο μέσω του Messages API, υποστηρίζει περιβάλλον 1 εκατομμυρίου Token, μέγιστη έξοδο 128K Token και ενεργοποιεί πάντα την προσαρμοστική σκέψη. Το νεότερο κορυφαίο μοντέλο είναι το `claude-fable-5-1` (περιβάλλον 1 εκατομμυρίου Token, μέγιστη έξοδος 128K Token)· το προηγούμενο `claude-fable-5` παραμένει συμβατό. Το `claude-sonnet-5-5` έχει προστεθεί στη σειρά εγγενών διεπαφών Messages, υποστηρίζει εισαγωγή εικόνων και προσαρμοστική σκέψη· οι επίσημες τιμές αναφοράς για είσοδο, έξοδο και ανάγνωση cache είναι αντίστοιχα 2, 10 και 0,20 δολάρια ανά εκατομμύριο Token. -- `messages`: Ο πίνακας εισαγόμενων μηνυμάτων. Κάθε μήνυμα περιλαμβάνει `role` (ρόλος) και `content` (περιεχόμενο), όπου το `role` υποστηρίζει `user` και `assistant`. +- `model`: Επιλέγει το μοντέλο Claude που θα χρησιμοποιηθεί. Το `claude-opus-5-5` παρέχεται μόνο μέσω του Messages API, υποστηρίζει πλαίσιο 1 εκατομμυρίου Token, μέγιστη έξοδο 128K Token και ενεργοποιεί πάντα προσαρμοστική σκέψη. Η νεότερη ναυαρχίδα είναι το `claude-fable-5-1` (πλαίσιο 1 εκατομμυρίου Token, μέγιστη έξοδος 128K Token)· το προηγούμενο `claude-fable-5` παραμένει συμβατό και διαθέσιμο. Το `claude-sonnet-5-5` έχει προστεθεί στη σειρά εγγενών διεπαφών Messages, υποστηρίζει είσοδο εικόνων και προσαρμοστική σκέψη· οι επίσημες τιμές αναφοράς για είσοδο, έξοδο και ανάγνωση cache είναι αντίστοιχα 2, 10 και 0,20 δολάρια ανά εκατομμύριο Token. +- `messages`: Ο πίνακας εισαγόμενων μηνυμάτων. Κάθε μήνυμα περιλαμβάνει `role` (ρόλο) και `content` (περιεχόμενο), όπου το `role` υποστηρίζει `user` και `assistant`. - `max_tokens`: Ο μέγιστος αριθμός token εξόδου, που χρησιμοποιείται για τον περιορισμό του μήκους μιας μεμονωμένης απάντησης. Συνήθεις προαιρετικές παράμετροι: - `system`: Το system prompt, που χρησιμοποιείται για τον καθορισμό της συμπεριφοράς και του ρόλου του μοντέλου. -- `temperature`: Η τυχαιότητα παραγωγής, μεταξύ 0 και 1· όσο μεγαλύτερη είναι η τιμή, τόσο πιο αποκλίνουσες είναι οι απαντήσεις. -- `stream`: Αν θα χρησιμοποιηθεί ροϊκή απόκριση· ορίζοντας `true` μπορεί να επιτευχθεί εφέ επιστροφής χαρακτήρα προς χαρακτήρα. -- `stop_sequences`: Προσαρμοσμένες ακολουθίες διακοπής· το μοντέλο σταματά την παραγωγή όταν συναντά αυτά τα κείμενα. -- `top_p`: Παράμετρος δειγματοληψίας πυρήνα, που ελέγχει την τυχαιότητα της παραγωγής σε συνδυασμό με το temperature. +- `temperature`: Η τυχαιότητα της δημιουργίας, μεταξύ 0-1· όσο μεγαλύτερη είναι η τιμή, τόσο πιο αποκλίνουσες είναι οι απαντήσεις. +- `stream`: Αν θα χρησιμοποιηθεί ροή απόκρισης· ορίζοντας το σε `true` μπορεί να επιτευχθεί εφέ επιστροφής χαρακτήρα προς χαρακτήρα. +- `stop_sequences`: Προσαρμοσμένες ακολουθίες διακοπής· το μοντέλο θα σταματήσει τη δημιουργία όταν συναντήσει αυτά τα κείμενα. +- `top_p`: Παράμετρος δειγματοληψίας πυρήνα, που ελέγχει την τυχαιότητα της δημιουργίας σε συνδυασμό με το temperature. - `top_k`: Δειγματοληψία μόνο από τις K επιλογές με την υψηλότερη πιθανότητα. - `tools`: Ορισμοί εργαλείων, που χρησιμοποιούνται για να επιτρέπουν στο μοντέλο να καλεί εξωτερικές συναρτήσεις. - `tool_choice`: Ελέγχει πώς το μοντέλο χρησιμοποιεί τα παρεχόμενα εργαλεία. -- `cache_control`: Δημιουργεί αυτόματα σημείο διακοπής cache στο τελευταίο μπλοκ περιεχομένου που μπορεί να αποθηκευτεί προσωρινά στο αίτημα· μπορεί επίσης να γραφτεί σε συγκεκριμένο μπλοκ περιεχομένου. -- `metadata`: Προαιρετικό αντικείμενο μεταδεδομένων αιτήματος. Το `metadata.user_id` είναι συμβολοσειρά και μπορεί να μεταφέρει προσαρμοσμένο αναγνωριστικό χρήστη του καλούντος, για παράδειγμα `{"user_id":"example-user-001"}`· συνιστάται η χρήση σταθερού αναγνωριστικού που δεν περιέχει προσωπικές πληροφορίες. Δεν αντικαθιστά την ταυτοποίηση `Authorization`, ούτε χρειάζεται να γραφτεί στο περιεχόμενο συνομιλίας `messages`. +- `cache_control`: Δημιουργεί αυτόματα σημείο διακοπής cache στο τελευταίο αποθηκεύσιμο μπλοκ περιεχομένου του αιτήματος· μπορεί επίσης να γραφτεί σε συγκεκριμένο μπλοκ περιεχομένου. ### Παράδειγμα cURL @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -86,7 +83,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Μετά την κλήση, το αποτέλεσμα επιστροφής είναι το εξής: +Μετά την κλήση, το αποτέλεσμα επιστροφής είναι το ακόλουθο: ```json { @@ -109,25 +106,25 @@ print(response.json()) } ``` -Επεξήγηση των πεδίων του αποτελέσματος επιστροφής: -- `id`：Το μοναδικό αναγνωριστικό του τρέχοντος μηνύματος. -- `type`：Πάντα `message`. -- `role`：Πάντα `assistant`. -- `content`：Πίνακας περιεχομένου απάντησης, όπου κάθε στοιχείο περιλαμβάνει `type` (όπως `text`) και το αντίστοιχο περιεχόμενο. -- `model`：Το όνομα του μοντέλου που επεξεργάζεται το αίτημα. -- `stop_reason`：Ο λόγος διακοπής. Οι σταθερές τιμές περιλαμβάνουν `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (μπορείτε να επιστρέψετε αυτούσιο το τρέχον περιεχόμενο του assistant για να συνεχίσετε), `refusal` και `model_context_window_exceeded`. -- `stop_sequence`：Αν η διακοπή οφείλεται σε προσαρμοσμένη ακολουθία διακοπής, εμφανίζει το κείμενο της ακολουθίας διακοπής που αντιστοιχίστηκε. -- `stop_details`：Όταν το `stop_reason` είναι `refusal`, μπορεί να περιλαμβάνει την κατηγορία και την περιγραφή της άρνησης. -- `usage`：Στατιστικά χρήσης token. Το `input_tokens` είναι η μη αποθηκευμένη στην προσωρινή μνήμη είσοδος· τα `cache_creation_input_tokens` και `cache_read_input_tokens` είναι αντίστοιχα η εγγραφή και η ανάγνωση της προσωρινής μνήμης· το `output_tokens` είναι ο συνολικός αριθμός token εξόδου. Αν επιστρέφεται το `output_tokens_details.thinking_tokens`, αυτή η τιμή είναι υποσύνολο του `output_tokens` και δεν πρέπει να προστεθεί ξανά κατά τον υπολογισμό του συνόλου ή του κόστους. Όταν αυτή η ανάλυση δεν έχει επίσημη καταμέτρηση, μπορεί να είναι `null` ή να παραλείπεται. -- `usage.cache_creation`：Προαιρετικές λεπτομέρειες TTL εγγραφής προσωρινής μνήμης, που περιλαμβάνουν `ephemeral_5m_input_tokens` και `ephemeral_1h_input_tokens`. Όταν το αντικείμενο υπάρχει, το άθροισμα των δύο ισούται με `cache_creation_input_tokens`· όταν τα πεδία είναι `null` ή παραλείπονται, σημαίνει ότι η τρέχουσα απόκριση δεν διαθέτει χρησιμοποιήσιμη ανάλυση TTL και δεν πρέπει να ερμηνεύεται ως `0`. -- `usage.cost`：Οι μη ροϊκές αποκρίσεις μπορεί να περιλαμβάνουν ένα αντικείμενο κατανάλωσης πιστώσεων που καταγράφεται από το Ace Data Cloud, όπου το `amount` είναι η πραγματική κατανάλωση αυτής της φοράς, το `currency` είναι η μονάδα μέτρησης και το `list_amount` είναι το ποσό πριν από την έκπτωση (εάν υπάρχει). Η επίσημη βασική τιμή για ανάγνωση προσωρινής μνήμης του Fable 5.1 είναι $0.25/εκατομμύριο Token, ενώ οι βασικές τιμές εγγραφής προσωρινής μνήμης για 5 λεπτά και 1 ώρα είναι αντίστοιχα $12.50 και $20/εκατομμύριο Token· η πραγματική τιμή της πλατφόρμας μετατρέπεται σύμφωνα με την έκπτωση του προγράμματος. +Περιγραφή των πεδίων του αποτελέσματος επιστροφής: -## Προτροπή συστήματος +- `id`: Το μοναδικό αναγνωριστικό του τρέχοντος μηνύματος. +- `type`: Πάντα `message`. +- `role`: Πάντα `assistant`. +- `content`: Πίνακας περιεχομένου απάντησης, όπου κάθε στοιχείο περιλαμβάνει `type` (όπως `text`) και το αντίστοιχο περιεχόμενο. +- `model`: Το όνομα του μοντέλου που επεξεργάζεται το αίτημα. +- `stop_reason`: Ο λόγος διακοπής. Οι σταθερές τιμές περιλαμβάνουν `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (μπορείτε να επιστρέψετε αυτούσιο το τρέχον περιεχόμενο του assistant για να συνεχίσετε), `refusal` και `model_context_window_exceeded`. +- `stop_sequence`: Εάν σταμάτησε λόγω προσαρμοσμένης ακολουθίας διακοπής, εμφανίζει το κείμενο της ακολουθίας διακοπής που αντιστοιχίστηκε. +- `stop_details`: Όταν το `stop_reason` είναι `refusal`, μπορεί να περιλαμβάνει την κατηγορία απόρριψης και περιγραφή. +- `usage`: Στατιστικά χρήσης token. Το `input_tokens` είναι η μη αποθηκευμένη στην cache είσοδος· τα `cache_creation_input_tokens` και `cache_read_input_tokens` είναι αντίστοιχα εγγραφή και ανάγνωση cache· το `output_tokens` είναι ο συνολικός αριθμός token εξόδου. Εάν επιστρέφεται το `output_tokens_details.thinking_tokens`, αυτή η τιμή είναι υποσύνολο του `output_tokens`· μην την προσθέτετε ξανά κατά τον υπολογισμό του συνόλου ή του κόστους. Αυτή η ανάλυση μπορεί να είναι `null` ή να παραλείπεται όταν δεν υπάρχει έγκυρη καταμέτρηση. +- `usage.cache_creation`: Προαιρετικές λεπτομέρειες TTL εγγραφής cache, που περιλαμβάνουν `ephemeral_5m_input_tokens` και `ephemeral_1h_input_tokens`. Όταν υπάρχει το αντικείμενο, το άθροισμα των δύο ισούται με το `cache_creation_input_tokens`· εάν το πεδίο είναι `null` ή παραλείπεται, σημαίνει ότι η τρέχουσα απόκριση δεν διαθέτει ανάλυση TTL και δεν μπορεί να ερμηνευτεί ως `0`. +- `usage.cost`: Οι μη ροϊκές αποκρίσεις μπορεί να περιλαμβάνουν αντικείμενο κατανάλωσης πίστωσης που καταγράφεται από το Ace Data Cloud, όπου το `amount` είναι η πραγματική κατανάλωση αυτής της φοράς, το `currency` είναι η μονάδα μέτρησης και το `list_amount` είναι το ποσό πριν από την έκπτωση (εάν υπάρχει). Η επίσημη βασική τιμή ανάγνωσης cache του Fable 5.1 είναι $0.25/εκατομμύριο Token, ενώ οι βασικές τιμές εγγραφής cache για 5 λεπτά και 1 ώρα είναι αντίστοιχα $12.50 και $20/εκατομμύριο Token· η πραγματική τιμή της πλατφόρμας μετατρέπεται σύμφωνα με την έκπτωση του πακέτου. -Το Claude Messages API υποστηρίζει τον ορισμό προτροπών συστήματος μέσω του πεδίου `system`, για τον καθορισμό της συμπεριφοράς, του ρόλου και του πλαισίου του μοντέλου. +## System prompt -### Παράδειγμα Python +Το Claude Messages API υποστηρίζει τον ορισμό system prompt μέσω του πεδίου `system`, για τον καθορισμό της συμπεριφοράς, του ρόλου και του πλαισίου του μοντέλου. +### Παράδειγμα Python ```python import requests @@ -152,11 +149,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Με τη ρύθμιση της προτροπής `system`, μπορείτε να ελέγξετε με ακρίβεια τον ρόλο και τον τρόπο συμπεριφοράς του Claude. +Με τη ρύθμιση της προτροπής `system`, μπορείτε να ελέγχετε με ακρίβεια τον ρόλο και τον τρόπο συμπεριφοράς του Claude. -## Ροϊκές αποκρίσεις +## Ροϊκή απόκριση -Η διεπαφή υποστηρίζει επίσης ροϊκές αποκρίσεις· ορίστε την παράμετρο `stream` σε `true` για να λάβετε σταδιακή επιστροφή, κάτι που είναι ιδιαίτερα κατάλληλο για την υλοποίηση εμφάνισης χαρακτήρα προς χαρακτήρα σε ιστοσελίδες. +Αυτή η διεπαφή υποστηρίζει επίσης ροϊκές αποκρίσεις. Ορίστε την παράμετρο `stream` σε `true` για να λάβετε ένα αποτέλεσμα που επιστρέφεται σταδιακά, κάτι που είναι ιδιαίτερα κατάλληλο για την υλοποίηση εμφάνισης χαρακτήρα προς χαρακτήρα σε ιστοσελίδες. ### Παράδειγμα Python @@ -186,14 +183,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Οι ροϊκές αποκρίσεις επιστρέφονται σε μορφή Server-Sent Events (SSE), με κάθε γραμμή να έχει το πρόθεμα `event:` και `data:`. Οι τύποι ροϊκών συμβάντων περιλαμβάνουν: +Η ροϊκή απόκριση επιστρέφεται σε μορφή Server-Sent Events (SSE), με κάθε γραμμή να έχει το πρόθεμα `event:` και `data:`. Οι τύποι ροϊκών συμβάντων περιλαμβάνουν: -- `message_start`：Έναρξη μηνύματος, περιλαμβάνει τις βασικές πληροφορίες του μηνύματος και το όνομα του μοντέλου. -- `content_block_start`：Έναρξη μπλοκ περιεχομένου. -- `content_block_delta`：Σταδιακή ενημέρωση μπλοκ περιεχομένου, περιλαμβάνει το νέο παραγόμενο τμήμα κειμένου. -- `content_block_stop`：Λήξη μπλοκ περιεχομένου. -- `message_delta`：Σταδιακή ενημέρωση επιπέδου μηνύματος, περιλαμβάνει `stop_reason` και τις τελικές πληροφορίες `usage`. Η έγκυρη τιμή του `output_tokens_details.thinking_tokens` θα πρέπει να διαβάζεται μόνο από το τελευταίο `message_delta.usage` και να μην αθροίζεται μεταξύ συμβάντων. -- `message_stop`：Λήξη μηνύματος. +- `message_start`: Έναρξη μηνύματος, περιλαμβάνει τις βασικές πληροφορίες του μηνύματος και το όνομα του μοντέλου. +- `content_block_start`: Έναρξη μπλοκ περιεχομένου. +- `content_block_delta`: Σταδιακή ενημέρωση μπλοκ περιεχομένου, περιλαμβάνει το νέο παραγόμενο τμήμα κειμένου. +- `content_block_stop`: Λήξη μπλοκ περιεχομένου. +- `message_delta`: Σταδιακή ενημέρωση σε επίπεδο μηνύματος, περιλαμβάνει τις πληροφορίες `stop_reason` και τις τελικές πληροφορίες `usage`. Η έγκυρη τιμή του `output_tokens_details.thinking_tokens` πρέπει να διαβάζεται μόνο από το τελευταίο `message_delta.usage` και να μην αθροίζεται μεταξύ συμβάντων. +- `message_stop`: Λήξη μηνύματος. Το αποτέλεσμα εξόδου είναι το εξής: @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Όπως φαίνεται, στο ροϊκό αποτέλεσμα, το συμβάν `content_block_delta` περιλαμβάνει το σταδιακά παραγόμενο κείμενο· με τη συνένωση όλων των `text_delta` μπορείτε να λάβετε την πλήρη απάντηση. +Όπως φαίνεται, στη ροϊκή απόκριση το συμβάν `content_block_delta` περιλαμβάνει το σταδιακά παραγόμενο περιεχόμενο κειμένου. Με τη συνένωση όλων των `text_delta` μπορείτε να λάβετε την πλήρη απάντηση. ### Παράδειγμα JavaScript @@ -254,9 +251,9 @@ while (true) { } ``` -## Πολυγυρικός διάλογος +## Συνομιλία πολλαπλών γύρων -Αν θέλετε να ενσωματώσετε λειτουργία πολυγυρικού διαλόγου, πρέπει να τοποθετήσετε εναλλάξ μηνύματα με ρόλους `user` και `assistant` στον πίνακα `messages`, μεταβιβάζοντας μαζί και το προηγούμενο ιστορικό διαλόγου. +Αν θέλετε να ενσωματώσετε λειτουργία συνομιλίας πολλαπλών γύρων, πρέπει να τοποθετήσετε εναλλάξ μηνύματα με ρόλους `user` και `assistant` στον πίνακα `messages`, και να μεταβιβάσετε μαζί το προηγούμενο ιστορικό συνομιλίας. ### Παράδειγμα Python @@ -286,6 +283,7 @@ print(response.json()) ``` Το αποτέλεσμα επιστροφής είναι το εξής: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ print(response.json()) } ``` -Περνώντας το πλήρες ιστορικό συνομιλίας στα `messages`, το Claude μπορεί να παρέχει ακριβείς απαντήσεις με βάση το πλαίσιο. +Με τη μεταβίβαση του πλήρους ιστορικού συνομιλίας στο `messages`, το Claude μπορεί να παρέχει ακριβείς απαντήσεις με βάση το περιβάλλον. -## Μοντέλα βαθιάς σκέψης +## Μοντέλο βαθιάς σκέψης -Το thinking και το thinking summary του Claude είναι δύο διαφορετικές έννοιες: το μοντέλο μπορεί να εκτελεί εσωτερική συλλογιστική, αλλά το API δεν επιστρέφει την αρχική αλυσίδα σκέψης. Όταν χρειάζεται να εμφανιστεί η διαδικασία συλλογισμού, το API επιστρέφει μια επεξεργασμένη σύνοψη. +Το thinking και το thinking summary του Claude είναι δύο διαφορετικές έννοιες: το μοντέλο μπορεί να εκτελεί εσωτερικό συλλογισμό, αλλά το API δεν επιστρέφει την αρχική αλυσίδα σκέψης. Όταν χρειάζεται να παρουσιαστεί η διαδικασία συλλογισμού, το API επιστρέφει μια επεξεργασμένη σύνοψη. -Για τα τρέχοντα μοντέλα συνιστάται η χρήση adaptive thinking και ο έλεγχος της συνολικής επένδυσης συλλογισμού μέσω του `output_config.effort`: +Για το τρέχον μοντέλο συνιστάται η χρήση adaptive thinking και ο έλεγχος της συνολικής επένδυσης συλλογισμού μέσω του `output_config.effort`: ```python import requests @@ -343,7 +341,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Το μπλοκ thinking στην απόκριση έχει την εξής μορφή: +Το μπλοκ thinking στην απόκριση έχει την ακόλουθη μορφή: ```json { @@ -352,27 +350,26 @@ print(response.json()) "signature": "opaque-signature" } ``` - -- Το `display: "summarized"` επιστρέφει μια αναγνώσιμη σύνοψη σκέψης· δεν είναι η αρχική αλυσίδα σκέψης. -- Το `display: "omitted"` επιστρέφει `thinking: ""`, αλλά διατηρεί το opaque `signature` για την υποστήριξη επακόλουθων συνομιλιών. -- Το `display: "updates"` είναι η beta λειτουργία της Anthropic και απαιτεί το `anthropic-beta: thinking-display-updates-2026-08-18`. Ο επίσημος ορισμός είναι ότι αποκρύπτει το κυρίως σώμα της συλλογιστικής και εμφανίζει σύντομες ενημερώσεις προόδου μεταξύ κλήσεων εργαλείων. Η πλατφόρμα μεταβιβάζει αυτήν την παράμετρο και την κεφαλίδα beta όπως είναι και δεν την ξαναγράφει αναγκαστικά σε `summarized`· το πραγματικό περιεχόμενο εξόδου εξαρτάται από την υποστήριξη του επιλεγμένου μοντέλου. -- Τα `thinking`, `output_config`, effort, οι παράμετροι δειγματοληψίας και τα νέα επεκτατικά πεδία μεταβιβάζονται όπως είναι. Η πλατφόρμα δεν διατηρεί απαρίθμηση τιμών ή περιορισμούς συνδυασμών κωδικοποιημένους ανά μοντέλο, ούτε ξαναγράφει αυτόματα τη λειτουργία thinking· το αν γίνονται αποδεκτές αυτές οι παράμετροι κρίνεται από το επιλεγμένο μοντέλο και τα σφάλματα παραμέτρων που επιστρέφει το μοντέλο μεταβιβάζονται στον πελάτη. -- Οι προεπιλεγμένες τιμές display για τα Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 και Opus 4.7 είναι `omitted`· τα Opus 4.6, Sonnet 4.6 και παλαιότερα μοντέλα που υποστηρίζουν thinking χρησιμοποιούν από προεπιλογή `summarized`. -- Το Display επηρεάζει μόνο το περιεχόμενο επιστροφής και την καθυστέρηση ροής, δεν απενεργοποιεί τη συλλογιστική και δεν μειώνει τη χρέωση των thinking token. -- Το αν το thinking ενεργοποιείται από προεπιλογή και η προεπιλεγμένη τιμή display είναι δύο ανεξάρτητα ζητήματα. Τα Opus 5 και Sonnet 5 ενεργοποιούν από προεπιλογή το adaptive thinking· για το Opus 5, η παράλειψη του `thinking` ισοδυναμεί με adaptive και η παράλειψη του `output_config.effort` ισοδυναμεί με `high`. Τα Opus 4.8, 4.7 και 4.6 απαιτούν ρητή ενεργοποίηση. -- Το Thinking και το τελικό κυρίως κείμενο καταναλώνουν μαζί τον προϋπολογισμό εξόδου `max_tokens`. Όταν ο προϋπολογισμός είναι πολύ μικρός, το thinking μπορεί να καταναλώσει το μεγαλύτερο μέρος του ορίου, αφήνοντας το κυρίως κείμενο κενό ή περικομμένο· αυξήστε το `max_tokens` ή χρησιμοποιήστε effort `low` / `medium` για να ελέγξετε την επένδυση συλλογισμού. -- Για μοντέλα που επιτρέπουν την απενεργοποίηση του thinking, μπορείτε να περάσετε `thinking: {"type":"disabled"}`. Νέες λειτουργίες όπως `between_tools` και οι συνδυασμοί effort εξαρτώνται από το επιλεγμένο μοντέλο· η πλατφόρμα δεν τα απορρίπτει εκ των προτέρων με βάση παλιούς κανόνες μοντέλων. -- Ένας σταθερός προϋπολογισμός σκέψης μπορεί να μεταβιβαστεί μέσω του `budget_tokens`· τα νέα μοντέλα συνήθως χρησιμοποιούν `thinking.type=adaptive` και `output_config.effort`. Το αν υποστηρίζονται ο σταθερός προϋπολογισμός ή η απενεργοποίηση της σκέψης εξαρτάται από τις τρέχουσες δυνατότητες του επιλεγμένου μοντέλου. -- Σε συνομιλίες πολλών γύρων και κλήσεις εργαλείων, θα πρέπει να επιστρέφετε αυτούσιο το πλήρες μπλοκ thinking και το signature που επέστρεψε ο assistant· μην τροποποιείτε ούτε δημιουργείτε μόνοι σας signature. -- Η μεταβίβαση παραμέτρων δεν σημαίνει ότι κάθε μοντέλο υποστηρίζει όλες τις λειτουργίες. Οι διαπρωτοκολλιακές κλήσεις εξακολουθούν να απαιτούν μετατροπή και το εύρος υποστήριξης και τα σφάλματα για περιεχόμενο όπως `redacted_thinking` καθορίζονται από την υπηρεσία μοντέλου που επεξεργάζεται πραγματικά το αίτημα. - -Σε αιτήματα ροής, το `summarized` παράγει `thinking_delta`· το `omitted` δεν παράγει `thinking_delta`, διατηρώντας μόνο τον κύκλο ζωής του μπλοκ thinking και το `signature_delta`. +- Το `display: "summarized"` επιστρέφει μια αναγνώσιμη περίληψη της σκέψης· δεν είναι η ακατέργαστη αλυσίδα σκέψης. +- Το `display: "omitted"` επιστρέφει `thinking: ""`, αλλά εξακολουθεί να διατηρεί το opaque `signature` για την υποστήριξη επόμενων συνομιλιών. +- Το `display: "updates"` είναι η beta λειτουργία της Anthropic και απαιτεί το `anthropic-beta: thinking-display-updates-2026-08-18`. Ο επίσημος ορισμός είναι να αποκρύπτει το κυρίως κείμενο της συλλογιστικής και να εμφανίζει σύντομες ενημερώσεις προόδου μεταξύ των κλήσεων εργαλείων. Η πλατφόρμα προωθεί αυτή την παράμετρο και την κεφαλίδα beta όπως είναι, και δεν την ξαναγράφει υποχρεωτικά ως `summarized`· το πραγματικό περιεχόμενο εξόδου εξαρτάται από την υποστήριξη του επιλεγμένου μοντέλου. +- Τα `thinking`, `output_config`, effort, οι παράμετροι δειγματοληψίας και τα πρόσθετα πεδία επέκτασης προωθούνται όπως είναι. Η πλατφόρμα δεν διατηρεί σκληρά κωδικοποιημένες ανά μοντέλο απαριθμήσεις τιμών ή περιορισμούς συνδυασμών, ούτε ξαναγράφει αυτόματα τη λειτουργία thinking· το αν αυτά τα παραμέτρους γίνονται αποδεκτές κρίνεται από το επιλεγμένο μοντέλο, και τα σφάλματα παραμέτρων που επιστρέφει το μοντέλο μεταβιβάζονται στον πελάτη. +- Οι προεπιλεγμένες τιμές display για τα Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 και Opus 4.7 είναι `omitted`· τα Opus 4.6, Sonnet 4.6 και τα παλαιότερα μοντέλα που υποστηρίζουν thinking χρησιμοποιούν από προεπιλογή το `summarized`. +- Το Display επηρεάζει μόνο το επιστρεφόμενο περιεχόμενο και την καθυστέρηση ροής, δεν απενεργοποιεί τη συλλογιστική ούτε μειώνει τη χρέωση των thinking token. +- Το αν το thinking είναι ενεργοποιημένο από προεπιλογή και η προεπιλεγμένη τιμή display είναι δύο ανεξάρτητα ζητήματα. Τα Opus 5, Sonnet 5 ενεργοποιούν από προεπιλογή το adaptive thinking· για το Opus 5, η παράλειψη του `thinking` ισοδυναμεί με adaptive, και η παράλειψη του `output_config.effort` ισοδυναμεί με `high`. Τα Opus 4.8, 4.7 και 4.6 απαιτούν ρητή ενεργοποίηση. +- Το Thinking και το τελικό κυρίως κείμενο μοιράζονται τον προϋπολογισμό εξόδου `max_tokens`. Όταν ο προϋπολογισμός είναι πολύ μικρός, το thinking μπορεί να καταλάβει το μεγαλύτερο μέρος του ορίου, αφήνοντας το κυρίως κείμενο κενό ή περικομμένο· αυξήστε το `max_tokens`, ή χρησιμοποιήστε `low` / `medium` effort για να ελέγξετε την επένδυση στη συλλογιστική. +- Για μοντέλα που επιτρέπουν την απενεργοποίηση του thinking, μπορείτε να περάσετε `thinking: {"type":"disabled"}`. Οι νέες λειτουργίες όπως `between_tools`, καθώς και οι συνδυασμοί effort, εξαρτώνται από το επιλεγμένο μοντέλο· η πλατφόρμα δεν απορρίπτει εκ των προτέρων βάσει παλαιών κανόνων μοντέλων. +- Ένας σταθερός προϋπολογισμός σκέψης μπορεί να περαστεί μέσω του `budget_tokens`· τα νέα μοντέλα συνήθως χρησιμοποιούν `thinking.type=adaptive` και `output_config.effort`. Το αν υποστηρίζεται σταθερός προϋπολογισμός ή απενεργοποίηση της σκέψης εξαρτάται από τις τρέχουσες δυνατότητες του επιλεγμένου μοντέλου. +- Σε συνομιλίες πολλών γύρων και κλήσεις εργαλείων, πρέπει να επιστρέφετε αυτούσιο το πλήρες thinking block και το signature που επιστρέφει ο assistant· μην τροποποιείτε και μη δημιουργείτε μόνοι σας signature. +- Η προώθηση παραμέτρων δεν σημαίνει ότι κάθε μοντέλο υποστηρίζει όλες τις λειτουργίες. Οι κλήσεις μεταξύ πρωτοκόλλων εξακολουθούν να απαιτούν μετατροπή, και το εύρος υποστήριξης και τα σφάλματα για περιεχόμενο όπως το `redacted_thinking` καθορίζονται από την υπηρεσία μοντέλου που πράγματι επεξεργάζεται το αίτημα. + +Στα αιτήματα ροής, το `summarized` παράγει `thinking_delta`· το `omitted` δεν παράγει `thinking_delta`, διατηρεί μόνο τον κύκλο ζωής του thinking block και το `signature_delta`. ## Μοντέλα όρασης -Το Claude υποστηρίζει πολυτροπική είσοδο και μπορεί να επεξεργάζεται ταυτόχρονα κείμενο και εικόνες. Στο Messages API, μπορείτε να χρησιμοποιήσετε τις δυνατότητες όρασης ορίζοντας το `content` σε μορφή πίνακα και περνώντας μπλοκ περιεχομένου εικόνας. +Το Claude υποστηρίζει πολυτροπικές εισόδους και μπορεί να επεξεργάζεται ταυτόχρονα κείμενο και εικόνες. Στο Messages API, μπορείτε να χρησιμοποιήσετε δυνατότητες όρασης ορίζοντας το `content` σε μορφή πίνακα και περνώντας image content blocks. -### Χρήση εικόνων κωδικοποιημένων σε Base64 +### Χρήση εικόνων κωδικοποιημένων με Base64 ```python import base64 @@ -459,6 +456,7 @@ print(response.json()) ``` ### Παράδειγμα cURL + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -492,7 +490,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ ## Έγγραφα και PDF -Τα PDF χρησιμοποιούν το μπλοκ περιεχομένου `document`, υποστηρίζοντας δύο σταθερές πηγές: Base64 και URL. Η πηγή Base64 πρέπει να χρησιμοποιεί `application/pdf`: +Τα PDF χρησιμοποιούν content blocks `document`, υποστηρίζοντας δύο σταθερές πηγές: Base64 και URL. Οι πηγές Base64 πρέπει να χρησιμοποιούν `application/pdf`: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -Η πηγή URL γράφεται ως `{"type":"url","url":"https://example.com/report.pdf"}`. Το `document` υποστηρίζει επίσης το `text/plain` και την πηγή `content` που αποτελείται από μπλοκ text/image· τα προαιρετικά πεδία περιλαμβάνουν `title`, `context` και `citations`. Η πηγή `file_id` του Files API ανήκει σε ανεξάρτητη beta λειτουργία και δεν περιλαμβάνεται στο σταθερό συμβόλαιο αυτής της διεπαφής. +Η πηγή URL γράφεται ως `{"type":"url","url":"https://example.com/report.pdf"}`. Το `document` υποστηρίζει επίσης `text/plain` και πηγές `content` που αποτελούνται από text/image blocks· τα προαιρετικά πεδία περιλαμβάνουν `title`, `context` και `citations`. Η πηγή `file_id` του Files API αποτελεί ανεξάρτητη beta λειτουργία και δεν περιλαμβάνεται στο σταθερό συμβόλαιο αυτής της διεπαφής. -## Προσωρινή αποθήκευση προτροπών +## Cache προτροπών -Το ανώτατου επιπέδου `cache_control` τοποθετεί αυτόματα το σημείο διακοπής της προσωρινής αποθήκευσης στο τελευταίο μπλοκ που μπορεί να αποθηκευτεί προσωρινά: +Το κορυφαίο `cache_control` τοποθετεί αυτόματα το σημείο διακοπής της cache στο τελευταίο block που μπορεί να αποθηκευτεί στην cache: ```python payload = { @@ -536,12 +534,11 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Όταν απαιτείται ακριβής έλεγχος θέσης, μπορείτε επίσης να γράψετε το ίδιο `cache_control` σε μπλοκ περιεχομένου text, image, document, tool_use, tool_result ή σε ορισμούς εργαλείων. Το `ttl` υποστηρίζει `5m` (προεπιλογή) και `1h`· παρακαλούμε να κρίνετε την εγγραφή και την επιτυχία της προσωρινής μνήμης μέσω των `usage.cache_creation_input_tokens` και `usage.cache_read_input_tokens`. -Όταν απαιτείται ακριβής έλεγχος της θέσης, μπορείτε επίσης να γράψετε το ίδιο `cache_control` σε μπλοκ περιεχομένου text, image, document, tool_use, tool_result ή σε ορισμό εργαλείου. Το `ttl` υποστηρίζει `5m` (προεπιλογή) και `1h`· χρησιμοποιήστε τα `usage.cache_creation_input_tokens` και `usage.cache_read_input_tokens` για να προσδιορίσετε την εγγραφή και την επιτυχία εύρεσης στην προσωρινή αποθήκευση. - -Όταν η απόκριση παρέχει `usage.cache_creation`, τότε `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Εάν το `cache_creation` είναι `null` ή παραλείπεται, αυτό υποδηλώνει ότι υπάρχει μόνο η συνολική ποσότητα εγγραφής στην προσωρινή αποθήκευση, χωρίς έγκυρη ανάλυση TTL· σε αυτήν την περίπτωση, μην θεωρείτε κανένα bucket ως γνωστό 0, ενώ η χρέωση και τα σύνολα εξακολουθούν να βασίζονται στο συγκεντρωτικό πεδίο. +Όταν η απόκριση παρέχει `usage.cache_creation`, ισχύει ότι `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Εάν το `cache_creation` είναι `null` ή παραλείπεται, σημαίνει ότι υπάρχει μόνο το συνολικό ποσό εγγραφής στην προσωρινή μνήμη, χωρίς επίσημη ανάλυση TTL· σε αυτήν την περίπτωση, μην θεωρείτε κανέναν bucket ως γνωστό 0, και η χρέωση και τα σύνολα εξακολουθούν να βασίζονται στο aggregate πεδίο. -Παράδειγμα επιστρεφόμενου αποτελέσματος: +Παράδειγμα αποτελέσματος επιστροφής: ```json { @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Όταν το μοντέλο αποφασίσει να καλέσει ένα εργαλείο, το `content` στο επιστρεφόμενο αποτέλεσμα θα περιλαμβάνει ένα μπλοκ περιεχομένου τύπου `tool_use`: +Όταν το μοντέλο αποφασίσει να καλέσει ένα εργαλείο, το `content` στο αποτέλεσμα επιστροφής θα περιέχει ένα μπλοκ περιεχομένου τύπου `tool_use`: ```json { @@ -640,7 +637,7 @@ print(response.json()) } ``` -Σημειώστε ότι το `stop_reason` είναι `tool_use`, υποδεικνύοντας ότι το μοντέλο χρειάζεται να καλέσει το εργαλείο. Αφού λάβετε αυτό το αποτέλεσμα, πρέπει να εκτελέσετε τη συνάρτηση του εργαλείου και να επιστρέψετε το αποτέλεσμα στο μοντέλο με τη μορφή `tool_result`: +Σημειώστε ότι το `stop_reason` είναι `tool_use`, υποδεικνύοντας ότι το μοντέλο πρέπει να καλέσει το εργαλείο. Αφού λάβετε αυτό το αποτέλεσμα, πρέπει να εκτελέσετε τη συνάρτηση εργαλείου και να επιστρέψετε το αποτέλεσμα στο μοντέλο με τη μορφή `tool_result`: ```python payload = { @@ -688,36 +685,37 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Το μοντέλο θα δημιουργήσει την τελική απόκριση φυσικής γλώσσας με βάση το αποτέλεσμα που επιστρέφει το εργαλείο. +Το μοντέλο θα δημιουργήσει την τελική απάντηση σε φυσική γλώσσα βάσει του αποτελέσματος που επιστρέφει το εργαλείο. ## Διαφορές από το Chat Completion API -Το Ace Data Cloud παρέχει ταυτόχρονα δύο μορφές Claude API, με τις κύριες διαφορές τους να είναι οι εξής: +Το Ace Data Cloud παρέχει ταυτόχρονα δύο μορφές Claude API, και οι κύριες διαφορές μεταξύ τους είναι οι ακόλουθες: + +Το `usage.input_tokens` του Messages API υποδηλώνει μόνο μη αποθηκευμένες εισόδους, ενώ τα `cache_read_input_tokens` και `cache_creation_input_tokens` είναι ανεξάρτητοι κάδοι χρέωσης· και τα τρία υπολογίζονται ξεχωριστά στις αντίστοιχες τιμές. -Το `usage.input_tokens` του Messages API αντιπροσωπεύει μόνο μη αποθηκευμένες εισόδους, ενώ τα `cache_read_input_tokens` και `cache_creation_input_tokens` είναι ανεξάρτητα buckets χρέωσης· και τα τρία υπολογίζονται ξεχωριστά στις αντίστοιχες τιμές. | Χαρακτηριστικό | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| Μορφή | Εγγενής μορφή Anthropic | Συμβατή μορφή OpenAI | -| Προτροπή συστήματος | Ανεξάρτητο πεδίο `system` | Μεταδίδεται μέσω του `role: "system"` στα `messages` | -| Δομή απόκρισης | Πίνακας `content` (υποστηρίζει πολλαπλούς τύπους) | Πίνακας `choices` (περιλαμβάνει `message`) | -| Μορφή ροής | Συμβάντα SSE (πολλαπλοί τύποι συμβάντων) | Γραμμές SSE `data` | -| Βαθιά σκέψη | Εγγενές `thinking` και `output_config.effort` | Προεπιλεγμένη στρατηγική μοντέλου και συμβατές παράμετροι | -| Κλήση εργαλείων | Εγγενές `tools` + `input_schema` | Μορφή `tools` συμβατή με OpenAI | +| Μορφή | Εγγενής μορφή Anthropic | Μορφή συμβατή με OpenAI | +| Προτροπή συστήματος | Ανεξάρτητο πεδίο `system` | Μεταδίδεται μέσω `role: "system"` στο `messages` | +| Δομή απόκρισης | Πίνακας `content` (υποστηρίζει πολλούς τύπους) | Πίνακας `choices` (περιλαμβάνει `message`) | +| Μορφή ροής | Συμβάντα SSE (πολλοί τύποι συμβάντων) | Γραμμές SSE `data` | +| Βαθιά σκέψη | Εγγενή `thinking` και `output_config.effort` | Προεπιλεγμένη στρατηγική μοντέλου και συμβατές παράμετροι | +| Κλήση εργαλείων | Εγγενή `tools` + `input_schema` | Μορφή `tools` συμβατή με OpenAI | | Στατιστικά Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Εάν το σύστημά σας έχει ήδη ενσωματωθεί με API μορφής OpenAI, μπορείτε να χρησιμοποιήσετε το Chat Completion API για απρόσκοπτη εναλλαγή. Εάν χρειάζεστε να χρησιμοποιήσετε όλες τις εγγενείς δυνατότητες του Claude, συνιστάται να χρησιμοποιήσετε το Messages API. +Εάν το σύστημά σας έχει ήδη ενσωματωθεί με API μορφής OpenAI, μπορείτε να χρησιμοποιήσετε το Chat Completion API για απρόσκοπτη μετάβαση. Εάν χρειάζεστε να χρησιμοποιήσετε όλες τις εγγενείς δυνατότητες του Claude, συνιστάται να χρησιμοποιήσετε το Messages API. -## Διαχείριση σφαλμάτων +## Χειρισμός σφαλμάτων -Οι αποκρίσεις σφαλμάτων των δημόσιων διεπαφών χρησιμοποιούν το envelope της πλατφόρμας Ace Data Cloud: το `error.code` είναι ένας σταθερός κωδικός σφάλματος, το `error.message` είναι η περιγραφή και το `trace_id` χρησιμοποιείται για τη διερεύνηση αιτημάτων. Οι συνήθεις καταστάσεις HTTP περιλαμβάνουν: +Οι αποκρίσεις σφαλμάτων του δημόσιου interface χρησιμοποιούν το envelope της πλατφόρμας Ace Data Cloud: το `error.code` είναι σταθερός κωδικός σφάλματος, το `error.message` είναι η περιγραφή και το `trace_id` χρησιμοποιείται για διερεύνηση αιτημάτων. Οι συνήθεις καταστάσεις HTTP περιλαμβάνουν: -- `400`: Οι παράμετροι αιτήματος ή το περιεχόμενο πρωτοκόλλου δεν είναι έγκυρα. +- `400`: Οι παράμετροι αιτήματος ή το περιεχόμενο πρωτοκόλλου είναι μη έγκυρα. - `401`: Το διακριτικό εξουσιοδότησης είναι μη έγκυρο, λείπει ή έχει λήξει. -- `403`: Η πρόσβαση απαγορεύεται, το υπόλοιπο είναι ανεπαρκές ή το όριο χρήσης είναι περιορισμένο. +- `403`: Η πρόσβαση απαγορεύεται, το υπόλοιπο είναι ανεπαρκές ή η ποσόστωση είναι περιορισμένη. - `404`: Το API ή το μοντέλο δεν υπάρχει. - `413`: Το σώμα του αιτήματος είναι υπερβολικά μεγάλο. - `429`: Πάρα πολλά αιτήματα. -- `500` / `503` / `504`: Σφάλμα υπηρεσίας, προσωρινά μη διαθέσιμη ή χρονικό όριο επεξεργασίας. +- `500` / `503` / `504`: Σφάλμα υπηρεσίας, προσωρινή μη διαθεσιμότητα ή χρονικό όριο επεξεργασίας. ### Παράδειγμα απόκρισης σφάλματος @@ -731,8 +729,7 @@ print(response.json()) } ``` -Αυτή η δομή σφάλματος είναι το συμβόλαιο χρόνου εκτέλεσης του Ace Data Cloud και δεν ισοδυναμεί με το επίσημο envelope σφαλμάτων της Anthropic· παρακαλούμε να γίνεται χειρισμός βάσει της κατάστασης HTTP και του `error.code`. +Αυτή η δομή σφάλματος είναι το συμβόλαιο χρόνου εκτέλεσης του Ace Data Cloud και δεν ισοδυναμεί με το επίσημο envelope σφαλμάτων του Anthropic· παρακαλούμε να το χειρίζεστε σύμφωνα με την κατάσταση HTTP και το `error.code`. ## Συμπέρασμα - -Μέσω αυτού του εγγράφου, έχετε ήδη μάθει πώς να χρησιμοποιείτε το Claude Messages API για να καλείτε τις λειτουργίες συνομιλίας του Claude σε εγγενή μορφή Anthropic. Το Messages API υποστηρίζει πλούσιες λειτουργίες όπως βασική συνομιλία, προτροπές συστήματος, αποκρίσεις ροής, συνομιλίες πολλαπλών γύρων, βαθιά σκέψη, οπτική κατανόηση, PDF, προσωρινή αποθήκευση προτροπών και κλήση εργαλείων. Εάν έχετε οποιεσδήποτε ερωτήσεις, επικοινωνήστε με την ομάδα τεχνικής υποστήριξής μας ανά πάσα στιγμή. +Μέσω αυτού του εγγράφου, έχετε ήδη μάθει πώς να χρησιμοποιείτε το Claude Messages API για να καλέσετε τις λειτουργίες συνομιλίας του Claude στη μορφή Anthropic Native. Το Messages API υποστηρίζει πλούσιες λειτουργίες όπως βασική συνομιλία, προτροπές συστήματος, αποκρίσεις ροής, συνομιλίες πολλαπλών γύρων, βαθιά σκέψη, οπτική κατανόηση, PDF, προσωρινή αποθήκευση προτροπών και κλήσεις εργαλείων. Εάν έχετε οποιεσδήποτε ερωτήσεις, μη διστάσετε να επικοινωνήσετε με την ομάδα τεχνικής υποστήριξής μας. diff --git a/en/guides/claude/claude_messages.mdx b/en/guides/claude/claude_messages.mdx index 42026952..22fe8141 100644 --- a/en/guides/claude/claude_messages.mdx +++ b/en/guides/claude/claude_messages.mdx @@ -3,9 +3,9 @@ title: "Claude Messages API Application and Usage" description: "Claude AI integration guide - Ace Data Cloud" --- -Anthropic Claude is a very powerful AI conversation system. Simply enter a prompt, and it can generate fluent and natural responses in just a few seconds. Claude Messages API is Anthropic's official native API format. Unlike the OpenAI-compatible format (Chat Completion), it uses Anthropic's own request and response structure, enabling better utilization of Claude's unique capabilities, such as multimodal content input, tool calling, extended thinking, and other advanced features. +Anthropic Claude is a very powerful AI conversational system that can generate fluent and natural responses in just a few seconds by simply entering a prompt. Claude Messages API is Anthropic's official native API format. Unlike the OpenAI-compatible format (Chat Completion), it uses Anthropic's own request and response structure, enabling better use of Claude's unique capabilities, such as multimodal content input, tool calling, extended thinking, and other advanced features. -This document mainly introduces the usage process of Claude Messages API operations. With it, we can use native interfaces consistent with Anthropic's official ones to call Claude's conversation capabilities. +This document mainly introduces the usage process of Claude Messages API operations. With it, we can use native interfaces consistent with Anthropic's official ones to invoke Claude's conversational capabilities. ## Application Process @@ -13,32 +13,31 @@ To use Claude Messages API, first go to the [Ace Data Cloud Console](https://pla ![](https://cdn.acedata.cloud/dvc3cg.jpg) -If you have not yet logged in or registered, you will be automatically redirected to the login page to register and log in, and will automatically return to the current page after completion. +If you have not yet logged in or registered, you will be automatically redirected to the login page and invited to register and log in. After completion, you will automatically return to the current page. -**One API Token can call all platform services; there is no need to apply separately for each service.** Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the [Console](https://platform.acedata.cloud/console/coin). +**One API Token can invoke all platform services; there is no need to apply separately for each service.** Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the [Console](https://platform.acedata.cloud/console/coin). -> 📘 Complete documentation: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) +> 📘 Full documentation: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Basic Usage -The request path for Claude Messages API is `/v1/messages`, consistent with Anthropic's official API. We need to provide at least three required parameters: +The request path for Claude Messages API is `/v1/messages`, consistent with the official Anthropic API. We need to provide at least three required parameters: -- `model`: Select the Claude model to use. `claude-opus-5-5` is available only through the Messages API, supports 1 million Token context, a maximum output of 128K Tokens, and always enables adaptive thinking. The latest flagship is `claude-fable-5-1` (1 million Token context, maximum output of 128K Tokens); the original `claude-fable-5` remains compatible and retained. `claude-sonnet-5-5` has joined the native Messages series interface, supports image input and adaptive thinking; its official reference prices for input, output, and cache reads are 2, 10, and 0.20 USD per million Tokens respectively. -- `messages`: The array of input messages. Each message contains `role` (role) and `content` (content), where `role` supports `user` and `assistant`. +- `model`: Select the Claude model to use. `claude-opus-5-5` is available only through the Messages API, supports 1 million Token context, a maximum output of 128K Tokens, and always enables adaptive thinking. The latest flagship is `claude-fable-5-1` (1 million Token context, maximum output of 128K Tokens); the original `claude-fable-5` is still retained for compatibility. `claude-sonnet-5-5` has joined the native Messages series interface, supports image input and adaptive thinking; its official reference prices for input, output, and cache reads are 2, 10, and 0.20 USD per million Tokens, respectively. +- `messages`: An array of input messages. Each message contains `role` (role) and `content` (content), where `role` supports `user` and `assistant`. - `max_tokens`: The maximum number of output tokens, used to limit the length of a single response. Common optional parameters: - `system`: System prompt, used to set the model's behavior and role. -- `temperature`: Generation randomness, between 0 and 1. The larger the value, the more divergent the response. +- `temperature`: Generation randomness, between 0 and 1. The higher the value, the more divergent the response. - `stream`: Whether to use streaming responses. Setting it to `true` enables a word-by-word return effect. - `stop_sequences`: Custom stop sequences. The model stops generating when it encounters these texts. -- `top_p`: Nucleus sampling parameter, used with temperature to control generation randomness. +- `top_p`: Nucleus sampling parameter, used together with temperature to control generation randomness. - `top_k`: Sample only from the K options with the highest probabilities. - `tools`: Tool definitions, used to allow the model to call external functions. - `tool_choice`: Controls how the model uses the provided tools. - `cache_control`: Automatically creates a cache breakpoint at the last cacheable content block of the request; it can also be written on a specific content block. -- `metadata`: An optional request metadata object. `metadata.user_id` is a string that can pass a caller-defined user identifier, for example `{"user_id":"example-user-001"}`; it is recommended to use a stable identifier that does not contain personal information. It does not replace `Authorization` authentication and does not need to be included in the `messages` conversation content. ### cURL Example @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -110,24 +107,24 @@ After calling, the returned result is as follows: ``` Description of returned result fields: -- `id`: The unique identifier for this message. + +- `id`: Unique identifier of this message. - `type`: Always `message`. - `role`: Always `assistant`. -- `content`: An array of reply content, where each element contains `type` (such as `text`) and the corresponding content. +- `content`: An array of response content. Each element contains `type` (such as `text`) and the corresponding content. - `model`: The name of the model processing the request. -- `stop_reason`: The reason for stopping. Stable values include `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (the current assistant content can be returned as-is to continue), `refusal`, and `model_context_window_exceeded`. -- `stop_sequence`: If stopped due to a custom stop sequence, displays the matched stop sequence text. -- `stop_details`: When `stop_reason` is `refusal`, may contain the refusal category and explanation. -- `usage`: Token usage statistics. `input_tokens` are uncached input; `cache_creation_input_tokens` and `cache_read_input_tokens` are cache writes and reads respectively; `output_tokens` is the total number of output tokens. If `output_tokens_details.thinking_tokens` is returned, this value is a subset of `output_tokens`; do not add it again when calculating totals or costs. This detail may be `null` or omitted when there is no authoritative count. -- `usage.cache_creation`: Optional cache write TTL details, including `ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens`. When the object exists, the sum of the two equals `cache_creation_input_tokens`; fields being `null` or omitted indicates that the current response has no available TTL breakdown and must not be interpreted as `0`. -- `usage.cost`: Non-streaming responses may include an Ace Data Cloud-recorded credit consumption object, where `amount` is the actual consumption for this request, `currency` is the unit of measurement, and `list_amount` is the pre-discount amount (if any). The official cache-read list price for Fable 5.1 is $0.25/million Tokens, while the list prices for 5-minute and 1-hour cache writes are $12.50 and $20/million Tokens respectively; actual platform pricing is converted according to plan discounts. +- `stop_reason`: The reason for stopping. Stable values include `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (you can return the current assistant content unchanged to continue), `refusal`, and `model_context_window_exceeded`. +- `stop_sequence`: If stopped due to a custom stop sequence, displays the matching stop sequence text. +- `stop_details`: When `stop_reason` is `refusal`, it may contain the refusal category and description. +- `usage`: Token usage statistics. `input_tokens` is uncached input; `cache_creation_input_tokens` and `cache_read_input_tokens` are cache writes and reads respectively; `output_tokens` is the total number of output tokens. If `output_tokens_details.thinking_tokens` is returned, this value is a subset of `output_tokens`; do not add it again when calculating totals or costs. This detail may be `null` or omitted when there is no authoritative count. +- `usage.cache_creation`: Optional cache write TTL details, containing `ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens`. When the object exists, the sum of the two equals `cache_creation_input_tokens`; a field being `null` or omitted means that the current response has no available TTL breakdown and must not be interpreted as `0`. +- `usage.cost`: Non-streaming responses may contain a credit consumption object recorded by Ace Data Cloud, where `amount` is the actual consumption for this request, `currency` is the unit of measurement, and `list_amount` is the amount before discount (if any). The official base price for Fable 5.1 cache reads is $0.25 per million Tokens, while the base prices for 5-minute and 1-hour cache writes are $12.50 and $20 per million Tokens, respectively; actual platform prices are converted according to plan discounts. -## System Prompts +## System Prompt -The Claude Messages API supports setting system prompts through the `system` field, which is used to define the model's behavior, role, and context. +Claude Messages API supports setting a system prompt through the `system` field, used to define the model's behavior, role, and context. ### Python Example - ```python import requests @@ -142,7 +139,7 @@ headers = { payload = { "model": "claude-sonnet-4-20250514", "max_tokens": 1024, - "system": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。", + "system": "You are a professional Chinese translation assistant. Please translate the English input from the user into Chinese.", "messages": [ {"role": "user", "content": "The quick brown fox jumps over the lazy dog."} ] @@ -156,7 +153,7 @@ By setting the `system` prompt, you can precisely control Claude's role and beha ## Streaming Responses -This API also supports streaming responses. Set the `stream` parameter to `true` to obtain progressively returned results, which is highly suitable for implementing word-by-word display on web pages. +This interface also supports streaming responses. Set the `stream` parameter to `true` to receive results progressively, which is highly suitable for implementing character-by-character display on web pages. ### Python Example @@ -188,12 +185,12 @@ for line in response.iter_lines(): Streaming responses are returned in Server-Sent Events (SSE) format, with each line prefixed by `event:` and `data:`. Streaming event types include: -- `message_start`: Message start, containing basic message information and the model name. -- `content_block_start`: Content block start. -- `content_block_delta`: Incremental content block update, containing newly generated text fragments. -- `content_block_stop`: Content block end. -- `message_delta`: Message-level incremental update, containing `stop_reason` and final `usage` information. The authoritative value of `output_tokens_details.thinking_tokens` should only be read from the final `message_delta.usage`; do not accumulate it across events. -- `message_stop`: Message end. +- `message_start`: The message starts, containing the basic message information and model name. +- `content_block_start`: A content block starts. +- `content_block_delta`: An incremental update to a content block, containing newly generated text fragments. +- `content_block_stop`: A content block ends. +- `message_delta`: An incremental update at the message level, containing `stop_reason` and the final `usage` information. The authoritative value of `output_tokens_details.thinking_tokens` should only be read from the last `message_delta.usage`; do not accumulate it across events. +- `message_stop`: The message ends. The output is as follows: @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -It can be seen that the `content_block_delta` events in streaming responses contain progressively generated text content, and the complete reply can be obtained by concatenating all `text_delta` values. +As you can see, the `content_block_delta` events in the streaming response contain progressively generated text content. By concatenating all `text_delta` values, you can obtain the complete reply. ### JavaScript Example @@ -285,7 +282,8 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -The returned result is as follows: +The response is as follows: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ The returned result is as follows: } ``` -By passing the complete conversation history in `messages`, Claude can provide accurate responses based on the context. +By passing the complete conversation history in `messages`, Claude can provide accurate answers based on the context. -## Thinking Models +## Deep Thinking Models Claude's thinking and thinking summary are two different concepts: the model can perform internal reasoning, but the API does not return the original chain of thought. When the reasoning process needs to be displayed, the API returns a processed summary. -Current models are recommended to use adaptive thinking, with overall reasoning effort controlled through `output_config.effort`: +Current models are recommended to use adaptive thinking, and the overall reasoning effort is controlled through `output_config.effort`: ```python import requests @@ -343,7 +341,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -The thinking block in the response looks like: +The thinking block in the response is as follows: ```json { @@ -352,21 +350,20 @@ The thinking block in the response looks like: "signature": "opaque-signature" } ``` - -- `display: "summarized"` returns a readable thinking summary; it is not the original chain of thought. -- `display: "omitted"` returns `thinking: ""`, while retaining the opaque `signature` to support subsequent conversations. -- `display: "updates"` is Anthropic's beta mode and requires `anthropic-beta: thinking-display-updates-2026-08-18`. The official definition is to hide the reasoning body and display brief progress updates between tool calls. The platform passes this parameter and the beta request header through as-is, and does not forcibly rewrite it to `summarized`; the actual output content depends on support from the selected model. +- `display: "summarized"` returns a readable thinking summary; it is not the raw chain of thought. +- `display: "omitted"` returns `thinking: ""`, while still retaining the opaque `signature` to support subsequent conversations. +- `display: "updates"` is Anthropic's beta mode and requires `anthropic-beta: thinking-display-updates-2026-08-18`. The official definition is to hide the reasoning body and display brief progress updates between tool calls. The platform passes through this parameter and beta request header as-is, and will not forcibly rewrite it as `summarized`; the actual output content depends on the support of the selected model. - `thinking`, `output_config`, effort, sampling parameters, and newly added extension fields are passed through as-is. The platform does not maintain hardcoded value enumerations or combination restrictions by model, nor does it automatically rewrite thinking modes; whether these parameters are accepted is determined by the selected model, and parameter errors returned by the model are passed back to the client. - The default display value for Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8, and Opus 4.7 is `omitted`; Opus 4.6, Sonnet 4.6, and earlier models that support thinking use `summarized` by default. -- Display only affects returned content and streaming latency; it does not disable reasoning or reduce billing for thinking tokens. -- Whether thinking is enabled by default and the default display value are two independent issues. Opus 5 and Sonnet 5 enable adaptive thinking by default; for Opus 5, omitting `thinking` is equivalent to adaptive, and omitting `output_config.effort` is equivalent to `high`. Opus 4.8, 4.7, and 4.6 require explicit enabling. -- Thinking and the final body jointly consume the `max_tokens` output budget. When the budget is too small, thinking may consume most of the quota, causing the body to be empty or truncated; increase `max_tokens`, or use `low` / `medium` effort to control reasoning investment. +- Display affects only returned content and streaming latency; it does not disable reasoning or reduce billing for thinking tokens. +- Whether thinking is enabled by default and the display default value are two independent matters. Opus 5 and Sonnet 5 enable adaptive thinking by default; for Opus 5, omitting `thinking` is equivalent to adaptive, and omitting `output_config.effort` is equivalent to `high`. Opus 4.8, 4.7, and 4.6 require explicit enablement. +- Thinking and the final body jointly use the `max_tokens` output budget. When the budget is too small, thinking may consume most of the allowance, causing the body to be empty or truncated; please increase `max_tokens`, or use `low` / `medium` effort to control reasoning investment. - For models that allow thinking to be disabled, you can pass `thinking: {"type":"disabled"}`. New modes such as `between_tools` and effort combinations depend on the selected model; the platform does not reject them in advance based on old model rules. -- A fixed thinking budget can be passed through `budget_tokens`; new models typically use `thinking.type=adaptive` and `output_config.effort`. Whether fixed budgets or disabling thinking are supported depends on the current capabilities of the selected model. +- Fixed thinking budgets can be passed through `budget_tokens`; new models typically use `thinking.type=adaptive` and `output_config.effort`. Whether fixed budgets or disabling thinking are supported depends on the current capabilities of the selected model. - During multi-turn conversations and tool calls, the complete thinking block and signature returned by the assistant should be passed back as-is; do not modify or generate the signature yourself. -- Parameter pass-through does not mean that every model supports all features. Cross-protocol calls still require conversion, and the support scope and errors for content such as `redacted_thinking` are determined by the model service that actually processes the request. +- Parameter pass-through does not mean that every model supports every feature. Cross-protocol calls still require conversion, and the support scope and errors for content such as `redacted_thinking` are determined by the model service that actually processes the request. -In streaming requests, `summarized` produces `thinking_delta`; `omitted` does not produce `thinking_delta`, retaining only the thinking block lifecycle and `signature_delta`. +In streaming requests, `summarized` produces `thinking_delta`; `omitted` does not produce `thinking_delta`, and only retains the thinking block lifecycle and `signature_delta`. ## Vision Models @@ -386,7 +383,7 @@ headers = { "content-type": "application/json" } -# Read and encode the image +# 读取并编码图片 with open("image.png", "rb") as f: image_data = base64.standard_b64encode(f.read()).decode("utf-8") @@ -459,6 +456,7 @@ print(response.json()) ``` ### cURL Example + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -492,7 +490,7 @@ Supported image formats include: `image/jpeg`, `image/png`, `image/gif`, and `im ## Documents and PDFs -PDFs use the `document` content block and support two stable sources: Base64 and URL. A Base64 source must use `application/pdf`: +PDFs use `document` content blocks and support two stable sources: Base64 and URL. Base64 sources must use `application/pdf`: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -A URL source is written as `{"type":"url","url":"https://example.com/report.pdf"}`. `document` also supports `text/plain` and `content` sources composed of text/image blocks; optional fields include `title`, `context`, and `citations`. The Files API `file_id` source is an independent beta feature and is not part of the stable contract of this API. +URL sources are written as `{"type":"url","url":"https://example.com/report.pdf"}`. `document` also supports `text/plain` and `content` sources composed of text/image blocks; optional fields include `title`, `context`, and `citations`. The `file_id` source of the Files API belongs to an independent beta feature and is not part of the stable contract of this interface. ## Prompt Caching -Top-level `cache_control` automatically places the cache breakpoint on the last cacheable block: +Top-level `cache_control` automatically places the cache breakpoint on the final cacheable block: ```python payload = { @@ -536,12 +534,11 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +When precise control over placement is needed, you can also write the same `cache_control` on text, image, document, `tool_use`, `tool_result` content blocks, or tool definitions. `ttl` supports `5m` (default) and `1h`; please use `usage.cache_creation_input_tokens` and `usage.cache_read_input_tokens` to determine cache writes and hits. -When precise position control is needed, the same `cache_control` can also be written on text, image, document, `tool_use`, `tool_result` content blocks, or tool definitions. `ttl` supports `5m` (default) and `1h`; use `usage.cache_creation_input_tokens` and `usage.cache_read_input_tokens` to determine cache writes and hits. - -When the response provides `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. If `cache_creation` is `null` or omitted, it means there is only the total amount of cache writes and no authoritative TTL breakdown; in this case, do not treat either bucket as a known 0, and billing and totals should still be based on the aggregate field. +When the response provides `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. If `cache_creation` is `null` or omitted, it indicates that there is only a total cache write volume and no authoritative TTL breakdown; in this case, do not treat either bucket as a known 0, and billing and totals should still be based on the aggregate fields. -Example response: +Example return result: ```json { @@ -566,7 +563,7 @@ Example response: ## Tool Use -The Claude Messages API natively supports tool use functionality, allowing the model to call your predefined tools/functions when needed. +The Claude Messages API natively supports tool use, allowing the model to call your predefined tools/functions when needed. ### Python Example @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -When the model decides to call a tool, `content` in the response will include a content block of type `tool_use`: +When the model decides to call a tool, `content` in the returned result will include a content block of type `tool_use`: ```json { @@ -688,34 +685,35 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -The model will generate the final natural-language response based on the result returned by the tool. +The model will generate the final natural language response based on the result returned by the tool. ## Differences from the Chat Completion API -Ace Data Cloud provides two Claude API formats simultaneously. Their main differences are as follows: +Ace Data Cloud provides two Claude API formats. The main differences between them are as follows: For the Messages API, `usage.input_tokens` only represents uncached input, while `cache_read_input_tokens` and `cache_creation_input_tokens` are independently billed buckets; all three are calculated separately according to their respective prices. + | Feature | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Format | Anthropic native format | OpenAI-compatible format | | System prompt | Separate `system` field | Passed through `role: "system"` in `messages` | | Response structure | `content` array (supports multiple types) | `choices` array (contains `message`) | | Streaming format | SSE events (multiple event types) | SSE `data` lines | -| Extended thinking | Native `thinking` and `output_config.effort` | Model default strategy and compatible parameters | -| Tool calling | Native `tools` + `input_schema` | OpenAI-compatible `tools` format | +| Extended thinking | Native `thinking` and `output_config.effort` | Model default strategy and compatibility parameters | +| Tool use | Native `tools` + `input_schema` | OpenAI-compatible `tools` format | | Token statistics | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -If your system has already integrated with the OpenAI-format API, you can use the Chat Completion API to switch seamlessly. If you need to use all of Claude's native capabilities, it is recommended to use the Messages API. +If your system has already integrated with an OpenAI-format API, you can use the Chat Completion API for a seamless switch. If you need to use all of Claude's native capabilities, the Messages API is recommended. ## Error Handling -Error responses from public APIs use the Ace Data Cloud platform envelope: `error.code` is the stable error code, `error.message` is the description, and `trace_id` is used for request troubleshooting. Common HTTP statuses include: +Error responses from public APIs use the Ace Data Cloud platform envelope: `error.code` is a stable error code, `error.message` is a description, and `trace_id` is used for request troubleshooting. Common HTTP statuses include: -- `400`: Request parameters or protocol content are invalid. -- `401`: Authorization token is invalid, missing, or expired. -- `403`: Access is forbidden, balance is insufficient, or quota is restricted. -- `404`: API or model does not exist. -- `413`: Request body is too large. +- `400`: Request parameters or protocol content is invalid. +- `401`: The authorization token is invalid, missing, or expired. +- `403`: Access is forbidden, the balance is insufficient, or the quota is restricted. +- `404`: The API or model does not exist. +- `413`: The request body is too large. - `429`: Too many requests. - `500` / `503` / `504`: Service error, temporarily unavailable, or processing timeout. @@ -734,5 +732,4 @@ Error responses from public APIs use the Ace Data Cloud platform envelope: `erro This error structure is the runtime contract of Ace Data Cloud and is not equivalent to Anthropic's official error envelope; please handle it according to the HTTP status and `error.code`. ## Conclusion - -Through this document, you have learned how to use the Claude Messages API to call Claude's conversational capabilities in Anthropic's native format. The Messages API supports rich features such as basic conversations, system prompts, streaming responses, multi-turn conversations, extended thinking, vision understanding, PDFs, prompt caching, and tool calling. If you have any questions, please feel free to contact our technical support team. +Through this document, you have learned how to use the Claude Messages API to invoke Claude's conversation capabilities in Anthropic's native format. The Messages API supports rich features such as basic conversations, system prompts, streaming responses, multi-turn conversations, extended thinking, vision understanding, PDFs, prompt caching, and tool use. If you have any questions, please feel free to contact our technical support team. diff --git a/es/guides/claude/claude_messages.mdx b/es/guides/claude/claude_messages.mdx index 92169995..f0cbe414 100644 --- a/es/guides/claude/claude_messages.mdx +++ b/es/guides/claude/claude_messages.mdx @@ -3,42 +3,41 @@ title: "Solicitud y uso de Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude es un sistema de conversación de IA muy potente; basta con introducir un prompt para generar respuestas fluidas y naturales en solo unos segundos. Claude Messages API es el formato de API nativo oficial de Anthropic; a diferencia del formato compatible con OpenAI (Chat Completion), adopta la estructura propia de solicitudes y respuestas de Anthropic, lo que permite aprovechar mejor las capacidades únicas de Claude, como la entrada de contenido multimodal, la llamada de herramientas, el pensamiento profundo (Extended Thinking) y otras funciones avanzadas. +Anthropic Claude es un sistema de conversación de IA muy potente; basta con introducir un prompt para generar respuestas fluidas y naturales en apenas unos segundos. Claude Messages API es el formato de API nativo oficial de Anthropic. A diferencia del formato compatible con OpenAI (Chat Completion), utiliza la propia estructura de solicitudes y respuestas de Anthropic, lo que permite aprovechar mejor las capacidades únicas de Claude, como la entrada de contenido multimodal, la llamada a herramientas, el pensamiento profundo (Extended Thinking) y otras características avanzadas. Este documento presenta principalmente el proceso de uso de las operaciones de Claude Messages API. Con ella, podemos utilizar una interfaz nativa coherente con la oficial de Anthropic para invocar la función de conversación de Claude. ## Proceso de solicitud -Para utilizar Claude Messages API, primero obtenga su API Token en la [Consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo como respaldo. +Para utilizar Claude Messages API, primero obtenga su API Token en la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo para su uso posterior. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, volverá automáticamente a la página actual. +Si aún no ha iniciado sesión o se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, regresará automáticamente a la página actual. -**Un único API Token permite invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye crédito gratuito para una experiencia sin coste; cuando el crédito sea insuficiente, puede recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin). +**Un API Token permite invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye saldo gratuito, que permite una experiencia sin costo; cuando el saldo sea insuficiente, puede recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin). > 📘 Documentación completa: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Uso básico -La ruta de solicitud de Claude Messages API es `/v1/messages`, coherente con la API oficial de Anthropic. Debemos proporcionar al menos tres parámetros obligatorios: +La ruta de solicitud de Claude Messages API es `/v1/messages`, coherente con la API oficial de Anthropic. Como mínimo, debemos proporcionar tres parámetros obligatorios: -- `model`: selecciona el modelo Claude que se utilizará. `claude-opus-5-5` solo se proporciona a través de Messages API, admite un contexto de 1 millón de Token, una salida máxima de 128K Token y siempre activa el pensamiento adaptativo. El último modelo insignia es `claude-fable-5-1` (contexto de 1 millón de Token, salida máxima de 128K Token); el anterior `claude-fable-5` sigue siendo compatible y se mantiene. `claude-sonnet-5-5` se ha incorporado a la interfaz de la serie nativa Messages, admite entrada de imágenes y pensamiento adaptativo; sus precios de referencia oficiales para entrada, salida y lectura de caché son respectivamente 2, 10 y 0,20 dólares por millón de Token. -- `messages`: el arreglo de mensajes de entrada; cada mensaje contiene `role` (rol) y `content` (contenido), donde `role` admite `user` y `assistant`. -- `max_tokens`: el número máximo de token de salida, utilizado para limitar la longitud de una sola respuesta. +- `model`: seleccione el modelo Claude que desea utilizar. `claude-opus-5-5` solo se proporciona mediante Messages API, admite un contexto de 1 millón de Token, una salida máxima de 128K Token y siempre habilita el pensamiento adaptativo. El buque insignia más reciente es `claude-fable-5-1` (contexto de 1 millón de Token, salida máxima de 128K Token); el anterior `claude-fable-5` sigue conservándose por compatibilidad. `claude-sonnet-5-5` se ha incorporado a la interfaz de la serie nativa Messages, admite entrada de imágenes y pensamiento adaptativo; sus precios de referencia oficiales de entrada, salida y lectura de caché son respectivamente 2, 10 y 0.20 dólares por millón de Token. +- `messages`: matriz de mensajes de entrada, donde cada mensaje incluye `role` (rol) y `content` (contenido), y `role` admite `user` y `assistant`. +- `max_tokens`: número máximo de token de salida, utilizado para limitar la longitud de una sola respuesta. -Parámetros opcionales de uso común: +Parámetros opcionales comunes: - `system`: prompt del sistema, utilizado para establecer el comportamiento y el rol del modelo. -- `temperature`: aleatoriedad de generación, entre 0 y 1; cuanto mayor sea el valor, más dispersa será la respuesta. -- `stream`: si se utiliza respuesta en streaming; establecerlo en `true` permite lograr un efecto de devolución carácter por carácter. +- `temperature`: aleatoriedad de la generación, entre 0 y 1; cuanto mayor sea el valor, más dispersa será la respuesta. +- `stream`: si se utiliza respuesta en streaming; establecerlo en `true` permite lograr un efecto de devolución palabra por palabra. - `stop_sequences`: secuencias de detención personalizadas; el modelo dejará de generar cuando encuentre estos textos. -- `top_p`: parámetro de muestreo nuclear, que controla la aleatoriedad de la generación junto con temperature. -- `top_k`: solo realiza muestreo entre las K opciones con mayor probabilidad. -- `tools`: definición de herramientas, utilizada para permitir que el modelo invoque funciones externas. +- `top_p`: parámetro de muestreo de núcleo, que controla la aleatoriedad de la generación junto con temperature. +- `top_k`: realiza el muestreo solo entre las K opciones con mayor probabilidad. +- `tools`: definición de herramientas, utilizada para permitir que el modelo llame a funciones externas. - `tool_choice`: controla cómo utiliza el modelo las herramientas proporcionadas. - `cache_control`: crea automáticamente un punto de interrupción de caché en el último bloque de contenido almacenable en caché de la solicitud; también puede escribirse en bloques de contenido específicos. -- `metadata`: objeto opcional de metadatos de solicitud. `metadata.user_id` es una cadena de texto que puede transmitir un identificador de usuario personalizado por el llamador, por ejemplo `{"user_id":"example-user-001"}`; se recomienda utilizar un identificador estable que no contenga información personal. No sustituye la autenticación `Authorization` ni necesita escribirse en el contenido de la conversación de `messages`. ### Ejemplo de cURL @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -110,24 +107,24 @@ Después de la llamada, el resultado devuelto es el siguiente: ``` Descripción de los campos del resultado devuelto: -- `id`: el identificador único de este mensaje. + +- `id`: identificador único de este mensaje. - `type`: siempre es `message`. - `role`: siempre es `assistant`. -- `content`: un arreglo de contenido de respuesta, donde cada elemento contiene `type` (como `text`) y el contenido correspondiente. -- `model`: el nombre del modelo que procesa la solicitud. -- `stop_reason`: el motivo de detención. Los valores estables incluyen `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (puede devolver sin cambios el contenido actual de `assistant` para continuar), `refusal` y `model_context_window_exceeded`. +- `content`: matriz de contenido de la respuesta; cada elemento contiene `type` (como `text`) y el contenido correspondiente. +- `model`: nombre del modelo que procesa la solicitud. +- `stop_reason`: motivo de detención. Los valores estables incluyen `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (puede devolver el contenido actual de assistant sin cambios para continuar), `refusal` y `model_context_window_exceeded`. - `stop_sequence`: si se detiene debido a una secuencia de detención personalizada, muestra el texto de la secuencia de detención coincidente. -- `stop_details`: cuando `stop_reason` es `refusal`, puede contener la categoría y la descripción del rechazo. -- `usage`: estadísticas de uso de tokens. `input_tokens` es la entrada no almacenada en caché; `cache_creation_input_tokens` y `cache_read_input_tokens` son, respectivamente, la escritura y la lectura de caché; `output_tokens` es el número total de tokens de salida. Si se devuelve `output_tokens_details.thinking_tokens`, este valor es un subconjunto de `output_tokens`; no lo sume nuevamente al calcular el total o el coste. Este detalle puede ser `null` u omitirse cuando no hay un recuento autorizado. -- `usage.cache_creation`: detalle opcional del TTL de escritura de caché, que contiene `ephemeral_5m_input_tokens` y `ephemeral_1h_input_tokens`. Cuando el objeto existe, la suma de ambos equivale a `cache_creation_input_tokens`; que los campos sean `null` u omitidos indica que la respuesta actual no tiene un desglose de TTL disponible y no debe interpretarse como `0`. -- `usage.cost`: las respuestas no transmitidas pueden contener un objeto de consumo de créditos registrado por Ace Data Cloud, donde `amount` es el consumo real de esta vez, `currency` es la unidad de medida y `list_amount` es el importe antes del descuento (si existe). El precio oficial base de lectura de caché de Fable 5.1 es de $0.25/millón de tokens, y los precios base de escritura de caché de 5 minutos y 1 hora son de $12.50 y $20/millón de tokens, respectivamente; el precio real de la plataforma se convierte según el descuento del plan. +- `stop_details`: cuando `stop_reason` es `refusal`, puede incluir la categoría y la explicación del rechazo. +- `usage`: estadísticas de uso de token. `input_tokens` corresponde a la entrada no almacenada en caché; `cache_creation_input_tokens` y `cache_read_input_tokens` corresponden respectivamente a la escritura y lectura de caché; `output_tokens` es el número total de token de salida. Si se devuelve `output_tokens_details.thinking_tokens`, este valor es un subconjunto de `output_tokens`; no lo sume de nuevo al calcular el total o el costo. Este detalle puede ser `null` u omitirse cuando no haya un recuento autorizado. +- `usage.cache_creation`: detalle opcional de TTL de escritura de caché, que incluye `ephemeral_5m_input_tokens` y `ephemeral_1h_input_tokens`. Cuando el objeto existe, la suma de ambos equivale a `cache_creation_input_tokens`; que el campo sea `null` o se omita indica que la respuesta actual no tiene un desglose de TTL disponible y no debe interpretarse como `0`. +- `usage.cost`: las respuestas sin streaming pueden incluir un objeto de consumo de saldo registrado por Ace Data Cloud, donde `amount` es el consumo real de esta solicitud, `currency` es la unidad de medida y `list_amount` es el importe antes del descuento (si existe). El precio base oficial de lectura de caché de Fable 5.1 es de $0.25/millón de Token, y los precios base de escritura de caché de 5 minutos y 1 hora son respectivamente $12.50 y $20/millón de Token; el precio real de la plataforma se calcula según el descuento del plan. -## Mensaje del sistema +## Prompt del sistema -Claude Messages API admite establecer mensajes del sistema mediante el campo `system`, utilizados para definir el comportamiento, el rol y el contexto del modelo. +Claude Messages API admite establecer prompts del sistema mediante el campo `system`, utilizado para definir el comportamiento, el rol y el contexto del modelo. ### Ejemplo de Python - ```python import requests @@ -152,13 +149,13 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Al configurar el mensaje de `system`, se puede controlar con precisión el rol y el comportamiento de Claude. +Al configurar el prompt de `system`, se puede controlar con precisión el rol y el comportamiento de Claude. ## Respuesta en streaming -Esta interfaz también admite respuestas en streaming; basta con establecer el parámetro `stream` en `true` para obtener un efecto de devolución progresiva, muy adecuado para implementar una visualización carácter por carácter en páginas web. +Esta interfaz también admite respuestas en streaming; establezca el parámetro `stream` en `true` para obtener un efecto de retorno gradual, lo cual es muy adecuado para implementar una visualización carácter por carácter en páginas web. -### Ejemplo de Python +### Ejemplo en Python ```python import requests @@ -186,14 +183,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Las respuestas en streaming se devuelven en formato Server-Sent Events (SSE), y cada línea tiene los prefijos `event:` y `data:`. Los tipos de eventos de streaming incluyen: +La respuesta en streaming se devuelve en formato Server-Sent Events (SSE), y cada línea tiene los prefijos `event:` y `data:`. Los tipos de eventos de streaming incluyen: -- `message_start`: inicio del mensaje, contiene la información básica del mensaje y el nombre del modelo. +- `message_start`: inicio del mensaje, incluye la información básica del mensaje y el nombre del modelo. - `content_block_start`: inicio del bloque de contenido. -- `content_block_delta`: actualización incremental del bloque de contenido, contiene el fragmento de texto recién generado. -- `content_block_stop`: fin del bloque de contenido. -- `message_delta`: actualización incremental a nivel de mensaje, contiene `stop_reason` y la información final de `usage`. El valor autorizado de `output_tokens_details.thinking_tokens` solo debe leerse del último `message_delta.usage`; no debe acumularse entre eventos. -- `message_stop`: fin del mensaje. +- `content_block_delta`: actualización incremental del bloque de contenido, incluye los fragmentos de texto recién generados. +- `content_block_stop`: finalización del bloque de contenido. +- `message_delta`: actualización incremental a nivel de mensaje, incluye la información de `stop_reason` y `usage` final. El valor autorizado de `output_tokens_details.thinking_tokens` solo debe leerse del último `message_delta.usage`; no se debe acumular entre eventos. +- `message_stop`: finalización del mensaje. El efecto de salida es el siguiente: @@ -223,9 +220,9 @@ event: message_stop data: {"type":"message_stop"} ``` -Se puede ver que, en las respuestas en streaming, el evento `content_block_delta` contiene el contenido de texto generado progresivamente; al concatenar todos los `text_delta` se puede obtener la respuesta completa. +Como se puede ver, el evento `content_block_delta` de la respuesta en streaming contiene el contenido de texto generado gradualmente; al concatenar todos los `text_delta` se puede obtener la respuesta completa. -### Ejemplo de JavaScript +### Ejemplo en JavaScript ```javascript const options = { @@ -254,11 +251,11 @@ while (true) { } ``` -## Conversaciones de múltiples turnos +## Conversación de múltiples turnos -Si desea integrar la función de conversación de múltiples turnos, debe organizar alternativamente los mensajes con los roles `user` y `assistant` en el arreglo `messages`, e incluir todo el historial de conversación anterior. +Si desea integrar la función de conversación de múltiples turnos, debe alternar los mensajes con los roles `user` y `assistant` en el arreglo `messages`, y pasar también el historial de conversación anterior. -### Ejemplo de Python +### Ejemplo en Python ```python import requests @@ -286,6 +283,7 @@ print(response.json()) ``` El resultado devuelto es el siguiente: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ El resultado devuelto es el siguiente: } ``` -Al pasar el historial completo de la conversación en `messages`, Claude puede combinar el contexto para proporcionar respuestas precisas. +Al pasar el historial completo de la conversación en `messages`, Claude puede proporcionar respuestas precisas en función del contexto. ## Modelo de razonamiento profundo El thinking y el thinking summary de Claude son dos conceptos diferentes: el modelo puede realizar razonamiento interno, pero la API no devuelve la cadena de pensamiento original. Cuando se necesita mostrar el proceso de razonamiento, la API devuelve un resumen procesado. -Actualmente, se recomienda que los modelos usen adaptive thinking y controlen la inversión total de razonamiento mediante `output_config.effort`: +Actualmente, se recomienda utilizar adaptive thinking con el modelo actual y controlar la inversión total de razonamiento mediante `output_config.effort`: ```python import requests @@ -343,7 +341,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -El bloque thinking en la respuesta tiene la siguiente forma: +El bloque thinking de la respuesta tiene la siguiente forma: ```json { @@ -352,27 +350,26 @@ El bloque thinking en la respuesta tiene la siguiente forma: "signature": "opaque-signature" } ``` - - `display: "summarized"` devuelve un resumen de pensamiento legible; no es la cadena de pensamiento original. -- `display: "omitted"` devuelve `thinking: ""`, pero aún conserva la `signature` opaca para admitir conversaciones posteriores. -- `display: "updates"` es el modo beta de Anthropic, y se debe incluir `anthropic-beta: thinking-display-updates-2026-08-18`. La definición oficial es ocultar el cuerpo del razonamiento y mostrar breves actualizaciones de progreso entre llamadas a herramientas. La plataforma transmite este parámetro y el encabezado de solicitud beta según sus valores originales, y no los reescribe forzosamente como `summarized`; el contenido de salida real depende de la compatibilidad del modelo seleccionado. -- `thinking`, `output_config`, effort, los parámetros de muestreo y los campos de extensión añadidos se transmiten según sus valores originales. La plataforma no mantiene enumeraciones de valores ni restricciones de combinación codificadas por modelo, y tampoco reescribe automáticamente el modo thinking; el modelo seleccionado determina si acepta estos parámetros, y los errores de parámetros devueltos por el modelo se transmitirán al cliente. -- El valor predeterminado de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 y Opus 4.7 es `omitted`; Opus 4.6, Sonnet 4.6 y los modelos anteriores que admiten thinking usan `summarized` de forma predeterminada. -- Display solo afecta al contenido devuelto y a la latencia de streaming, no desactiva el razonamiento ni reduce la facturación de tokens de thinking. +- `display: "omitted"` devuelve `thinking: ""`, pero aún conserva una `signature` opaca para admitir conversaciones posteriores. +- `display: "updates"` es el modo beta de Anthropic y requiere incluir `anthropic-beta: thinking-display-updates-2026-08-18`. La definición oficial es ocultar el cuerpo del razonamiento y mostrar actualizaciones breves de progreso entre llamadas a herramientas. La plataforma transmite este parámetro y el encabezado de solicitud beta según sus valores originales, y no lo reescribe forzosamente como `summarized`; el contenido de salida real depende de la compatibilidad del modelo seleccionado. +- `thinking`, `output_config`, effort, parámetros de muestreo y campos de extensión añadidos se transmiten según sus valores originales. La plataforma no mantiene enumeraciones de valores ni restricciones de combinación codificadas de forma fija por modelo, ni reescribe automáticamente los modos de thinking; el modelo seleccionado determina si acepta estos parámetros, y los errores de parámetros devueltos por el modelo se transmiten al cliente. +- Los valores predeterminados de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 y Opus 4.7 son `omitted`; Opus 4.6, Sonnet 4.6 y los modelos anteriores compatibles con thinking usan `summarized` de forma predeterminada. +- Display solo afecta al contenido devuelto y a la latencia de streaming; no desactiva el razonamiento ni reduce la facturación de tokens de thinking. - Si thinking está habilitado de forma predeterminada y el valor predeterminado de display son dos cuestiones independientes. Opus 5 y Sonnet 5 habilitan adaptive thinking de forma predeterminada; para Opus 5, omitir `thinking` equivale a adaptive, y omitir `output_config.effort` equivale a `high`. Opus 4.8, 4.7 y 4.6 requieren habilitación explícita. -- Thinking y el cuerpo final comparten el presupuesto de salida de `max_tokens`. Cuando el presupuesto es demasiado pequeño, thinking puede ocupar la mayor parte de la cuota, dejando el cuerpo vacío o truncado; aumente `max_tokens`, o use effort `low` / `medium` para controlar la inversión de razonamiento. -- Para los modelos que permiten desactivar thinking, se puede pasar `thinking: {"type":"disabled"}`. Los nuevos modos como `between_tools` y las combinaciones de effort dependen del modelo seleccionado; la plataforma no los rechaza anticipadamente basándose en reglas de modelos antiguas. -- El presupuesto de pensamiento fijo puede pasarse mediante `budget_tokens`; los modelos nuevos suelen usar `thinking.type=adaptive` y `output_config.effort`. Si se admite un presupuesto fijo o desactivar el pensamiento depende de las capacidades actuales del modelo seleccionado. -- En conversaciones de varias rondas y llamadas a herramientas, se debe devolver intacto el bloque thinking completo y la signature devueltos por assistant; no modifique ni genere por su cuenta la signature. -- La transmisión de parámetros no significa que todos los modelos admitan todas las funciones. Las llamadas entre protocolos aún requieren conversión, y el alcance de compatibilidad y los errores de contenido como `redacted_thinking` son determinados por el servicio del modelo que procesa realmente la solicitud. +- Thinking y el cuerpo final comparten el presupuesto de salida de `max_tokens`. Cuando el presupuesto es demasiado pequeño, thinking puede consumir la mayor parte de la cuota, dejando el cuerpo vacío o truncado; aumente `max_tokens` o use effort `low` / `medium` para controlar la inversión de razonamiento. +- Para los modelos que permiten desactivar thinking, se puede pasar `thinking: {"type":"disabled"}`. Los nuevos modos como `between_tools` y las combinaciones de effort dependen del modelo seleccionado; la plataforma no los rechaza por adelantado basándose en reglas de modelos antiguas. +- El presupuesto de pensamiento fijo se puede transmitir mediante `budget_tokens`; los modelos nuevos suelen utilizar `thinking.type=adaptive` y `output_config.effort`. Si se admite un presupuesto fijo o la desactivación del pensamiento depende de las capacidades actuales del modelo seleccionado. +- En conversaciones de múltiples turnos y llamadas a herramientas, se deben devolver sin modificaciones los bloques completos de thinking y signature devueltos por el assistant; no modifique ni genere signatures por su cuenta. +- La transmisión de parámetros no significa que cada modelo admita todas las funciones. Las llamadas entre protocolos aún requieren conversión, y el alcance de compatibilidad y los errores de contenidos como `redacted_thinking` son determinados por el servicio de modelo que procesa realmente la solicitud. -En las solicitudes de streaming, `summarized` genera `thinking_delta`; `omitted` no genera `thinking_delta`, y solo conserva el ciclo de vida del bloque thinking y `signature_delta`. +En las solicitudes de streaming, `summarized` produce `thinking_delta`; `omitted` no produce `thinking_delta`, solo conserva el ciclo de vida del bloque thinking y `signature_delta`. -## Modelo visual +## Modelos visuales -Claude admite entradas multimodales y puede procesar texto e imágenes al mismo tiempo. En la API de Messages, las capacidades visuales se pueden utilizar estableciendo `content` en formato de matriz y pasando bloques de contenido de imagen. +Claude admite entradas multimodales y puede procesar texto e imágenes simultáneamente. En la API de Messages, las capacidades visuales se pueden utilizar estableciendo `content` en formato de matriz y pasando bloques de contenido de imagen. -### Usar imágenes codificadas en Base64 +### Uso de imágenes codificadas en Base64 ```python import base64 @@ -418,7 +415,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### Usar imágenes mediante URL +### Uso de imágenes mediante URL ```python import requests @@ -459,6 +456,7 @@ print(response.json()) ``` ### Ejemplo de cURL + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -488,11 +486,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Los formatos de imagen compatibles incluyen: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Los formatos de imagen admitidos incluyen: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Documentos y PDF -Los PDF utilizan el bloque de contenido `document`, compatible con dos fuentes estables: Base64 y URL. La fuente Base64 debe utilizar `application/pdf`: +Los PDF utilizan el bloque de contenido `document` y admiten dos fuentes estables: Base64 y URL. Las fuentes Base64 deben utilizar `application/pdf`: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -La fuente URL se escribe como `{"type":"url","url":"https://example.com/report.pdf"}`. `document` también admite `text/plain` y fuentes `content` compuestas por bloques text/image; los campos opcionales incluyen `title`, `context` y `citations`. La fuente `file_id` de la API Files pertenece a una función beta independiente y no forma parte del contrato estable de esta interfaz. +La fuente URL se escribe como `{"type":"url","url":"https://example.com/report.pdf"}`. `document` también admite `text/plain` y fuentes `content` compuestas por bloques text/image; los campos opcionales incluyen `title`, `context` y `citations`. La fuente `file_id` de la API de Files pertenece a una función beta independiente y no forma parte del contrato estable de esta interfaz. -## Caché de indicaciones +## Caché de prompts -El `cache_control` de nivel superior coloca automáticamente el punto de interrupción de caché en el último bloque almacenable en caché: +`cache_control` de nivel superior coloca automáticamente el punto de interrupción de caché en el último bloque almacenable en caché: ```python payload = { @@ -536,10 +534,9 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Cuando se requiera un control preciso de la posición, también puede escribir el mismo `cache_control` en bloques de contenido text, image, document, tool_use, tool_result o en definiciones de herramientas. `ttl` admite `5m` (predeterminado) y `1h`; determine la escritura y los aciertos de caché mediante `usage.cache_creation_input_tokens` y `usage.cache_read_input_tokens`. -Cuando se necesita un control preciso de la posición, también se puede escribir el mismo `cache_control` en bloques de contenido text, image, document, tool_use, tool_result o en definiciones de herramientas. `ttl` admite `5m` (predeterminado) y `1h`; utilice `usage.cache_creation_input_tokens` y `usage.cache_read_input_tokens` para determinar las escrituras y los aciertos de caché. - -Cuando la respuesta proporciona `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Si `cache_creation` es `null` u se omite, indica que solo hay un total de escrituras de caché, sin un desglose de TTL autorizado; en este caso, no trate ningún bucket como un 0 conocido, y la facturación y los totales seguirán basándose en el campo agregado. +Cuando la respuesta proporciona `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Si `cache_creation` es `null` o se omite, indica que solo existe el total de escritura de caché y no hay un desglose de TTL autoritativo; en este caso, no considere ningún bucket como un 0 conocido, y la facturación y el total seguirán basándose en el campo agregado. Ejemplo de resultado devuelto: @@ -564,9 +561,9 @@ Ejemplo de resultado devuelto: } ``` -## Llamada a herramientas (Tool Use) +## Llamada de herramientas (Tool Use) -La API de Claude Messages admite de forma nativa la función de llamada a herramientas, lo que permite que el modelo invoque sus herramientas/funciones predefinidas cuando sea necesario. +La API de Mensajes de Claude admite de forma nativa la funcionalidad de llamada de herramientas, lo que permite al modelo llamar a las herramientas/funciones que usted haya predefinido cuando sea necesario. ### Ejemplo en Python @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Cuando el modelo decide llamar a una herramienta, el resultado devuelto incluirá un bloque de contenido de tipo `tool_use` en `content`: +Cuando el modelo decide llamar a una herramienta, el `content` del resultado devuelto incluirá un bloque de contenido de tipo `tool_use`: ```json { @@ -640,7 +637,7 @@ Cuando el modelo decide llamar a una herramienta, el resultado devuelto incluir } ``` -Tenga en cuenta que `stop_reason` es `tool_use`, lo que indica que el modelo necesita llamar a una herramienta. Después de recibir este resultado, debe ejecutar la función de la herramienta y devolver el resultado al modelo en forma de `tool_result`: +Tenga en cuenta que `stop_reason` es `tool_use`, lo que indica que el modelo necesita llamar a una herramienta. Tras recibir este resultado, debe ejecutar la función de la herramienta y devolver el resultado al modelo en forma de `tool_result`: ```python payload = { @@ -688,24 +685,25 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -El modelo generará la respuesta final en lenguaje natural basándose en el resultado devuelto por la herramienta. +El modelo generará una respuesta final en lenguaje natural basándose en el resultado devuelto por la herramienta. + +## Diferencias con la API de Chat Completion -## Diferencias con la API Chat Completion +Ace Data Cloud ofrece simultáneamente dos formatos de API de Claude; las principales diferencias entre ambos son las siguientes: -Ace Data Cloud proporciona simultáneamente dos formatos de API de Claude, cuyas principales diferencias son las siguientes: +El `usage.input_tokens` de la API de Messages solo representa entradas sin caché; `cache_read_input_tokens` y `cache_creation_input_tokens` son buckets de facturación independientes; los tres se calculan por separado según los precios correspondientes. -`usage.input_tokens` de la API Messages solo representa la entrada no almacenada en caché; `cache_read_input_tokens` y `cache_creation_input_tokens` son buckets de facturación independientes; los tres se calcularán por separado según sus precios correspondientes. -| Característica | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +| Característica | API de Messages (`/v1/messages`) | API de Chat Completion (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Formato | Formato nativo de Anthropic | Formato compatible con OpenAI | -| Prompt del sistema | Campo `system` independiente | Se transmite mediante `role: "system"` en `messages` | -| Estructura de respuesta | Array `content` (admite múltiples tipos) | Array `choices` (contiene `message`) | -| Formato de streaming | Eventos SSE (múltiples tipos de eventos) | Líneas SSE `data` | -| Pensamiento profundo | `thinking` nativo y `output_config.effort` | Estrategia predeterminada del modelo y parámetros compatibles | -| Llamada a herramientas | `tools` nativo + `input_schema` | Formato `tools` compatible con OpenAI | -| Estadísticas de Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | +| Mensaje del sistema | Campo `system` independiente | Se transmite mediante `role: "system"` en `messages` | +| Estructura de respuesta | Array `content` (admite varios tipos) | Array `choices` (incluye `message`) | +| Transmisión en streaming | Eventos SSE (varios tipos de eventos) | Líneas SSE `data` | +| Razonamiento profundo | `thinking` nativo y `output_config.effort` | Estrategia predeterminada del modelo y parámetros compatibles | +| Llamada de herramientas | `tools` + `input_schema` nativos | Formato `tools` compatible con OpenAI | +| Estadísticas de tokens | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Si su sistema ya está integrado con una API en formato OpenAI, puede utilizar Chat Completion API para cambiar sin problemas. Si necesita utilizar todas las capacidades nativas de Claude, se recomienda utilizar Messages API. +Si su sistema ya está integrado con una API en formato OpenAI, puede utilizar la API de Chat Completion para realizar una transición fluida. Si necesita utilizar todas las capacidades nativas de Claude, se recomienda utilizar la API de Messages. ## Manejo de errores @@ -714,10 +712,10 @@ Las respuestas de error de la interfaz pública utilizan el envelope de la plata - `400`: Los parámetros de la solicitud o el contenido del protocolo no son válidos. - `401`: El token de autorización no es válido, falta o ha expirado. - `403`: Acceso prohibido, saldo insuficiente o cuota restringida. -- `404`: La API o el modelo no existen. +- `404`: La API o el modelo no existe. - `413`: El cuerpo de la solicitud es demasiado grande. - `429`: Demasiadas solicitudes. -- `500` / `503` / `504`: Error del servicio, no disponible temporalmente o tiempo de procesamiento agotado. +- `500` / `503` / `504`: Error del servicio, no disponible temporalmente o tiempo de espera de procesamiento agotado. ### Ejemplo de respuesta de error @@ -731,8 +729,7 @@ Las respuestas de error de la interfaz pública utilizan el envelope de la plata } ``` -Esta estructura de error es el contrato de tiempo de ejecución de Ace Data Cloud y no equivale al envelope de error oficial de Anthropic; procese según el estado HTTP y `error.code`. +Esta estructura de error es el contrato de tiempo de ejecución de Ace Data Cloud y no equivale al envelope de error oficial de Anthropic; procéselo según el estado HTTP y `error.code`. ## Conclusión - -A través de este documento, ya ha aprendido cómo utilizar Claude Messages API para invocar las funciones de conversación de Claude en el formato nativo de Anthropic. Messages API admite funciones enriquecidas como conversación básica, prompts del sistema, respuestas de streaming, conversaciones de múltiples turnos, pensamiento profundo, comprensión visual, PDF, caché de prompts y llamadas a herramientas. Si tiene alguna pregunta, no dude en contactar a nuestro equipo de soporte técnico. +A través de este documento, ya ha aprendido cómo utilizar la API de Messages de Claude para invocar la funcionalidad de conversación de Claude en el formato nativo de Anthropic. La API de Messages admite funciones enriquecidas como conversación básica, mensajes de sistema, respuestas en streaming, conversaciones de múltiples turnos, razonamiento profundo, comprensión visual, PDF, caché de prompts y llamadas a herramientas. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico. diff --git a/fi/guides/claude/claude_messages.mdx b/fi/guides/claude/claude_messages.mdx index caa1ee5b..ff64f988 100644 --- a/fi/guides/claude/claude_messages.mdx +++ b/fi/guides/claude/claude_messages.mdx @@ -3,42 +3,41 @@ title: "Claude Messages API:n hakeminen ja käyttö" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude on erittäin tehokas AI-keskustelujärjestelmä, joka voi tuottaa sujuvia ja luonnollisia vastauksia vain muutamassa sekunnissa, kun syötät kehotteen. Claude Messages API on Anthropicin virallinen natiivi API-muoto, joka eroaa OpenAI-yhteensopivasta muodosta (Chat Completion) siten, että se käyttää Anthropicin omaa pyyntö- ja vastausrakennetta ja voi hyödyntää paremmin Clauden ainutlaatuisia ominaisuuksia, kuten multimodaalista sisällön syöttöä, työkalukutsuja, syvällistä ajattelua (Extended Thinking) ja muita edistyneitä ominaisuuksia. +Anthropic Claude on erittäin tehokas AI-keskustelujärjestelmä, joka voi tuottaa sujuvia ja luonnollisia vastauksia vain muutamassa sekunnissa syöttämällä kehotteen. Claude Messages API on Anthropicin virallinen natiivi API-muoto, joka eroaa OpenAI-yhteensopivasta muodosta (Chat Completion): se käyttää Anthropicin omaa pyyntö- ja vastausrakennetta, mikä mahdollistaa Clauden ainutlaatuisten kykyjen, kuten multimodaalisen sisällön syötön, työkalukutsujen, syvällisen ajattelun (Extended Thinking) ja muiden edistyneiden ominaisuuksien paremman hyödyntämisen. -Tässä dokumentissa esitellään pääasiassa Claude Messages API -toimintojen käyttöprosessi. Sen avulla voimme käyttää Anthropicin virallista vastaavaa natiivia rajapintaa Clauden keskustelutoimintojen kutsumiseen. +Tässä dokumentissa esitellään pääasiassa Claude Messages API -toimintojen käyttöprosessi. Sen avulla voimme käyttää Anthropicin virallisen kanssa yhteneviä natiiveja rajapintoja Clauden keskustelutoimintojen kutsumiseen. ## Hakuprosessi -Jos haluat käyttää Claude Messages API:a, hanki ensin API Tokenisi [Ace Data Cloud -konsolista](https://platform.acedata.cloud/console/applications) ja pidä se varalla. +Käyttääksesi Claude Messages API:a hae ensin [Ace Data Cloud -konsolista](https://platform.acedata.cloud/console/applications) API Tokenisi ja säilytä se varalla. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Jos et ole vielä kirjautunut sisään tai rekisteröitynyt, sinut ohjataan automaattisesti kirjautumissivulle rekisteröitymään ja kirjautumaan sisään, minkä jälkeen palaat automaattisesti tälle sivulle. +Jos et ole vielä kirjautunut sisään tai rekisteröitynyt, sinut ohjataan automaattisesti kirjautumissivulle rekisteröitymään ja kirjautumaan sisään, minkä jälkeen palaat automaattisesti nykyiselle sivulle. -**Yhdellä API Tokenilla voi kutsua kaikkia alustan palveluita, eikä sitä tarvitse hakea erikseen jokaiselle palvelulle.** Ensimmäisen hakemuksen yhteydessä saat ilmaista käyttökiintiötä maksutonta kokeilua varten; kun kiintiö ei riitä, voit ladata yleissaldoa [konsolissa](https://platform.acedata.cloud/console/coin). +**Yhdellä API Tokenilla voi kutsua kaikkia alustan palveluita, eikä jokaista palvelua tarvitse hakea erikseen.** Ensimmäisestä hakemuksesta annetaan ilmainen käyttökiintiö maksutonta kokeilua varten; kun kiintiö ei riitä, voit ladata yleistä saldoa [konsolissa](https://platform.acedata.cloud/console/coin). > 📘 Täydellinen dokumentaatio: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Peruskäyttö -Claude Messages API:n pyyntöpolku on `/v1/messages`, joka on sama kuin Anthropicin virallisessa API:ssa. Meidän on annettava vähintään kolme pakollista parametria: +Claude Messages API:n pyyntöpolku on `/v1/messages`, mikä vastaa Anthropicin virallista API:a. Meidän on annettava vähintään kolme pakollista parametria: -- `model`: Valitse käytettävä Claude-malli. `claude-opus-5-5` on saatavilla vain Messages API:n kautta, se tukee 1 miljoonan Tokenin kontekstia, enintään 128K Tokenin tulostetta ja ottaa aina käyttöön mukautuvan ajattelun. Uusin lippulaivamalli on `claude-fable-5-1` (1 miljoonan Tokenin konteksti, enintään 128K Tokenin tuloste); alkuperäinen `claude-fable-5` säilyy edelleen yhteensopivana. `claude-sonnet-5-5` on liittynyt natiiviin Messages-sarjan rajapintaan ja tukee kuvasisältöä sekä mukautuvaa ajattelua; sen viralliset viitehinnat syötteelle, tulosteelle ja välimuistin luvulle ovat vastaavasti 2, 10 ja 0,20 Yhdysvaltain dollaria miljoonaa Tokenia kohden. -- `messages`: Syötettyjen viestien taulukko, jossa jokainen viesti sisältää `role`-arvon (rooli) ja `content`-arvon (sisältö); `role` tukee arvoja `user` ja `assistant`. +- `model`: Valitse käytettävä Claude-malli. `claude-opus-5-5` tarjotaan vain Messages API:n kautta, ja se tukee 1 miljoonan Tokenin kontekstia, enintään 128K Tokenin tulostetta sekä ottaa aina käyttöön mukautuvan ajattelun. Uusin lippulaiva on `claude-fable-5-1` (1 miljoonan Tokenin konteksti, enintään 128K Tokenin tuloste); alkuperäinen `claude-fable-5` säilyy edelleen yhteensopivana. `claude-sonnet-5-5` on lisätty natiivien Messages-sarja-rajapintojen joukkoon, ja se tukee kuvan syöttöä sekä mukautuvaa ajattelua; sen viralliset viitehinnat syötölle, tulosteelle ja välimuistiluvulle ovat vastaavasti 2, 10 ja 0,20 Yhdysvaltain dollaria miljoonaa Tokenia kohti. +- `messages`: Syötettyjen viestien taulukko, jossa jokainen viesti sisältää `role`-kentän (rooli) ja `content`-kentän (sisältö), ja `role` tukee arvoja `user` ja `assistant`. - `max_tokens`: Tulostettavien tokenien enimmäismäärä, jota käytetään yksittäisen vastauksen pituuden rajoittamiseen. Yleisesti käytetyt valinnaiset parametrit: - `system`: Järjestelmäkehote, jota käytetään mallin toiminnan ja roolin määrittämiseen. -- `temperature`: Luomisen satunnaisuus, välillä 0–1; mitä suurempi arvo, sitä hajautuneempia vastaukset ovat. -- `stream`: Käytetäänkö suoratoistovastausta; arvon `true` asettaminen mahdollistaa merkkikohtaisen palautusefektin. +- `temperature`: Generoinnin satunnaisuus, välillä 0–1; mitä suurempi arvo, sitä hajautuneempi vastaus. +- `stream`: Käytetäänkö suoratoistovastausta; arvon `true` asettaminen mahdollistaa merkkikohtaisen palautuksen. - `stop_sequences`: Mukautetut pysäytyssekvenssit; malli lopettaa generoinnin kohdatessaan nämä tekstit. - `top_p`: Ydinnäytteenottoparametri, joka yhdessä temperaturen kanssa hallitsee generoinnin satunnaisuutta. - `top_k`: Näytteistää vain K:sta todennäköisimmästä vaihtoehdosta. -- `tools`: Työkalumääritykset, joiden avulla malli voi kutsua ulkoisia funktioita. -- `tool_choice`: Hallitsee, miten malli käyttää tarjottuja työkaluja. +- `tools`: Työkalujen määrittelyt, joiden avulla malli voi kutsua ulkoisia funktioita. +- `tool_choice`: Hallitsee, miten malli käyttää annettuja työkaluja. - `cache_control`: Luo automaattisesti välimuistin katkaisupisteen pyynnön viimeiseen välimuistiin tallennettavaan sisältölohkoon; voidaan myös kirjoittaa tiettyyn sisältölohkoon. -- `metadata`: Valinnainen pyynnön metatieto-objekti. `metadata.user_id` on merkkijono, johon voidaan välittää kutsujan mukautettu käyttäjätunniste, esimerkiksi `{"user_id":"example-user-001"}`; on suositeltavaa käyttää vakaata tunnistetta, joka ei sisällä henkilötietoja. Se ei korvaa `Authorization`-todennusta eikä sitä tarvitse kirjoittaa `messages`-keskustelusisältöön. ### cURL-esimerkki @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -109,25 +106,25 @@ Kutsun jälkeen palautettava tulos on seuraava: } ``` -Palautustuloksen kenttien selitykset: +Palautettavien tuloskenttien selitykset: + - `id`: Tämän viestin yksilöllinen tunniste. - `type`: Aina `message`. - `role`: Aina `assistant`. -- `content`: Vastaussisältötaulukko, jonka jokainen elementti sisältää `type`-kentän (kuten `text`) ja vastaavan sisällön. +- `content`: Vastaussisällön taulukko, jossa jokainen elementti sisältää `type`-kentän (kuten `text`) ja vastaavan sisällön. - `model`: Pyynnön käsittelevän mallin nimi. -- `stop_reason`: Lopetussyy. Vakaat arvot sisältävät `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (voit palauttaa nykyisen assistant-sisällön sellaisenaan jatkaaksesi), `refusal` ja `model_context_window_exceeded`. -- `stop_sequence`: Jos pysäytys johtuu mukautetusta pysäytyssekvenssistä, näyttää vastaavan pysäytyssekvenssin tekstin. -- `stop_details`: Kun `stop_reason` on `refusal`, voi sisältää kieltäytymiskategorian ja kuvauksen. -- `usage`: Tokenien käyttötilastot. `input_tokens` on välimuistiin tallentamaton syöte; `cache_creation_input_tokens` ja `cache_read_input_tokens` ovat vastaavasti välimuistin kirjoitus ja luku; `output_tokens` on kaikkien tulostokenien määrä. Jos palautetaan `output_tokens_details.thinking_tokens`, tämä arvo on `output_tokens`-arvon osajoukko, eikä sitä tule lisätä uudelleen kokonaismäärää tai kustannusta laskettaessa. Tämä erittely voi olla `null` tai puuttua, jos sillä ei ole auktoritatiivista laskentaa. -- `usage.cache_creation`: Valinnainen välimuistikirjoituksen TTL-erittely, joka sisältää `ephemeral_5m_input_tokens` ja `ephemeral_1h_input_tokens`. Kun objekti on olemassa, näiden kahden summa on yhtä suuri kuin `cache_creation_input_tokens`; `null`-arvo tai puuttuva kenttä tarkoittaa, ettei nykyiselle vastaukselle ole saatavilla TTL-erittelyä, eikä sitä voi tulkita arvoksi `0`. -- `usage.cost`: Ei-suoratoistovastaukset voivat sisältää Ace Data Cloudin kirjaaman käyttöhyvityskulutusobjektin, jossa `amount` on tämän kerran todellinen kulutus, `currency` on mittayksikkö ja `list_amount` on summa ennen alennusta (jos sellainen on). Fable 5.1:n virallinen välimuistilukemisen perushinta on $0.25/miljoona tokenia, ja 5 minuutin sekä 1 tunnin välimuistikirjoituksen perushinnat ovat vastaavasti $12.50 ja $20/miljoona tokenia; alustan todellinen hinta muunnetaan pakettialennuksen mukaan. +- `stop_reason`: Lopetussyy. Vakaisiin arvoihin kuuluvat `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (nykyinen assistant-sisältö voidaan palauttaa sellaisenaan jatkamista varten), `refusal` ja `model_context_window_exceeded`. +- `stop_sequence`: Jos lopetus johtuu mukautetusta pysäytyssekvenssistä, näyttää vastaavan pysäytyssekvenssin tekstin. +- `stop_details`: Kun `stop_reason` on `refusal`, voi sisältää kieltäytymisluokan ja kuvauksen. +- `usage`: Tokenien käyttötilastot. `input_tokens` on välimuistittamaton syöte; `cache_creation_input_tokens` ja `cache_read_input_tokens` ovat vastaavasti välimuistin kirjoitus ja luku; `output_tokens` on kaikkien tulostokenien määrä. Jos palautetaan `output_tokens_details.thinking_tokens`, tämä arvo on `output_tokens`-kentän osajoukko, eikä sitä saa lisätä uudelleen kokonaismäärää tai kustannuksia laskettaessa. Tämä erittely voi olla `null` tai puuttua, kun auktoritatiivista laskentaa ei ole. +- `usage.cache_creation`: Valinnainen välimuistin kirjoituksen TTL-erittely, joka sisältää `ephemeral_5m_input_tokens`- ja `ephemeral_1h_input_tokens`-kentät. Kun objekti on olemassa, näiden kahden summa on yhtä suuri kuin `cache_creation_input_tokens`; kentän arvo `null` tai puuttuminen tarkoittaa, ettei nykyisessä vastauksessa ole käytettävissä TTL-erittelyä, eikä sitä voi tulkita arvoksi `0`. +- `usage.cost`: Ei-suoratoistovastaukset voivat sisältää Ace Data Cloudin kirjaaman käyttökiintiön kulutusobjektin, jossa `amount` on tämän kerran todellinen kulutus, `currency` on mittayksikkö ja `list_amount` on summa ennen alennusta (jos sellainen on). Fable 5.1:n virallinen välimuistiluvun perushinta on $0.25/miljoona Tokenia, ja 5 minuutin sekä 1 tunnin välimuistikirjoituksen perushinnat ovat vastaavasti $12.50 ja $20/miljoona Tokenia; alustan todelliset hinnat muunnetaan pakettialennusten mukaisesti. ## Järjestelmäkehote -Claude Messages API tukee järjestelmäkehotteiden määrittämistä `system`-kentän kautta, jota käytetään mallin toiminnan, roolin ja kontekstin määrittelyyn. +Claude Messages API tukee järjestelmäkehotteen asettamista `system`-kentän kautta mallin toiminnan, roolin ja kontekstin määrittämiseksi. ### Python-esimerkki - ```python import requests @@ -152,11 +149,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Asettamalla `system`-kehotteen voit hallita tarkasti Clauden roolia ja toimintatapaa. +Asettamalla `system`-kehote voit hallita tarkasti Clauden roolia ja toimintatapaa. ## Suoratoistovastaus -Tämä rajapinta tukee myös suoratoistovastauksia. Asettamalla `stream`-parametrin arvoksi `true` voit saada vaiheittaisen palautuksen, mikä sopii erinomaisesti merkkikohtaisen näytön toteuttamiseen verkkosivulla. +Tämä rajapinta tukee myös suoratoistovastauksia. Asettamalla `stream`-parametrin arvoksi `true` voit saada asteittain palautuvan tuloksen, mikä sopii erinomaisesti merkkikohtaisen näyttämisen toteuttamiseen verkkosivulla. ### Python-esimerkki @@ -186,16 +183,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Suoratoistovastaus palautetaan Server-Sent Events (SSE) -muodossa, jossa jokainen rivi alkaa etuliitteillä `event:` ja `data:`. Suoratoistotapahtumatyypit sisältävät: +Suoratoistovastaus palautetaan Server-Sent Events (SSE) -muodossa, ja jokainen rivi alkaa etuliitteellä `event:` ja `data:`. Suoratoistotapahtumatyyppeihin kuuluvat: -- `message_start`: Viestin alku, sisältää viestin perustiedot ja mallin nimen. -- `content_block_start`: Sisältölohkon alku. -- `content_block_delta`: Sisältölohkon inkrementaalinen päivitys, sisältää uuden luodun tekstikatkelman. -- `content_block_stop`: Sisältölohkon loppu. -- `message_delta`: Viestitason inkrementaalinen päivitys, sisältää `stop_reason`- ja lopulliset `usage`-tiedot. `output_tokens_details.thinking_tokens`-arvon auktoritatiivinen arvo tulee lukea vain viimeisestä `message_delta.usage`-tapahtumasta, eikä sitä tule kerryttää tapahtumien välillä. -- `message_stop`: Viestin loppu. +- `message_start`: Viesti alkaa ja sisältää viestin perustiedot sekä mallin nimen. +- `content_block_start`: Sisältölohko alkaa. +- `content_block_delta`: Sisältölohkon lisäpäivitys, joka sisältää uuden luodun tekstikatkelman. +- `content_block_stop`: Sisältölohko päättyy. +- `message_delta`: Viestitason lisäpäivitys, joka sisältää `stop_reason`- ja lopulliset `usage`-tiedot. Kohteen `output_tokens_details.thinking_tokens` auktoriteettiarvo tulee lukea vain viimeisestä `message_delta.usage`-kohdasta, eikä sitä tule kerryttää tapahtumien välillä. +- `message_stop`: Viesti päättyy. -Tuloste on seuraava: +Tuloste näyttää seuraavalta: ``` event: message_start @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Kuten voidaan nähdä, suoratoistovastauksen `content_block_delta`-tapahtuma sisältää vaiheittain luodun tekstisisällön, ja yhdistämällä kaikki `text_delta`-osat voidaan saada täydellinen vastaus. +Kuten voidaan nähdä, suoratoistovastauksen `content_block_delta`-tapahtumat sisältävät asteittain luodun tekstisisällön, ja yhdistämällä kaikki `text_delta`-kohdat saadaan täydellinen vastaus. ### JavaScript-esimerkki @@ -256,7 +253,7 @@ while (true) { ## Monikierroksinen keskustelu -Jos haluat ottaa käyttöön monikierroksisen keskustelutoiminnon, sinun on järjestettävä `messages`-taulukossa `user`- ja `assistant`-roolien viestit vuorotellen ja välitettävä samalla aiempi keskusteluhistoria. +Jos haluat käyttää monikierroksisen keskustelun toiminnallisuutta, sinun tulee järjestää `messages`-taulukossa `user`- ja `assistant`-roolien viestit vuorotellen ja välittää aiempi keskusteluhistoria mukana. ### Python-esimerkki @@ -286,6 +283,7 @@ print(response.json()) ``` Palautettu tulos on seuraava: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ Palautettu tulos on seuraava: } ``` -Välittämällä koko keskusteluhistorian `messages`-kentässä Claude voi antaa tarkkoja vastauksia kontekstin perusteella. +Välittämällä koko keskusteluhistorian `messages`-kohdassa Claude voi vastata tarkasti kontekstin perusteella. -## Syvällisen ajattelun mallit +## Syvällisen ajattelun malli -Clauden thinking ja thinking summary ovat kaksi eri käsitettä: malli voi suorittaa sisäistä päättelyä, mutta API ei palauta alkuperäistä ajatusketjua. Kun päättelyprosessi on näytettävä, API palauttaa käsitellyn yhteenvedon. +Clauden thinking ja thinking summary ovat kaksi eri käsitettä: malli voi tehdä sisäistä päättelyä, mutta API ei palauta alkuperäistä ajatusketjua. Kun päättelyprosessi täytyy näyttää, API palauttaa käsitellyn yhteenvedon. -Nykyisille malleille suositellaan adaptive thinkingiä, ja kokonaispäättelypanostusta hallitaan `output_config.effort`-asetuksella: +Nykyiselle mallille suositellaan adaptive thinking -asetusta sekä kokonaispäättelypanoksen hallintaa `output_config.effort`-asetuksella: ```python import requests @@ -343,7 +341,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Vastauksen thinking-lohko näyttää tältä: +Vastauksen thinking-lohko on seuraavanlainen: ```json { @@ -352,25 +350,24 @@ Vastauksen thinking-lohko näyttää tältä: "signature": "opaque-signature" } ``` - - `display: "summarized"` palauttaa luettavan ajatteluyhteenvedon; se ei ole alkuperäinen ajatusketju. -- `display: "omitted"` palauttaa `thinking: ""`-arvon, mutta säilyttää edelleen peitetyn `signature`-arvon myöhempien keskustelujen tukemiseksi. -- `display: "updates"` on Anthropicin beta-tila, joka edellyttää `anthropic-beta: thinking-display-updates-2026-08-18`-otsaketta. Virallinen määritelmä on, että päättelytekstin sisältö piilotetaan ja työkalukutsujen välillä näytetään lyhyitä tilannepäivityksiä. Alusta välittää tämän parametrin ja beta-pyynnön otsakkeen sellaisenaan eikä pakota niiden uudelleenkirjoittamista muotoon `summarized`; todellinen tulostussisältö riippuu valitun mallin tuesta. -- `thinking`, `output_config`, effort, näytteenottoparametrit ja uudet laajennuskentät välitetään sellaisinaan. Alusta ei ylläpidä mallikohtaisesti kovakoodattuja arvoluetteloita tai yhdistelmärajoituksia eikä kirjoita thinking-tilaa automaattisesti uudelleen; valittu malli päättää, hyväksytäänkö nämä parametrit, ja mallin palauttamat parametrivirheet välitetään takaisin asiakkaalle. -- Fable 5.1:n, Fable 5:n, Opus 5:n, Sonnet 5:n, Opus 4.8:n ja Opus 4.7:n display-oletusarvo on `omitted`; Opus 4.6, Sonnet 4.6 ja aiemmat thinkingiä tukevat mallit käyttävät oletuksena `summarized`-arvoa. -- Display vaikuttaa vain palautettavaan sisältöön ja suoratoistoviiveeseen; se ei poista päättelyä käytöstä eikä vähennä thinking-tokenien laskutusta. -- Se, onko thinking oletusarvoisesti käytössä, ja displayn oletusarvo ovat kaksi erillistä kysymystä. Opus 5 ja Sonnet 5 ottavat adaptive thinkingin käyttöön oletusarvoisesti; Opus 5:ssä `thinking`-kentän pois jättäminen vastaa adaptive-tilaa ja `output_config.effort`-kentän pois jättäminen vastaa `high`-arvoa. Opus 4.8, 4.7 ja 4.6 edellyttävät nimenomaista käyttöönottoa. -- Thinking ja lopullinen tekstisisältö kuluttavat yhdessä `max_tokens`-tulostusbudjettia. Jos budjetti on liian pieni, thinking voi kuluttaa suurimman osan kiintiöstä, jolloin tekstisisältö jää tyhjäksi tai katkeaa; kasvata `max_tokens`-arvoa tai käytä `low` / `medium` effort -asetusta päättelypanostuksen hallintaan. -- Malleille, joissa thinkingin voi poistaa käytöstä, voidaan välittää `thinking: {"type":"disabled"}`. Uudet tilat, kuten `between_tools`, sekä effort-yhdistelmät riippuvat valitusta mallista; alusta ei hylkää niitä etukäteen vanhojen mallisääntöjen perusteella. -- Kiinteä ajattelubudjetti voidaan välittää `budget_tokens`-parametrilla; uudet mallit käyttävät yleensä `thinking.type=adaptive`-asetusta ja `output_config.effort`-asetusta. Se, tuetaanko kiinteää budjettia tai ajattelun poistamista käytöstä, riippuu valitun mallin nykyisistä ominaisuuksista. -- Monikierroksisissa keskusteluissa ja työkalukutsuissa assistantin palauttama täydellinen thinking-lohko ja signature on välitettävä takaisin sellaisenaan; älä muokkaa tai luo signaturea itse. -- Parametrien välittäminen ei tarkoita, että jokainen malli tukisi kaikkia toimintoja. Protokollien väliset kutsut edellyttävät edelleen muunnosta, ja sisällön, kuten `redacted_thinking`, tuen laajuuden ja virheet määrittää pyynnön tosiasiallisesti käsittelevä mallipalvelu. +- `display: "omitted"` palauttaa `thinking: ""`, mutta säilyttää edelleen läpinäkymättömän `signature`-arvon myöhempien keskustelujen tueksi. +- `display: "updates"` on Anthropicin beta-tila, ja sen mukana on lähetettävä `anthropic-beta: thinking-display-updates-2026-08-18`. Virallinen määritelmä on, että päättelyteksti piilotetaan ja työkalukutsujen välillä näytetään lyhyitä tilannepäivityksiä. Alusta välittää tämän parametrin ja beta-pyyntöotsikon alkuperäisinä arvoina eikä pakota muuttamaan sitä arvoksi `summarized`; todellinen tulostussisältö riippuu valitun mallin tuesta. +- `thinking`-, `output_config`-, effort-, näytteenottoparametrit ja uudet laajennuskentät välitetään alkuperäisinä arvoina. Alusta ei ylläpidä malleittain kovakoodattuja arvoluetteloita tai yhdistelmärajoituksia eikä automaattisesti kirjoita thinking-tilaa uudelleen; valittu malli päättää, hyväksyykö se nämä parametrit, ja mallin palauttamat parametrivirheet välitetään takaisin asiakkaalle. +- Fable 5.1:n, Fable 5:n, Opus 5:n, Sonnet 5:n, Opus 4.8:n ja Opus 4.7:n display-oletusarvo on `omitted`; Opus 4.6:ssa, Sonnet 4.6:ssa ja vanhemmissa thinkingiä tukevissa malleissa käytetään oletuksena arvoa `summarized`. +- Display vaikuttaa vain palautettavaan sisältöön ja suoratoiston viiveeseen, eikä se poista päättelyä käytöstä tai vähennä thinking-tokenien laskutusta. +- Se, onko thinking oletuksena käytössä, ja display-oletusarvo ovat kaksi erillistä kysymystä. Opus 5 ja Sonnet 5 ottavat adaptive thinkingin oletuksena käyttöön; Opus 5:ssa `thinking`-kentän pois jättäminen vastaa adaptive-tilaa, ja `output_config.effort`-kentän pois jättäminen vastaa arvoa `high`. Opus 4.8, 4.7 ja 4.6 edellyttävät eksplisiittistä käyttöönottoa. +- Thinking ja lopullinen tekstisisältö jakavat yhdessä `max_tokens`-tulostusbudjetin. Kun budjetti on liian pieni, thinking voi käyttää suurimman osan kiintiöstä, jolloin tekstisisältö jää tyhjäksi tai katkaistaan; suurenna `max_tokens`-arvoa tai käytä `low` / `medium` effort -arvoa päättelypanostuksen hallintaan. +- Malleille, joissa thinking voidaan poistaa käytöstä, voidaan välittää `thinking: {"type":"disabled"}`. Uudet tilat, kuten `between_tools`, sekä effort-yhdistelmät riippuvat valitusta mallista; alusta ei hylkää niitä etukäteen vanhojen mallisääntöjen perusteella. +- Kiinteä ajattelubudjetti voidaan välittää `budget_tokens`-kentällä; uudet mallit käyttävät yleensä `thinking.type=adaptive`-asetusta ja `output_config.effort`-asetusta. Kiinteän budjetin tai ajattelun poistamisen tuki määräytyy valitun mallin nykyisten ominaisuuksien mukaan. +- Monikierroksisissa keskusteluissa ja työkalukutsuissa assistantin palauttamat täydelliset thinking-lohkot ja signature tulee lähettää takaisin muuttamattomina; älä muokkaa tai luo signature-arvoa itse. +- Parametrien läpivälitys ei tarkoita, että jokainen malli tukee kaikkia ominaisuuksia. Protokollien väliset kutsut edellyttävät edelleen muunnosta, ja sisällön, kuten `redacted_thinking`, tukialueen ja virheet määrittää pyynnön tosiasiallisesti käsittelevä mallipalvelu. Suoratoistopyynnöissä `summarized` tuottaa `thinking_delta`-arvon; `omitted` ei tuota `thinking_delta`-arvoa, vaan säilyttää vain thinking-lohkon elinkaaren ja `signature_delta`-arvon. ## Visuaaliset mallit -Claude tukee monimuotoista syötettä ja voi käsitellä tekstiä ja kuvia samanaikaisesti. Messages API:ssa visuaalisia ominaisuuksia voi käyttää asettamalla `content` taulukkomuotoon ja välittämällä kuvasisältölohkon. +Claude tukee multimodaalisia syötteitä ja voi käsitellä samanaikaisesti tekstiä ja kuvia. Messages API:ssa visuaalisia ominaisuuksia voidaan käyttää asettamalla `content` taulukkomuotoon ja välittämällä kuvasisältölohkoja. ### Base64-koodattujen kuvien käyttö @@ -459,6 +456,7 @@ print(response.json()) ``` ### cURL-esimerkki + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -488,11 +486,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Tuetut kuvamuodot sisältävät: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Tuettuja kuvamuotoja ovat: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Asiakirjat ja PDF:t -PDF käyttää `document`-sisältölohkoa ja tukee kahta vakaata lähdettä: Base64:ää ja URL:ää. Base64-lähteen on käytettävä `application/pdf`-tyyppiä: +PDF:t käyttävät `document`-sisältölohkoa ja tukevat kahta vakaata lähdettä: Base64:ää ja URL:ää. Base64-lähteen on käytettävä `application/pdf`-tyyppiä: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -URL-lähde kirjoitetaan muodossa `{"type":"url","url":"https://example.com/report.pdf"}`. `document` tukee myös `text/plain`-tyyppiä sekä text/image-lohkoista koostuvaa `content`-lähdettä; valinnaisia kenttiä ovat `title`, `context` ja `citations`. Files API:n `file_id`-lähde kuuluu erilliseen beta-ominaisuuteen eikä tämän rajapinnan vakaaseen sopimukseen. +URL-lähde kirjoitetaan muodossa `{"type":"url","url":"https://example.com/report.pdf"}`. `document` tukee lisäksi `text/plain`-muotoa sekä `content`-lähdettä, joka koostuu text/image-lohkoista; valinnaisia kenttiä ovat `title`, `context` ja `citations`. Files API:n `file_id`-lähde on erillinen beta-ominaisuus, eikä se kuulu tämän rajapinnan vakaaseen sopimukseen. ## Kehotevälimuisti -Ylimmän tason `cache_control` sijoittaa automaattisesti välimuistin katkaisukohdan viimeiseen välimuistiin tallennettavaan lohkoon: +Ylätason `cache_control` sijoittaa välimuistin katkaisukohdan automaattisesti viimeiseen välimuistiin tallennettavaan lohkoon: ```python payload = { @@ -536,10 +534,9 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Kun sijaintia on hallittava tarkasti, sama `cache_control` voidaan kirjoittaa myös text-, image-, document-, tool_use-, tool_result-sisältölohkoihin tai työkalumääritelmiin. `ttl` tukee arvoja `5m` (oletus) ja `1h`; määritä välimuistin kirjoitus ja osuma käyttämällä `usage.cache_creation_input_tokens`- ja `usage.cache_read_input_tokens`-kenttiä. -Kun sijaintia on hallittava tarkasti, saman `cache_control`-määrityksen voi myös kirjoittaa text-, image-, document-, tool_use- tai tool_result-sisältölohkoon tai työkalun määritelmään. `ttl` tukee arvoja `5m` (oletus) ja `1h`; määritä välimuistiin kirjoittaminen ja osumat käyttämällä `usage.cache_creation_input_tokens`- ja `usage.cache_read_input_tokens`-kenttiä. - -Kun vastaus sisältää `usage.cache_creation`-kentän, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Jos `cache_creation` on `null` tai se jätetään pois, se tarkoittaa, että vain välimuistiin kirjoittamisen kokonaismäärä on saatavilla eikä auktoritatiivista TTL-erittelyä ole; tällöin mitään bucketia ei pidä pitää tunnettuna arvona 0, vaan laskutus ja kokonaismäärä perustuvat edelleen aggregate-kenttään. +Kun vastaus tarjoaa `usage.cache_creation`-kentän, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Jos `cache_creation` on `null` tai jätetty pois, se tarkoittaa, että vain välimuistin kirjoituksen kokonaismäärä on saatavilla eikä auktoritatiivista TTL-erittelyä ole; tällöin mitään buckettia ei pidä pitää tunnettuna arvona 0, vaan laskutus ja kokonaismäärä perustuvat edelleen aggregate-kenttään. Palautetun tuloksen esimerkki: @@ -566,7 +563,7 @@ Palautetun tuloksen esimerkki: ## Työkalukutsut (Tool Use) -Claude Messages API tukee natiivisti työkalukutsutoimintoa, jonka avulla malli voi tarvittaessa kutsua ennalta määritettyjä työkalujasi/funktioitasi. +Claude Messages API tukee natiivisti työkalukutsutoimintoa, jonka avulla malli voi tarvittaessa kutsua ennalta määrittämiäsi työkaluja/funktioita. ### Python-esimerkki @@ -640,7 +637,7 @@ Kun malli päättää kutsua työkalua, palautetun tuloksen `content` sisältä } ``` -Huomaa, että `stop_reason` on `tool_use`, mikä osoittaa, että mallin on kutsuttava työkalua. Saatuasi tämän tuloksen sinun on suoritettava työkalufunktio ja palautettava tulos mallille `tool_result`-muodossa: +Huomaa, että `stop_reason` on `tool_use`, mikä tarkoittaa, että mallin on kutsuttava työkalua. Kun olet vastaanottanut tämän tuloksen, sinun on suoritettava työkalufunktio ja palautettava tulos mallille `tool_result`-muodossa: ```python payload = { @@ -694,32 +691,33 @@ Malli luo työkalun palauttaman tuloksen perusteella lopullisen luonnollisen kie Ace Data Cloud tarjoaa samanaikaisesti kahta Claude API -muotoa, joiden tärkeimmät erot ovat seuraavat: -Messages API:n `usage.input_tokens` tarkoittaa vain välimuistiin tallentamatonta syötettä, kun taas `cache_read_input_tokens` ja `cache_creation_input_tokens` ovat erillisiä laskutuksen luokkia; kaikki kolme lasketaan erikseen niitä vastaavien hintojen mukaan. +Messages API:n `usage.input_tokens` tarkoittaa vain välimuistissa olematonta syötettä, ja `cache_read_input_tokens` sekä `cache_creation_input_tokens` ovat itsenäisiä laskutuksen bucketteja; kaikki kolme lasketaan erikseen vastaavien hintojen mukaan. + | Ominaisuus | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Muoto | Anthropicin natiivimuoto | OpenAI-yhteensopiva muoto | -| Järjestelmäkehote | Erillinen `system`-kenttä | Välitetään `messages`-kentässä `role: "system"` | -| Vastausrakenne | `content`-taulukko (tukee useita tyyppejä) | `choices`-taulukko (sisältää `message`-objektin) | -| Suoratoistomuoto | SSE-tapahtumat (useita tapahtumatyyppejä) | SSE `data`-rivit | +| Järjestelmäkehote | Erillinen `system`-kenttä | Välitetään `messages`-kentän `role: "system"` kautta | +| Vastausrakenne | `content`-taulukko (tukee useita tyyppejä) | `choices`-taulukko (sisältää `message`-kentän) | +| Suoratoistomuoto | SSE-tapahtumat (useita tapahtumatyyppejä) | SSE `data` -rivit | | Syvällinen päättely | Natiivi `thinking` ja `output_config.effort` | Mallin oletusstrategia ja yhteensopivuusparametrit | | Työkalukutsut | Natiivi `tools` + `input_schema` | OpenAI-yhteensopiva `tools`-muoto | | Token-tilastot | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Jos järjestelmäsi on jo integroitu OpenAI-muotoiseen APIin, voit käyttää Chat Completion APIa vaihtaaksesi saumattomasti. Jos tarvitset kaikki Clauden natiivit ominaisuudet, on suositeltavaa käyttää Messages APIa. +Jos järjestelmäsi on jo integroitu OpenAI-muotoiseen APIin, voit käyttää Chat Completion APIa saumattomaan vaihtamiseen. Jos sinun on käytettävä kaikkia Clauden natiiveja ominaisuuksia, Messages API:n käyttöä suositellaan. ## Virheenkäsittely -Julkisten rajapintojen virhevastaus käyttää Ace Data Cloud -alustan envelope-rakennetta: `error.code` on vakaa virhekoodi, `error.message` on kuvaus ja `trace_id` käytetään pyynnön selvittämiseen. Yleisiä HTTP-tiloja ovat: +Julkisen rajapinnan virhevastaus käyttää Ace Data Cloud -alustan envelopea: `error.code` on vakaa virhekoodi, `error.message` on kuvaus ja `trace_id` käytetään pyynnön selvittämiseen. Yleisiä HTTP-tiloja ovat: - `400`: Pyyntöparametrit tai protokollasisältö ovat virheellisiä. - `401`: Valtuutustunnus on virheellinen, puuttuu tai on vanhentunut. -- `403`: Käyttö on kielletty, saldo on riittämätön tai kiintiötä on rajoitettu. +- `403`: Käyttö estetty, saldo ei riitä tai kiintiötä on rajoitettu. - `404`: APIa tai mallia ei ole olemassa. - `413`: Pyyntörunko on liian suuri. - `429`: Pyyntöjä on liikaa. -- `500` / `503` / `504`: Palveluvirhe, tilapäisesti ei käytettävissä tai käsittely aikakatkaistiin. +- `500` / `503` / `504`: Palveluvirhe, tilapäisesti poissa käytöstä tai käsittelyaikakatkaisu. -### Esimerkki virhevastauksesta +### Virhevastausesimerkki ```json { @@ -731,8 +729,7 @@ Julkisten rajapintojen virhevastaus käyttää Ace Data Cloud -alustan envelope- } ``` -Tämä virherakenne on Ace Data Cloudin ajonaikainen sopimus, eikä se vastaa Anthropicin virallista error envelope -rakennetta; käsittele se HTTP-tilan ja `error.code`-arvon mukaan. +Tämä virherakenne on Ace Data Cloudin ajonaikainen sopimus eikä vastaa Anthropicin virallista virhe-envelopea; käsittele se HTTP-tilan ja `error.code`-kentän mukaan. ## Johtopäätös - -Tämän dokumentaation avulla olet oppinut, kuinka Claude Messages APIa käytetään Clauden keskusteluominaisuuksien kutsumiseen Anthropicin natiivimuodossa. Messages API tukee monipuolisia toimintoja, kuten peruskeskustelua, järjestelmäkehotteita, suoratoistovastauksia, monikierroksisia keskusteluja, syvällistä päättelyä, visuaalista ymmärrystä, PDF:iä, kehotevälimuistia ja työkalukutsuja. Jos sinulla on kysyttävää, ota milloin tahansa yhteyttä tekniseen tukitiimiimme. +Tämän dokumentin kautta olet jo oppinut, kuinka käyttää Claude Messages APIa Clauden keskusteluominaisuuksien kutsumiseen Anthropicille natiivissa muodossa. Messages API tukee monipuolisia toimintoja, kuten peruskeskusteluja, järjestelmäkehotteita, suoratoistovastauksia, monikierroksisia keskusteluja, syvällistä ajattelua, visuaalista ymmärrystä, PDF-tiedostoja, kehotteiden välimuistitallennusta ja työkalukutsuja. Jos sinulla on kysyttävää, ota milloin tahansa yhteyttä tekniseen tukitiimiimme. diff --git a/fr/guides/claude/claude_messages.mdx b/fr/guides/claude/claude_messages.mdx index 2f2679bc..edf0434d 100644 --- a/fr/guides/claude/claude_messages.mdx +++ b/fr/guides/claude/claude_messages.mdx @@ -3,42 +3,41 @@ title: "Demande et utilisation de l’API Claude Messages" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude est un système de conversation IA très puissant qui peut générer des réponses fluides et naturelles en quelques secondes seulement à partir d’une invite. L’API Claude Messages est le format d’API natif officiel d’Anthropic. Contrairement au format compatible OpenAI (Chat Completion), elle utilise la propre structure de requête et de réponse d’Anthropic, permettant de mieux exploiter les capacités uniques de Claude, telles que l’entrée de contenu multimodal, l’appel d’outils, la réflexion approfondie (Extended Thinking) et d’autres fonctionnalités avancées. +Anthropic Claude est un système de conversation IA très puissant ; il suffit de saisir une invite pour générer une réponse fluide et naturelle en quelques secondes. L’API Claude Messages est le format d’API natif officiel d’Anthropic. Contrairement au format compatible OpenAI (Chat Completion), elle adopte la structure de requête et de réponse propre à Anthropic, ce qui permet de mieux exploiter les capacités uniques de Claude, telles que l’entrée de contenu multimodal, l’appel d’outils, la réflexion approfondie (Extended Thinking) et d’autres fonctionnalités avancées. -Ce document présente principalement le processus d’utilisation des opérations de l’API Claude Messages. Grâce à elle, nous pouvons utiliser une interface native cohérente avec celle d’Anthropic officielle pour appeler les fonctionnalités conversationnelles de Claude. +Ce document présente principalement le processus d’utilisation de l’API Claude Messages. Grâce à elle, nous pouvons utiliser une interface native cohérente avec celle d’Anthropic officiel pour appeler les fonctionnalités de conversation de Claude. ## Processus de demande -Pour utiliser l’API Claude Messages, rendez-vous d’abord sur la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) afin d’obtenir votre API Token et conservez-le pour une utilisation ultérieure. +Pour utiliser l’API Claude Messages, récupérez d’abord votre API Token depuis la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications), et conservez-le pour une utilisation ultérieure. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion afin de vous inviter à vous inscrire et à vous connecter. Une fois terminé, vous reviendrez automatiquement sur la page actuelle. +Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion qui vous invitera à vous inscrire et à vous connecter ; une fois cela terminé, vous reviendrez automatiquement sur la page actuelle. -**Un seul API Token permet d’appeler tous les services de la plateforme, sans devoir en demander un séparément pour chaque service.** La première demande offre un crédit gratuit permettant une expérience gratuite ; lorsque le crédit est insuffisant, vous pouvez recharger votre solde général dans la [console](https://platform.acedata.cloud/console/coin). +**Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin d’en demander un séparément pour chaque service.** La première demande offre un quota gratuit, permettant une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger votre solde universel dans la [console](https://platform.acedata.cloud/console/coin). -> 📘 Documentation complète : [API Claude Messages →](https://platform.acedata.cloud/documents/claude-messages) +> 📘 Documentation complète : [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Utilisation de base Le chemin de requête de l’API Claude Messages est `/v1/messages`, identique à celui de l’API officielle d’Anthropic. Nous devons fournir au minimum trois paramètres obligatoires : -- `model` : sélectionne le modèle Claude à utiliser. `claude-opus-5-5` est uniquement disponible via l’API Messages, prend en charge un contexte d’un million de Token, une sortie maximale de 128K Token, et active toujours la réflexion adaptative. Le dernier modèle phare est `claude-fable-5-1` (contexte d’un million de Token, sortie maximale de 128K Token) ; l’ancien `claude-fable-5` reste compatible et conservé. `claude-sonnet-5-5` a rejoint l’interface de la série Messages native, prend en charge l’entrée d’images et la réflexion adaptative ; ses prix de référence officiels pour l’entrée, la sortie et la lecture du cache sont respectivement de 2, 10 et 0,20 dollars par million de Token. -- `messages` : le tableau des messages en entrée, chaque message contenant `role` (rôle) et `content` (contenu), où `role` prend en charge `user` et `assistant`. -- `max_tokens` : le nombre maximal de token en sortie, utilisé pour limiter la longueur d’une réponse unique. +- `model` : sélectionnez le modèle Claude à utiliser. `claude-opus-5-5` est fourni uniquement via l’API Messages, prend en charge un contexte de 1 million de Token, une sortie maximale de 128K Token, et active toujours la réflexion adaptative. Le dernier modèle phare est `claude-fable-5-1` (contexte de 1 million de Token, sortie maximale de 128K Token) ; l’ancien `claude-fable-5` reste conservé pour la compatibilité. `claude-sonnet-5-5` a rejoint l’interface de la série native Messages, prend en charge l’entrée d’images et la réflexion adaptative ; ses prix de référence officiels pour l’entrée, la sortie et la lecture du cache sont respectivement de 2, 10 et 0,20 dollars par million de Token. +- `messages` : le tableau des messages d’entrée ; chaque message contient `role` (rôle) et `content` (contenu), où `role` prend en charge `user` et `assistant`. +- `max_tokens` : le nombre maximal de tokens de sortie, utilisé pour limiter la longueur d’une réponse unique. -Paramètres optionnels courants : +Paramètres optionnels couramment utilisés : - `system` : l’invite système, utilisée pour définir le comportement et le rôle du modèle. -- `temperature` : le caractère aléatoire de la génération, entre 0 et 1 ; plus la valeur est élevée, plus les réponses divergent. -- `stream` : indique si une réponse en flux est utilisée ; définie sur `true`, elle permet un retour caractère par caractère. +- `temperature` : le caractère aléatoire de la génération, entre 0 et 1 ; plus la valeur est élevée, plus les réponses sont diversifiées. +- `stream` : indique si une réponse en streaming est utilisée ; définie sur `true`, elle permet un retour caractère par caractère. - `stop_sequences` : séquences d’arrêt personnalisées ; le modèle cesse de générer lorsqu’il rencontre ces textes. -- `top_p` : paramètre d’échantillonnage nucléaire, contrôlant le caractère aléatoire de la génération avec temperature. -- `top_k` : échantillonne uniquement parmi les K options ayant les probabilités les plus élevées. +- `top_p` : paramètre d’échantillonnage nucléaire, utilisé avec temperature pour contrôler le caractère aléatoire de la génération. +- `top_k` : échantillonne uniquement parmi les K options ayant la probabilité la plus élevée. - `tools` : définition des outils, utilisée pour permettre au modèle d’appeler des fonctions externes. - `tool_choice` : contrôle la manière dont le modèle utilise les outils fournis. - `cache_control` : crée automatiquement un point d’arrêt de cache au dernier bloc de contenu pouvant être mis en cache dans la requête ; peut également être écrit sur un bloc de contenu spécifique. -- `metadata` : objet de métadonnées de requête facultatif. `metadata.user_id` est une chaîne de caractères et peut transmettre l’identifiant utilisateur personnalisé de l’appelant, par exemple `{"user_id":"example-user-001"}` ; il est recommandé d’utiliser un identifiant stable ne contenant pas d’informations personnelles. Il ne remplace pas l’authentification `Authorization` et n’a pas besoin d’être écrit dans le contenu de conversation de `messages`. ### Exemple cURL @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -110,24 +107,24 @@ Après l’appel, le résultat retourné est le suivant : ``` Description des champs du résultat retourné : -- `id`：l’identifiant unique de ce message. -- `type`：toujours `message`. -- `role`：toujours `assistant`. -- `content`：tableau du contenu de la réponse, chaque élément contenant `type` (tel que `text`) et le contenu correspondant. -- `model`：le nom du modèle qui traite la requête. -- `stop_reason`：la raison de l’arrêt. Les valeurs stables incluent `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (vous pouvez renvoyer tel quel le contenu actuel de l’assistant afin de continuer), `refusal` et `model_context_window_exceeded`. -- `stop_sequence`：si l’arrêt est dû à une séquence d’arrêt personnalisée, affiche le texte de la séquence d’arrêt correspondante. -- `stop_details`：lorsque `stop_reason` vaut `refusal`, peut contenir la catégorie et l’explication du refus. -- `usage`：statistiques d’utilisation des tokens. `input_tokens` correspond à l’entrée non mise en cache ; `cache_creation_input_tokens` et `cache_read_input_tokens` correspondent respectivement à l’écriture et à la lecture du cache ; `output_tokens` correspond au nombre total de tokens de sortie. Si `output_tokens_details.thinking_tokens` est renvoyé, cette valeur est un sous-ensemble de `output_tokens` et ne doit pas être ajoutée une nouvelle fois lors du calcul du total ou du coût. Ce détail peut être `null` ou omis lorsqu’aucun comptage faisant autorité n’est disponible. -- `usage.cache_creation`：détail optionnel du TTL d’écriture du cache, incluant `ephemeral_5m_input_tokens` et `ephemeral_1h_input_tokens`. Lorsque l’objet est présent, la somme des deux est égale à `cache_creation_input_tokens` ; un champ à `null` ou omis indique qu’aucune ventilation TTL n’est disponible pour la réponse actuelle et ne doit pas être interprété comme `0`. -- `usage.cost`：les réponses non diffusées en streaming peuvent inclure un objet de consommation de crédits enregistré par Ace Data Cloud, où `amount` correspond à la consommation réelle de cette requête, `currency` est l’unité de mesure, et `list_amount` est le montant avant remise (le cas échéant). Le prix officiel de base de lecture du cache de Fable 5.1 est de 0,25 $/million de tokens, et les prix de base d’écriture du cache de 5 minutes et 1 heure sont respectivement de 12,50 $ et 20 $/million de tokens ; les prix réels de la plateforme sont convertis selon les remises du forfait. + +- `id` : l’identifiant unique de ce message. +- `type` : toujours `message`. +- `role` : toujours `assistant`. +- `content` : tableau du contenu de la réponse ; chaque élément contient `type` (tel que `text`) et le contenu correspondant. +- `model` : le nom du modèle qui traite la requête. +- `stop_reason` : la raison de l’arrêt. Les valeurs stables incluent `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (le contenu actuel de l’assistant peut être renvoyé tel quel pour continuer), `refusal` et `model_context_window_exceeded`. +- `stop_sequence` : si l’arrêt est dû à une séquence d’arrêt personnalisée, affiche le texte de la séquence d’arrêt correspondante. +- `stop_details` : lorsque `stop_reason` est `refusal`, peut contenir la catégorie du refus et une explication. +- `usage` : statistiques d’utilisation des tokens. `input_tokens` correspond aux entrées non mises en cache ; `cache_creation_input_tokens` et `cache_read_input_tokens` correspondent respectivement à l’écriture et à la lecture du cache ; `output_tokens` est le nombre total de tokens de sortie. Si `output_tokens_details.thinking_tokens` est retourné, cette valeur est un sous-ensemble de `output_tokens` ; ne l’ajoutez pas à nouveau lors du calcul du total ou du coût. Ce détail peut être `null` ou omis lorsqu’aucun comptage faisant autorité n’est disponible. +- `usage.cache_creation` : détail optionnel du TTL d’écriture du cache, contenant `ephemeral_5m_input_tokens` et `ephemeral_1h_input_tokens`. Lorsque l’objet existe, la somme des deux est égale à `cache_creation_input_tokens` ; un champ `null` ou omis indique qu’aucune ventilation TTL n’est disponible dans la réponse actuelle et ne doit pas être interprété comme `0`. +- `usage.cost` : les réponses non streaming peuvent contenir un objet de consommation de quota enregistré par Ace Data Cloud, dans lequel `amount` est la consommation réelle de cette requête, `currency` est l’unité de mesure, et `list_amount` est le montant avant remise (le cas échéant). Le prix de base officiel de lecture du cache pour Fable 5.1 est de 0,25 $/million de Token, et les prix de base d’écriture du cache pour 5 minutes et 1 heure sont respectivement de 12,50 $ et 20 $/million de Token ; le prix réel de la plateforme est converti selon les remises du forfait. ## Invite système -L’API Claude Messages prend en charge la définition d’invites système via le champ `system`, utilisées pour définir le comportement, le rôle et le contexte du modèle. +L’API Claude Messages prend en charge la définition d’une invite système via le champ `system`, utilisée pour définir le comportement, le rôle et le contexte du modèle. ### Exemple Python - ```python import requests @@ -152,11 +149,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -En définissant l’invite `system`, il est possible de contrôler précisément le rôle et le comportement de Claude. +En définissant le prompt `system`, vous pouvez contrôler précisément le rôle et le comportement de Claude. ## Réponse en streaming -Cette interface prend également en charge les réponses en streaming : définissez le paramètre `stream` sur `true` afin d’obtenir un retour progressif, ce qui convient parfaitement à l’implémentation d’un affichage caractère par caractère sur une page web. +Cette interface prend également en charge les réponses en streaming ; définissez le paramètre `stream` sur `true` pour obtenir un retour progressif, ce qui est particulièrement adapté à l’implémentation d’un affichage caractère par caractère sur une page web. ### Exemple Python @@ -186,14 +183,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Les réponses en streaming sont renvoyées au format Server-Sent Events (SSE), chaque ligne étant préfixée par `event:` et `data:`. Les types d’événements de streaming incluent : +La réponse en streaming est renvoyée au format Server-Sent Events (SSE), chaque ligne étant préfixée par `event:` et `data:`. Les types d’événements de streaming incluent : -- `message_start`：début du message, incluant les informations de base du message et le nom du modèle. -- `content_block_start`：début du bloc de contenu. -- `content_block_delta`：mise à jour incrémentielle du bloc de contenu, incluant le fragment de texte nouvellement généré. -- `content_block_stop`：fin du bloc de contenu. -- `message_delta`：mise à jour incrémentielle au niveau du message, incluant `stop_reason` et les informations finales de `usage`. La valeur faisant autorité de `output_tokens_details.thinking_tokens` doit uniquement être lue à partir du dernier `message_delta.usage`, et ne doit pas être cumulée entre les événements. -- `message_stop`：fin du message. +- `message_start` : début du message, contenant les informations de base du message et le nom du modèle. +- `content_block_start` : début du bloc de contenu. +- `content_block_delta` : mise à jour incrémentielle du bloc de contenu, contenant les nouveaux fragments de texte générés. +- `content_block_stop` : fin du bloc de contenu. +- `message_delta` : mise à jour incrémentielle au niveau du message, contenant `stop_reason` et les informations finales de `usage`. La valeur de référence de `output_tokens_details.thinking_tokens` doit uniquement être lue depuis le dernier `message_delta.usage`, ne l’accumulez pas entre les événements. +- `message_stop` : fin du message. L’effet de sortie est le suivant : @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -On peut voir que, dans les réponses en streaming, l’événement `content_block_delta` contient le contenu textuel généré progressivement ; il suffit de concaténer tous les `text_delta` pour obtenir la réponse complète. +Vous pouvez constater que, dans la réponse en streaming, l’événement `content_block_delta` contient le contenu textuel généré progressivement ; en concaténant tous les `text_delta`, vous pouvez obtenir la réponse complète. ### Exemple JavaScript @@ -254,9 +251,9 @@ while (true) { } ``` -## Conversation à plusieurs tours +## Conversation multi-tours -Si vous souhaitez intégrer une fonctionnalité de conversation à plusieurs tours, vous devez alterner les messages aux rôles `user` et `assistant` dans le tableau `messages`, et transmettre ensemble l’historique des conversations précédentes. +Si vous souhaitez intégrer une fonctionnalité de conversation multi-tours, vous devez alterner les messages avec les rôles `user` et `assistant` dans le tableau `messages`, en transmettant également l’historique des conversations précédentes. ### Exemple Python @@ -285,7 +282,8 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Le résultat retourné est le suivant : +Le résultat renvoyé est le suivant : + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ Le résultat retourné est le suivant : } ``` -En transmettant l'historique complet de la conversation dans `messages`, Claude peut fournir des réponses précises en tenant compte du contexte. +En transmettant l’historique complet de la conversation dans `messages`, Claude peut fournir des réponses précises en tenant compte du contexte. -## Modèles de réflexion approfondie +## Modèle de réflexion approfondie -Le thinking et le thinking summary de Claude sont deux concepts différents : le modèle peut effectuer un raisonnement interne, mais l'API ne renvoie pas la chaîne de pensée brute. Lorsqu'il est nécessaire d'afficher le processus de raisonnement, l'API renvoie un résumé traité. +Le thinking et le thinking summary de Claude sont deux concepts différents : le modèle peut effectuer un raisonnement interne, mais l’API ne renvoie pas la chaîne de pensée brute. Lorsqu’il est nécessaire d’afficher le processus de raisonnement, l’API renvoie un résumé traité. -Les modèles actuels recommandent d'utiliser l'adaptive thinking, et de contrôler l'investissement global dans le raisonnement via `output_config.effort` : +Il est actuellement recommandé d’utiliser l’adaptive thinking pour le modèle actuel, et de contrôler l’investissement global de raisonnement via `output_config.effort` : ```python import requests @@ -352,25 +350,24 @@ Le bloc thinking dans la réponse se présente comme suit : "signature": "opaque-signature" } ``` - -- `display: "summarized"` renvoie un résumé de réflexion lisible ; il ne s'agit pas de la chaîne de pensée brute. -- `display: "omitted"` renvoie `thinking: ""`, tout en conservant l'`signature` opaque pour prendre en charge les conversations ultérieures. -- `display: "updates"` est le mode beta d'Anthropic et nécessite `anthropic-beta: thinking-display-updates-2026-08-18`. La définition officielle est de masquer le corps du raisonnement et d'afficher de brèves mises à jour de progression entre les appels d'outils. La plateforme transmet ce paramètre et l'en-tête de requête beta tels quels, sans forcer leur réécriture en `summarized` ; le contenu réel de la sortie dépend de la prise en charge du modèle sélectionné. -- `thinking`, `output_config`, effort, les paramètres d'échantillonnage et les nouveaux champs d'extension sont transmis tels quels. La plateforme ne maintient pas d'énumérations de valeurs codées en dur par modèle ni de restrictions de combinaison, et ne réécrit pas automatiquement le mode thinking ; l'acceptation de ces paramètres est déterminée par le modèle sélectionné, et les erreurs de paramètres renvoyées par le modèle sont transmises au client. -- La valeur par défaut de display pour Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 et Opus 4.7 est `omitted` ; les modèles Opus 4.6, Sonnet 4.6 et les modèles antérieurs prenant en charge thinking utilisent par défaut `summarized`. -- Display affecte uniquement le contenu retourné et la latence du streaming ; il ne désactive pas le raisonnement et ne réduit pas la facturation des thinking tokens. -- L'activation par défaut de thinking et la valeur par défaut de display sont deux questions distinctes. Opus 5 et Sonnet 5 activent adaptive thinking par défaut ; pour Opus 5, omettre `thinking` équivaut à adaptive, et omettre `output_config.effort` équivaut à `high`. Opus 4.8, 4.7 et 4.6 nécessitent une activation explicite. -- Thinking et le texte final partagent le budget de sortie de `max_tokens`. Si le budget est trop faible, thinking peut utiliser la majeure partie du quota, laissant le texte vide ou tronqué ; veuillez augmenter `max_tokens`, ou utiliser l'effort `low` / `medium` pour contrôler l'investissement dans le raisonnement. -- Pour les modèles qui permettent de désactiver thinking, vous pouvez transmettre `thinking: {"type":"disabled"}`. Les nouveaux modes tels que `between_tools` ainsi que les combinaisons d'effort dépendent du modèle sélectionné ; la plateforme ne les rejette pas à l'avance selon les anciennes règles de modèles. -- Un budget de réflexion fixe peut être transmis via `budget_tokens` ; les nouveaux modèles utilisent généralement `thinking.type=adaptive` et `output_config.effort`. La prise en charge d'un budget fixe ou de la désactivation de la réflexion dépend des capacités actuelles du modèle sélectionné. -- Lors de conversations multi-tours et d'appels d'outils, le bloc thinking complet et la signature renvoyés par l'assistant doivent être retransmis tels quels ; ne modifiez pas et ne générez pas vous-même de signature. -- La transmission transparente des paramètres ne signifie pas que chaque modèle prend en charge toutes les fonctionnalités. Les appels inter-protocoles nécessitent toujours une conversion, et la prise en charge ainsi que les erreurs pour des contenus tels que `redacted_thinking` sont déterminées par le service de modèle qui traite réellement la requête. +- `display: "summarized"` renvoie un résumé de réflexion lisible ; ce n’est pas la chaîne de pensée brute. +- `display: "omitted"` renvoie `thinking: ""`, mais conserve toujours une `signature` opaque pour prendre en charge les conversations ultérieures. +- `display: "updates"` est le mode beta d’Anthropic, qui nécessite `anthropic-beta: thinking-display-updates-2026-08-18`. La définition officielle est de masquer le corps du raisonnement et d’afficher de brèves mises à jour de progression entre les appels d’outils. La plateforme transmet ce paramètre et l’en-tête de requête beta tels quels, sans forcer leur réécriture en `summarized` ; le contenu réel de la sortie dépend de la prise en charge du modèle sélectionné. +- `thinking`, `output_config`, effort, les paramètres d’échantillonnage et les nouveaux champs d’extension sont transmis tels quels. La plateforme ne maintient pas d’énumérations de valeurs ni de restrictions de combinaisons codées en dur par modèle, et ne réécrit pas automatiquement les modes thinking ; l’acceptation de ces paramètres est déterminée par le modèle sélectionné, et les erreurs de paramètres renvoyées par le modèle seront transmises au client. +- Les valeurs par défaut de display pour Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 et Opus 4.7 sont `omitted` ; Opus 4.6, Sonnet 4.6 et les modèles antérieurs prenant en charge thinking utilisent `summarized` par défaut. +- Display n’affecte que le contenu retourné et la latence de streaming, ne désactive pas le raisonnement et ne réduit pas la facturation des tokens thinking. +- L’activation de thinking par défaut et la valeur par défaut de display sont deux questions indépendantes. Opus 5 et Sonnet 5 activent adaptive thinking par défaut ; pour Opus 5, omettre `thinking` équivaut à adaptive, et omettre `output_config.effort` équivaut à `high`. Opus 4.8, 4.7 et 4.6 nécessitent une activation explicite. +- Thinking et le corps final partagent le budget de sortie `max_tokens`. Si le budget est trop faible, thinking peut consommer la majeure partie du quota, laissant le corps vide ou tronqué ; augmentez `max_tokens`, ou utilisez l’effort `low` / `medium` pour contrôler l’investissement dans le raisonnement. +- Pour les modèles qui autorisent la désactivation de thinking, vous pouvez transmettre `thinking: {"type":"disabled"}`. Les nouveaux modes tels que `between_tools` ainsi que les combinaisons d’effort dépendent du modèle sélectionné ; la plateforme ne les rejettera pas à l’avance selon les anciennes règles de modèle. +- Un budget de réflexion fixe peut être transmis via `budget_tokens` ; les nouveaux modèles utilisent généralement `thinking.type=adaptive` et `output_config.effort`. La prise en charge d’un budget fixe ou de la désactivation de la réflexion dépend des capacités actuelles du modèle sélectionné. +- Lors de conversations multi-tours et d’appels d’outils, le bloc thinking complet et la signature renvoyés par l’assistant doivent être retransmis tels quels ; ne modifiez pas et ne générez pas vous-même de signature. +- La transmission directe des paramètres ne signifie pas que chaque modèle prend en charge toutes les fonctionnalités. Les appels inter-protocoles nécessitent toujours une conversion, et la portée de prise en charge ainsi que les erreurs pour des contenus comme `redacted_thinking` sont déterminées par le service de modèle qui traite réellement la requête. Dans les requêtes en streaming, `summarized` produit `thinking_delta` ; `omitted` ne produit pas `thinking_delta`, et conserve uniquement le cycle de vie du bloc thinking et `signature_delta`. ## Modèles visuels -Claude prend en charge les entrées multimodales et peut traiter simultanément du texte et des images. Dans l'API Messages, les capacités visuelles peuvent être utilisées en définissant `content` au format tableau et en transmettant des blocs de contenu image. +Claude prend en charge les entrées multimodales et peut traiter simultanément du texte et des images. Dans l’API Messages, les capacités visuelles peuvent être utilisées en définissant `content` au format tableau et en transmettant des blocs de contenu d’image. ### Utiliser des images encodées en Base64 @@ -459,6 +456,7 @@ print(response.json()) ``` ### Exemple cURL + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -492,7 +490,7 @@ Les formats d’image pris en charge incluent : `image/jpeg`, `image/png`, `imag ## Documents et PDF -Les PDF utilisent le bloc de contenu `document`, prenant en charge deux sources stables : Base64 et URL. Les sources Base64 doivent utiliser `application/pdf` : +Les PDF utilisent des blocs de contenu `document` et prennent en charge deux sources stables : Base64 et URL. Les sources Base64 doivent utiliser `application/pdf` : ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -Les sources URL s’écrivent sous la forme `{"type":"url","url":"https://example.com/report.pdf"}`. `document` prend également en charge `text/plain` et les sources `content` composées de blocs text/image ; les champs facultatifs incluent `title`, `context` et `citations`. La source `file_id` de l’API Files est une fonctionnalité bêta indépendante et ne fait pas partie du contrat stable de cette interface. +Les sources URL s’écrivent `{"type":"url","url":"https://example.com/report.pdf"}`. `document` prend également en charge `text/plain` et les sources `content` composées de blocs text/image ; les champs optionnels incluent `title`, `context` et `citations`. Les sources `file_id` de l’API Files constituent une fonctionnalité beta distincte et ne font pas partie du contrat stable de cette interface. ## Mise en cache des prompts -Le `cache_control` de niveau supérieur place automatiquement le point de rupture du cache sur le dernier bloc pouvant être mis en cache : +Le `cache_control` de niveau supérieur placera automatiquement le point d’arrêt du cache sur le dernier bloc pouvant être mis en cache : ```python payload = { @@ -536,12 +534,11 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Lorsque vous devez contrôler précisément la position, vous pouvez également écrire le même `cache_control` sur les blocs de contenu text, image, document, tool_use, tool_result ou sur la définition de l’outil. `ttl` prend en charge `5m` (par défaut) et `1h` ; veuillez déterminer l’écriture et l’atteinte du cache via `usage.cache_creation_input_tokens` et `usage.cache_read_input_tokens`. -Lorsqu’un contrôle précis de la position est nécessaire, le même `cache_control` peut également être écrit sur les blocs de contenu text, image, document, tool_use, tool_result ou sur les définitions d’outils. `ttl` prend en charge `5m` (par défaut) et `1h` ; veuillez utiliser `usage.cache_creation_input_tokens` et `usage.cache_read_input_tokens` pour déterminer l’écriture dans le cache et les accès au cache. - -Lorsque la réponse fournit `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Si `cache_creation` est `null` ou omis, cela indique qu’il n’existe qu’un total des écritures dans le cache, sans ventilation TTL faisant autorité ; dans ce cas, ne considérez aucun bucket comme étant à 0 connu, et la facturation ainsi que les totaux restent basés sur le champ agrégé. +Lorsque la réponse fournit `usage.cache_creation`, alors `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Si `cache_creation` est `null` ou omis, cela indique qu’il n’existe qu’un total d’écriture dans le cache, sans répartition TTL faisant autorité ; dans ce cas, ne considérez aucun bucket comme étant connu à 0, la facturation et les totaux restent basés sur le champ aggregate. -Exemple de résultat renvoyé : +Exemple de résultat retourné : ```json { @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Lorsque le modèle décide d’appeler un outil, le `content` dans le résultat renvoyé inclut un bloc de contenu de type `tool_use` : +Lorsque le modèle décide d’appeler un outil, le champ `content` dans le résultat retourné contient un bloc de contenu de type `tool_use` : ```json { @@ -640,7 +637,7 @@ Lorsque le modèle décide d’appeler un outil, le `content` dans le résultat } ``` -Notez que `stop_reason` est `tool_use`, ce qui indique que le modèle doit appeler un outil. Après avoir reçu ce résultat, vous devez exécuter la fonction outil et renvoyer le résultat au modèle sous la forme de `tool_result` : +Notez que `stop_reason` est `tool_use`, ce qui indique que le modèle doit appeler un outil. Après avoir reçu ce résultat, vous devez exécuter la fonction outil et renvoyer le résultat au modèle sous la forme d’un `tool_result` : ```python payload = { @@ -688,38 +685,39 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Le modèle générera une réponse finale en langage naturel sur la base du résultat renvoyé par l’outil. +Le modèle générera une réponse finale en langage naturel sur la base du résultat retourné par l’outil. ## Différences avec l’API Chat Completion Ace Data Cloud fournit simultanément deux formats d’API Claude, dont les principales différences sont les suivantes : -Dans l’API Messages, `usage.input_tokens` représente uniquement les entrées non mises en cache, tandis que `cache_read_input_tokens` et `cache_creation_input_tokens` sont des catégories de facturation indépendantes ; les trois sont calculés séparément selon les prix correspondants. -| Fonctionnalité | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +Le champ `usage.input_tokens` de l’API Messages ne représente que les entrées non mises en cache ; `cache_read_input_tokens` et `cache_creation_input_tokens` sont des buckets de facturation indépendants ; les trois sont calculés séparément selon les prix correspondants. + +| Fonctionnalité | API Messages (`/v1/messages`) | API Chat Completion (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Format | Format natif Anthropic | Format compatible OpenAI | -| Invite système | Champ `system` indépendant | Transmis via `role: "system"` dans `messages` | +| Invite système | Champ `system` indépendant | Transmise via `role: "system"` dans `messages` | | Structure de réponse | Tableau `content` (prend en charge plusieurs types) | Tableau `choices` (contient `message`) | -| Format de streaming | Événements SSE (plusieurs types d'événements) | Lignes SSE `data` | +| Format de streaming | Événements SSE (plusieurs types d’événements) | Lignes SSE `data` | | Raisonnement approfondi | `thinking` natif et `output_config.effort` | Stratégie par défaut du modèle et paramètres de compatibilité | -| Appels d'outils | `tools` natif + `input_schema` | Format `tools` compatible OpenAI | -| Statistiques Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | +| Appel d’outils | `tools` natif + `input_schema` | Format `tools` compatible OpenAI | +| Statistiques de tokens | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Si votre système est déjà intégré à une API au format OpenAI, vous pouvez utiliser la Chat Completion API pour basculer de manière transparente. Si vous avez besoin d'utiliser toutes les capacités natives de Claude, il est recommandé d'utiliser la Messages API. +Si votre système est déjà intégré à une API au format OpenAI, vous pouvez utiliser l’API Chat Completion pour basculer de manière transparente. Si vous devez utiliser toutes les capacités natives de Claude, il est recommandé d’utiliser l’API Messages. ## Gestion des erreurs -Les réponses d'erreur de l'interface publique utilisent l'enveloppe de la plateforme Ace Data Cloud : `error.code` est un code d'erreur stable, `error.message` est une description, et `trace_id` est utilisé pour diagnostiquer les requêtes. Les statuts HTTP courants incluent : +Les réponses d’erreur de l’interface publique utilisent l’enveloppe de la plateforme Ace Data Cloud : `error.code` est un code d’erreur stable, `error.message` est une description, et `trace_id` est utilisé pour diagnostiquer les requêtes. Les statuts HTTP courants incluent : -- `400` : Les paramètres de la requête ou le contenu du protocole sont invalides. -- `401` : Le jeton d'autorisation est invalide, manquant ou expiré. -- `403` : Accès interdit, solde insuffisant ou quota limité. -- `404` : L'API ou le modèle n'existe pas. -- `413` : Le corps de la requête est trop volumineux. -- `429` : Trop de requêtes. -- `500` / `503` / `504` : Erreur de service, indisponibilité temporaire ou délai de traitement dépassé. +- `400` : les paramètres de la requête ou le contenu du protocole sont invalides. +- `401` : le jeton d’autorisation est invalide, absent ou expiré. +- `403` : accès interdit, solde insuffisant ou quota limité. +- `404` : l’API ou le modèle n’existe pas. +- `413` : le corps de la requête est trop volumineux. +- `429` : trop de requêtes. +- `500` / `503` / `504` : erreur de service, indisponibilité temporaire ou délai de traitement dépassé. -### Exemple de réponse d'erreur +### Exemple de réponse d’erreur ```json { @@ -731,8 +729,7 @@ Les réponses d'erreur de l'interface publique utilisent l'enveloppe de la plate } ``` -Cette structure d'erreur constitue le contrat d'exécution d'Ace Data Cloud et n'est pas équivalente à l'enveloppe d'erreur officielle d'Anthropic ; veuillez la traiter selon le statut HTTP et `error.code`. +Cette structure d’erreur est le contrat d’exécution d’Ace Data Cloud et n’est pas équivalente à l’enveloppe d’erreur officielle d’Anthropic ; veuillez la traiter selon le statut HTTP et `error.code`. ## Conclusion - -Grâce à ce document, vous avez appris à utiliser la Claude Messages API afin d'appeler les fonctionnalités conversationnelles de Claude au format natif Anthropic. La Messages API prend en charge de nombreuses fonctionnalités, telles que les conversations de base, les invites système, les réponses en streaming, les conversations multi-tours, le raisonnement approfondi, la compréhension visuelle, les PDF, la mise en cache des invites et les appels d'outils. Si vous avez des questions, veuillez contacter notre équipe de support technique à tout moment. +Grâce à ce document, vous avez déjà appris comment utiliser l’API Claude Messages pour appeler les fonctionnalités de conversation de Claude au format natif d’Anthropic. L’API Messages prend en charge de nombreuses fonctionnalités, notamment les conversations de base, les invites système, les réponses en streaming, les conversations à plusieurs tours, la réflexion approfondie, la compréhension visuelle, les PDF, la mise en cache des invites et l’appel d’outils. Si vous avez des questions, n’hésitez pas à contacter notre équipe de support technique. diff --git a/it/guides/claude/claude_messages.mdx b/it/guides/claude/claude_messages.mdx index ccf2142c..5e9fb737 100644 --- a/it/guides/claude/claude_messages.mdx +++ b/it/guides/claude/claude_messages.mdx @@ -3,42 +3,41 @@ title: "Richiesta e utilizzo della Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude è un sistema di conversazione AI molto potente: basta inserire un prompt per generare risposte fluide e naturali in pochi secondi. Claude Messages API è il formato API nativo ufficiale di Anthropic; diversamente dal formato compatibile con OpenAI (Chat Completion), adotta la propria struttura di richieste e risposte di Anthropic, consentendo di sfruttare meglio le capacità uniche di Claude, come l'input di contenuti multimodali, la chiamata di strumenti, il ragionamento approfondito (Extended Thinking) e altre funzionalità avanzate. +Anthropic Claude è un sistema di conversazione AI molto potente: basta inserire un prompt per generare risposte fluide e naturali in pochi secondi. La Claude Messages API è il formato API nativo ufficiale di Anthropic; diversamente dal formato compatibile con OpenAI (Chat Completion), adotta una struttura di richiesta e risposta proprietaria di Anthropic, consentendo di sfruttare meglio le capacità uniche di Claude, come l'input di contenuti multimodali, la chiamata di strumenti, il ragionamento approfondito (Extended Thinking) e altre funzionalità avanzate. -Questo documento introduce principalmente il flusso di utilizzo delle operazioni della Claude Messages API. Utilizzandola, possiamo chiamare le funzionalità di conversazione di Claude tramite un'interfaccia nativa coerente con quella ufficiale di Anthropic. +Questo documento presenta principalmente il flusso di utilizzo delle operazioni della Claude Messages API. Usandola, possiamo utilizzare un'interfaccia nativa coerente con quella ufficiale di Anthropic per richiamare le funzionalità di conversazione di Claude. -## Procedura di richiesta +## Processo di richiesta -Per utilizzare la Claude Messages API, per prima cosa vai alla [Console di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token e conservalo per l'uso successivo. +Per utilizzare la Claude Messages API, innanzitutto vai alla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token e conservarlo come riserva. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Se non hai ancora effettuato l'accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per registrarti e accedere; una volta completato, tornerai automaticamente alla pagina corrente. +Se non hai ancora effettuato l'accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per registrarti ed effettuare l'accesso; al termine, tornerai automaticamente alla pagina corrente. -**Un solo API Token consente di chiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ciascun servizio.** La prima richiesta include crediti gratuiti, consentendo una prova gratuita; quando i crediti sono insufficienti, puoi ricaricare il saldo universale nella [console](https://platform.acedata.cloud/console/coin). +**Un solo API Token consente di richiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ciascun servizio.** La prima richiesta include un credito gratuito, per consentire una prova gratuita; quando il credito è insufficiente, puoi ricaricare il saldo universale nella [console](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Utilizzo di base -Il percorso della richiesta della Claude Messages API è `/v1/messages`, coerente con l'API ufficiale di Anthropic. Dobbiamo fornire almeno tre parametri obbligatori: +Il percorso di richiesta della Claude Messages API è `/v1/messages`, coerente con l'API ufficiale di Anthropic. Dobbiamo fornire almeno tre parametri obbligatori: -- `model`: seleziona il modello Claude da utilizzare. `claude-opus-5-5` viene fornito solo tramite Messages API, supporta un contesto di 1 milione di Token, un output massimo di 128K Token e abilita sempre il ragionamento adattivo. L'ultimo modello di punta è `claude-fable-5-1` (contesto di 1 milione di Token, output massimo di 128K Token); il precedente `claude-fable-5` rimane compatibile e disponibile. `claude-sonnet-5-5` è stato aggiunto all'interfaccia della serie nativa Messages, supporta l'input di immagini e il ragionamento adattivo; i suoi prezzi di riferimento ufficiali per input, output e lettura della cache sono rispettivamente 2, 10 e 0,20 dollari per milione di Token. -- `messages`: l'array dei messaggi di input, ogni messaggio contiene `role` (ruolo) e `content` (contenuto), dove `role` supporta `user` e `assistant`. -- `max_tokens`: il numero massimo di token in output, utilizzato per limitare la lunghezza di una singola risposta. +- `model`: seleziona il modello Claude da utilizzare. `claude-opus-5-5` è disponibile solo tramite Messages API, supporta un contesto di 1 milione di Token, un output massimo di 128K Token e abilita sempre il ragionamento adattivo. Il più recente modello di punta è `claude-fable-5-1` (contesto di 1 milione di Token, output massimo di 128K Token); il precedente `claude-fable-5` rimane compatibile e disponibile. `claude-sonnet-5-5` è stato aggiunto alla serie di interfacce native Messages, supporta l'input di immagini e il ragionamento adattivo; i suoi prezzi di riferimento ufficiali per input, output e lettura della cache sono rispettivamente 2, 10 e 0,20 dollari per milione di Token. +- `messages`: array dei messaggi in input; ogni messaggio contiene `role` (ruolo) e `content` (contenuto), dove `role` supporta `user` e `assistant`. +- `max_tokens`: numero massimo di token in output, utilizzato per limitare la lunghezza di una singola risposta. Parametri opzionali comuni: - `system`: prompt di sistema, utilizzato per impostare il comportamento e il ruolo del modello. - `temperature`: casualità della generazione, compresa tra 0 e 1; maggiore è il valore, più divergente sarà la risposta. -- `stream`: se utilizzare risposte in streaming; impostandolo su `true` è possibile ottenere un effetto di restituzione carattere per carattere. +- `stream`: se utilizzare la risposta in streaming; impostandolo su `true` è possibile ottenere un effetto di restituzione carattere per carattere. - `stop_sequences`: sequenze di arresto personalizzate; il modello smetterà di generare quando incontrerà questi testi. -- `top_p`: parametro di campionamento nucleare, che controlla la casualità della generazione insieme a temperature. -- `top_k`: esegue il campionamento solo tra le K opzioni con probabilità più alta. +- `top_p`: parametro di campionamento del nucleo, utilizzato con temperature per controllare la casualità della generazione. +- `top_k`: campiona solo tra le K opzioni con probabilità più alta. - `tools`: definizioni degli strumenti, utilizzate per consentire al modello di chiamare funzioni esterne. - `tool_choice`: controlla come il modello utilizza gli strumenti forniti. -- `cache_control`: crea automaticamente un punto di interruzione della cache nell'ultimo blocco di contenuto memorizzabile nella richiesta; può anche essere scritto sul blocco di contenuto specifico. -- `metadata`: oggetto opzionale di metadati della richiesta. `metadata.user_id` è una stringa e può trasmettere un identificatore utente personalizzato dal chiamante, ad esempio `{"user_id":"example-user-001"}`; si consiglia di utilizzare un identificatore stabile che non contenga informazioni personali. Non sostituisce l'autenticazione `Authorization` e non deve essere scritto nel contenuto della conversazione `messages`. +- `cache_control`: crea automaticamente un punto di interruzione della cache nell'ultimo blocco di contenuto memorizzabile nella cache della richiesta; può anche essere scritto nel blocco di contenuto specifico. ### Esempio cURL @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -110,24 +107,24 @@ Dopo la chiamata, il risultato restituito è il seguente: ``` Descrizione dei campi del risultato restituito: -- `id`: l'identificatore univoco di questo messaggio. -- `type`: è sempre `message`. -- `role`: è sempre `assistant`. -- `content`: array del contenuto della risposta, ogni elemento include `type` (come `text`) e il contenuto corrispondente. -- `model`: il nome del modello che elabora la richiesta. -- `stop_reason`: il motivo dell'interruzione. I valori stabili includono `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (può ritrasmettere invariato il contenuto corrente dell'assistant per continuare), `refusal` e `model_context_window_exceeded`. -- `stop_sequence`: se l'interruzione avviene a causa di una sequenza di arresto personalizzata, mostra il testo della sequenza di arresto corrispondente. + +- `id`: identificatore univoco di questo messaggio. +- `type`: sempre `message`. +- `role`: sempre `assistant`. +- `content`: array dei contenuti della risposta; ogni elemento contiene `type` (ad esempio `text`) e il contenuto corrispondente. +- `model`: nome del modello che elabora la richiesta. +- `stop_reason`: motivo dell'arresto. I valori stabili includono `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (puoi ritrasmettere invariato il contenuto corrente dell'assistant per continuare), `refusal` e `model_context_window_exceeded`. +- `stop_sequence`: se l'arresto avviene a causa di una sequenza di arresto personalizzata, mostra il testo della sequenza di arresto corrispondente. - `stop_details`: quando `stop_reason` è `refusal`, può contenere la categoria e la descrizione del rifiuto. -- `usage`: statistiche sull'utilizzo dei token. `input_tokens` è l'input non memorizzato nella cache; `cache_creation_input_tokens` e `cache_read_input_tokens` sono rispettivamente la scrittura e la lettura della cache; `output_tokens` è il numero totale di token in output. Se viene restituito `output_tokens_details.thinking_tokens`, questo valore è un sottoinsieme di `output_tokens`, quindi non sommarlo nuovamente nel calcolo del totale o del costo. Questo dettaglio può essere `null` o omesso quando non è disponibile un conteggio autorevole. -- `usage.cache_creation`: dettagli opzionali sul TTL della scrittura in cache, inclusi `ephemeral_5m_input_tokens` e `ephemeral_1h_input_tokens`. Quando l'oggetto è presente, la somma dei due è uguale a `cache_creation_input_tokens`; un campo `null` o omesso indica che la risposta corrente non dispone di una suddivisione TTL utilizzabile e non deve essere interpretato come `0`. -- `usage.cost`: le risposte non in streaming possono includere un oggetto di consumo delle quote registrato da Ace Data Cloud, in cui `amount` è il consumo effettivo di questa richiesta, `currency` è l'unità di misura e `list_amount` è l'importo prima dello sconto (se presente). Il prezzo base ufficiale per le letture della cache di Fable 5.1 è $0,25/milione di token, mentre i prezzi base per la scrittura nella cache di 5 minuti e 1 ora sono rispettivamente $12,50 e $20/milione di token; il prezzo effettivo della piattaforma viene calcolato in base allo sconto del piano. +- `usage`: statistiche sull'utilizzo dei token. `input_tokens` è l'input non memorizzato nella cache; `cache_creation_input_tokens` e `cache_read_input_tokens` sono rispettivamente la scrittura e la lettura della cache; `output_tokens` è il numero totale di token in output. Se viene restituito `output_tokens_details.thinking_tokens`, questo valore è un sottoinsieme di `output_tokens`; non sommarlo nuovamente quando si calcola il totale o il costo. Questo dettaglio può essere `null` o omesso quando non è disponibile un conteggio autorevole. +- `usage.cache_creation`: dettaglio opzionale del TTL di scrittura della cache, contenente `ephemeral_5m_input_tokens` e `ephemeral_1h_input_tokens`. Quando l'oggetto è presente, la somma dei due elementi è uguale a `cache_creation_input_tokens`; un campo `null` o omesso indica che la risposta corrente non dispone di una suddivisione TTL utilizzabile e non può essere interpretato come `0`. +- `usage.cost`: le risposte non in streaming possono contenere l'oggetto di consumo del credito registrato da Ace Data Cloud, dove `amount` è il consumo effettivo di questa richiesta, `currency` è l'unità di misura e `list_amount` è l'importo prima dello sconto (se presente). Il prezzo base ufficiale per la lettura della cache di Fable 5.1 è di $0,25/milione di Token, mentre i prezzi base per la scrittura della cache di 5 minuti e di 1 ora sono rispettivamente $12,50 e $20/milione di Token; il prezzo effettivo della piattaforma viene calcolato in base allo sconto del piano. ## Prompt di sistema -Claude Messages API supporta l'impostazione dei prompt di sistema tramite il campo `system`, utilizzato per definire il comportamento, il ruolo e il contesto del modello. +La Claude Messages API supporta l'impostazione del prompt di sistema tramite il campo `system`, utilizzato per definire il comportamento, il ruolo e il contesto del modello. ### Esempio Python - ```python import requests @@ -156,7 +153,7 @@ Impostando il prompt `system`, è possibile controllare con precisione il ruolo ## Risposta in streaming -Questa interfaccia supporta anche le risposte in streaming: basta impostare il parametro `stream` su `true` per ottenere un effetto di restituzione progressiva, particolarmente adatto per implementare la visualizzazione parola per parola nelle pagine web. +Questa interfaccia supporta anche le risposte in streaming: impostando il parametro `stream` su `true` è possibile ottenere un effetto di restituzione progressiva, particolarmente adatto per implementare la visualizzazione carattere per carattere nelle pagine web. ### Esempio Python @@ -186,16 +183,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Le risposte in streaming vengono restituite nel formato Server-Sent Events (SSE), con ogni riga preceduta da `event:` e `data:`. I tipi di eventi in streaming includono: +La risposta in streaming viene restituita nel formato Server-Sent Events (SSE), con ogni riga preceduta da `event:` e `data:`. I tipi di eventi in streaming includono: - `message_start`: inizio del messaggio, include le informazioni di base del messaggio e il nome del modello. - `content_block_start`: inizio del blocco di contenuto. -- `content_block_delta`: aggiornamento incrementale del blocco di contenuto, include il nuovo frammento di testo generato. +- `content_block_delta`: aggiornamento incrementale del blocco di contenuto, include il frammento di testo appena generato. - `content_block_stop`: fine del blocco di contenuto. - `message_delta`: aggiornamento incrementale a livello di messaggio, include `stop_reason` e le informazioni finali di `usage`. Il valore autorevole di `output_tokens_details.thinking_tokens` deve essere letto solo dall'ultimo `message_delta.usage`, senza accumularlo tra gli eventi. - `message_stop`: fine del messaggio. -L'effetto dell'output è il seguente: +L'effetto di output è il seguente: ``` event: message_start @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Come si può vedere, nella risposta in streaming l'evento `content_block_delta` contiene il contenuto testuale generato progressivamente; concatenando tutti i `text_delta` si ottiene la risposta completa. +Come si può vedere, nella risposta in streaming l'evento `content_block_delta` contiene il testo generato progressivamente; concatenando tutti i `text_delta` è possibile ottenere la risposta completa. ### Esempio JavaScript @@ -256,7 +253,7 @@ while (true) { ## Conversazione multi-turno -Se desideri integrare la funzionalità di conversazione multi-turno, devi disporre alternativamente i messaggi con ruolo `user` e `assistant` nell'array `messages`, includendo anche la cronologia delle conversazioni precedenti. +Se desiderate integrare la funzionalità di conversazione multi-turno, dovete disporre alternativamente i messaggi con ruolo `user` e `assistant` nell'array `messages`, trasmettendo insieme l'intera cronologia della conversazione precedente. ### Esempio Python @@ -286,6 +283,7 @@ print(response.json()) ``` Il risultato restituito è il seguente: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ Il risultato restituito è il seguente: } ``` -Passando la cronologia completa della conversazione in `messages`, Claude può combinare il contesto per fornire risposte accurate. +Passando l'intera cronologia della conversazione in `messages`, Claude può fornire risposte accurate tenendo conto del contesto. -## Modelli di ragionamento profondo +## Modello di ragionamento approfondito -Il thinking e il thinking summary di Claude sono due concetti diversi: il modello può effettuare ragionamenti interni, ma l'API non restituisce la catena di pensiero originale. Quando è necessario mostrare il processo di ragionamento, l'API restituisce un riepilogo elaborato. +Il thinking e il thinking summary di Claude sono due concetti diversi: il modello può eseguire un ragionamento interno, ma l'API non restituisce la catena di pensiero originale. Quando è necessario mostrare il processo di ragionamento, l'API restituisce un riepilogo elaborato. -I modelli attuali consigliano di usare adaptive thinking e di controllare l'investimento complessivo nel ragionamento tramite `output_config.effort`: +Per il modello attuale si consiglia di utilizzare l'adaptive thinking e di controllare l'impegno complessivo di ragionamento tramite `output_config.effort`: ```python import requests @@ -343,7 +341,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Il blocco thinking nella risposta ha la forma seguente: +Il blocco thinking nella risposta ha la seguente forma: ```json { @@ -352,25 +350,24 @@ Il blocco thinking nella risposta ha la forma seguente: "signature": "opaque-signature" } ``` - - `display: "summarized"` restituisce un riepilogo leggibile del ragionamento; non è la catena di pensiero originale. -- `display: "omitted"` restituisce `thinking: ""`, ma mantiene comunque una `signature` opaca per supportare le conversazioni successive. -- `display: "updates"` è una modalità beta di Anthropic e richiede `anthropic-beta: thinking-display-updates-2026-08-18`. La definizione ufficiale consiste nel nascondere il testo del ragionamento e mostrare brevi aggiornamenti di avanzamento tra le chiamate agli strumenti. La piattaforma passa questo parametro e l'intestazione della richiesta beta con i valori originali e non lo riscrive forzatamente in `summarized`; il contenuto effettivo dell'output dipende dal supporto del modello selezionato. -- `thinking`, `output_config`, effort, parametri di campionamento e nuovi campi di estensione vengono passati con i valori originali. La piattaforma non mantiene enumerazioni di valori o limitazioni di combinazione codificate per modello, né riscrive automaticamente le modalità thinking; spetta al modello selezionato stabilire se accettare questi parametri, e gli errori dei parametri restituiti dal modello vengono inoltrati al client. -- I valori predefiniti di display per Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 sono `omitted`; Opus 4.6, Sonnet 4.6 e i modelli precedenti che supportano thinking usano `summarized` per impostazione predefinita. +- `display: "omitted"` restituisce `thinking: ""`, ma conserva comunque una `signature` opaca per supportare le conversazioni successive. +- `display: "updates"` è la modalità beta di Anthropic e richiede `anthropic-beta: thinking-display-updates-2026-08-18`. La definizione ufficiale è nascondere il corpo del ragionamento e mostrare brevi aggiornamenti di avanzamento tra le chiamate agli strumenti. La piattaforma trasmette questo parametro e l'header beta ai valori originali e non lo riscrive forzatamente come `summarized`; il contenuto effettivo dell'output dipende dal supporto del modello selezionato. +- `thinking`, `output_config`, effort, parametri di campionamento e nuovi campi estesi vengono trasmessi ai valori originali. La piattaforma non mantiene enumerazioni di valori codificate per modello, limitazioni di combinazione, né riscrive automaticamente la modalità thinking; se questi parametri siano accettati viene deciso dal modello selezionato, e gli errori di parametro restituiti dal modello vengono ritrasmessi al client. +- Il valore predefinito di display per Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 è `omitted`; Opus 4.6, Sonnet 4.6 e i modelli precedenti che supportano thinking usano per impostazione predefinita `summarized`. - Display influisce solo sul contenuto restituito e sulla latenza dello streaming, non disabilita il ragionamento né riduce la fatturazione dei token thinking. -- L'abilitazione predefinita di thinking e il valore predefinito di display sono due questioni indipendenti. Opus 5 e Sonnet 5 abilitano adaptive thinking per impostazione predefinita; per Opus 5, omettere `thinking` equivale ad adaptive, mentre omettere `output_config.effort` equivale a `high`. Opus 4.8, 4.7 e 4.6 richiedono l'abilitazione esplicita. -- Thinking e il testo finale condividono il budget di output `max_tokens`. Quando il budget è troppo ridotto, thinking può consumare gran parte della quota, lasciando il testo vuoto o troncato; aumentare `max_tokens` oppure usare effort `low` / `medium` per controllare l'investimento nel ragionamento. -- Per i modelli che consentono di disabilitare thinking, è possibile passare `thinking: {"type":"disabled"}`. Nuove modalità come `between_tools` e le combinazioni con effort dipendono dal modello selezionato; la piattaforma non rifiuta preventivamente in base alle vecchie regole dei modelli. -- Un budget di ragionamento fisso può essere passato tramite `budget_tokens`; i nuovi modelli usano in genere `thinking.type=adaptive` e `output_config.effort`. Il supporto per un budget fisso o per la disabilitazione del ragionamento dipende dalle capacità attuali del modello selezionato. -- Nelle conversazioni multi-turno e nelle chiamate agli strumenti, è necessario restituire invariati il blocco thinking completo e la signature restituiti dall'assistant; non modificare né generare autonomamente la signature. -- Il passaggio trasparente dei parametri non significa che ogni modello supporti tutte le funzionalità. Le chiamate tra protocolli richiedono comunque una conversione; l'ambito di supporto e gli errori per contenuti come `redacted_thinking` sono determinati dal servizio del modello che elabora effettivamente la richiesta. +- Se thinking sia abilitato per impostazione predefinita e il valore predefinito di display sono due questioni indipendenti. Opus 5 e Sonnet 5 abilitano per impostazione predefinita adaptive thinking; per Opus 5, omettere `thinking` equivale a adaptive, e omettere `output_config.effort` equivale a `high`. Opus 4.8, 4.7 e 4.6 richiedono un'abilitazione esplicita. +- Thinking e il corpo finale condividono il budget di output `max_tokens`. Se il budget è troppo ridotto, thinking può consumare gran parte della quota, lasciando il corpo vuoto o troncato; aumentare `max_tokens`, oppure usare effort `low` / `medium` per controllare l'investimento nel ragionamento. +- Per i modelli che consentono di disabilitare thinking, è possibile passare `thinking: {"type":"disabled"}`. Le nuove modalità come `between_tools` e le combinazioni di effort dipendono dal modello selezionato; la piattaforma non rifiuta in anticipo in base alle vecchie regole dei modelli. +- Il budget di pensiero fisso può essere passato tramite `budget_tokens`; i nuovi modelli usano generalmente `thinking.type=adaptive` e `output_config.effort`. Se il budget fisso o la disabilitazione del pensiero siano supportati dipende dalle capacità attuali del modello selezionato. +- Nelle conversazioni multi-turno e nelle chiamate agli strumenti, è necessario ritrasmettere invariati il blocco thinking completo e la signature restituiti dall'assistant; non modificare né generare autonomamente la signature. +- La trasmissione dei parametri non significa che ogni modello supporti tutte le funzionalità. Le chiamate tra protocolli richiedono comunque conversione, e l'ambito di supporto e gli errori per contenuti come `redacted_thinking` sono determinati dal servizio del modello che effettivamente elabora la richiesta. -Nelle richieste in streaming, `summarized` genera `thinking_delta`; `omitted` non genera `thinking_delta`, mantenendo solo il ciclo di vita del blocco thinking e `signature_delta`. +Nelle richieste in streaming, `summarized` produce `thinking_delta`; `omitted` non produce `thinking_delta`, mantenendo solo il ciclo di vita del blocco thinking e `signature_delta`. ## Modelli visivi -Claude supporta input multimodali e può elaborare contemporaneamente testo e immagini. Nella Messages API, è possibile utilizzare le capacità visive impostando `content` in formato array e passando blocchi di contenuto immagine. +Claude supporta input multimodali e può elaborare simultaneamente testo e immagini. Nella Messages API, le capacità visive possono essere utilizzate impostando `content` nel formato array e passando blocchi di contenuto immagine. ### Utilizzare immagini codificate in Base64 @@ -459,6 +456,7 @@ print(response.json()) ``` ### Esempio cURL + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -492,7 +490,7 @@ I formati immagine supportati includono: `image/jpeg`, `image/png`, `image/gif`, ## Documenti e PDF -I PDF utilizzano il blocco di contenuto `document`, supportando due fonti stabili: Base64 e URL. Le fonti Base64 devono utilizzare `application/pdf`: +I PDF utilizzano il blocco di contenuto `document`, con supporto per due fonti stabili: Base64 e URL. La fonte Base64 deve utilizzare `application/pdf`: ```python import base64 @@ -525,7 +523,7 @@ La fonte URL si scrive come `{"type":"url","url":"https://example.com/report.pdf ## Cache dei prompt -Il `cache_control` di primo livello posiziona automaticamente il punto di interruzione della cache sull'ultimo blocco memorizzabile nella cache: +Il `cache_control` di livello superiore posiziona automaticamente il punto di interruzione della cache sull'ultimo blocco memorizzabile nella cache: ```python payload = { @@ -536,10 +534,9 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Quando è necessario controllare con precisione la posizione, è possibile anche scrivere lo stesso `cache_control` sui blocchi di contenuto text, image, document, tool_use, tool_result o sulla definizione dello strumento. `ttl` supporta `5m` (predefinito) e `1h`; utilizzare `usage.cache_creation_input_tokens` e `usage.cache_read_input_tokens` per determinare la scrittura nella cache e il raggiungimento della cache. -Quando è necessario un controllo preciso della posizione, lo stesso `cache_control` può anche essere scritto sui blocchi di contenuto text, image, document, tool_use, tool_result o sulle definizioni degli strumenti. `ttl` supporta `5m` (predefinito) e `1h`; utilizzare `usage.cache_creation_input_tokens` e `usage.cache_read_input_tokens` per determinare la scrittura e il hit della cache. - -Quando la risposta fornisce `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Se `cache_creation` è `null` o viene omesso, ciò indica che esiste solo il totale delle scritture nella cache, senza una suddivisione TTL autorevole; in questo caso non trattare nessun bucket come uno 0 noto, e la fatturazione e il totale devono comunque basarsi sul campo aggregato. +Quando la risposta fornisce `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Se `cache_creation` è `null` o viene omesso, indica che esiste solo il totale delle scritture nella cache, senza una suddivisione autorevole per TTL; in questo caso non considerare alcun bucket come uno 0 noto, e la fatturazione e il totale rimangono basati sul campo aggregato. Esempio di risultato restituito: @@ -564,9 +561,9 @@ Esempio di risultato restituito: } ``` -## Chiamate agli strumenti (Tool Use) +## Chiamata di strumenti (Tool Use) -La Claude Messages API supporta nativamente la funzionalità di chiamata agli strumenti, consentendo al modello di chiamare strumenti/funzioni da voi predefiniti quando necessario. +La Claude Messages API supporta nativamente la funzionalità di chiamata di strumenti, consentendo al modello di chiamare gli strumenti/funzioni predefiniti quando necessario. ### Esempio Python @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Quando il modello decide di chiamare uno strumento, `content` nel risultato restituito conterrà un blocco di contenuto di tipo `tool_use`: +Quando il modello decide di chiamare uno strumento, il `content` nel risultato restituito conterrà un blocco di contenuto di tipo `tool_use`: ```json { @@ -640,7 +637,7 @@ Quando il modello decide di chiamare uno strumento, `content` nel risultato rest } ``` -Si noti che `stop_reason` è `tool_use`, il che indica che il modello deve chiamare lo strumento. Dopo aver ricevuto questo risultato, è necessario eseguire la funzione dello strumento e restituire il risultato al modello sotto forma di `tool_result`: +Si noti che `stop_reason` è `tool_use`, a indicare che il modello deve chiamare lo strumento. Dopo aver ricevuto questo risultato, è necessario eseguire la funzione dello strumento e restituire il risultato al modello sotto forma di `tool_result`: ```python payload = { @@ -688,34 +685,35 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Il modello genererà la risposta finale in linguaggio naturale sulla base dei risultati restituiti dallo strumento. +Il modello genererà la risposta finale in linguaggio naturale in base al risultato restituito dallo strumento. ## Differenze rispetto alla Chat Completion API Ace Data Cloud fornisce contemporaneamente due formati di Claude API, le cui principali differenze sono le seguenti: -`usage.input_tokens` della Messages API indica solo l'input non memorizzato nella cache; `cache_read_input_tokens` e `cache_creation_input_tokens` sono bucket di fatturazione indipendenti; tutti e tre verranno calcolati separatamente ai prezzi corrispondenti. +`usage.input_tokens` della Messages API rappresenta solo l'input non memorizzato nella cache, mentre `cache_read_input_tokens` e `cache_creation_input_tokens` sono bucket di fatturazione indipendenti; tutti e tre vengono calcolati separatamente in base ai rispettivi prezzi. + | Caratteristica | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Formato | Formato nativo Anthropic | Formato compatibile con OpenAI | -| Prompt di sistema | Campo `system` indipendente | Trasferito tramite `role: "system"` in `messages` | +| Prompt di sistema | Campo `system` indipendente | Trasmissione tramite `role: "system"` in `messages` | | Struttura della risposta | Array `content` (supporta più tipi) | Array `choices` (include `message`) | -| Formato streaming | Eventi SSE (molteplici tipi di eventi) | Righe SSE `data` | +| Formato streaming | Eventi SSE (più tipi di eventi) | Righe SSE `data` | | Ragionamento approfondito | `thinking` nativo e `output_config.effort` | Strategia predefinita del modello e parametri compatibili | | Chiamata di strumenti | `tools` nativo + `input_schema` | Formato `tools` compatibile con OpenAI | | Statistiche Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Se il vostro sistema è già integrato con API in formato OpenAI, potete usare la Chat Completion API per passare senza interruzioni. Se avete bisogno di utilizzare tutte le capacità native di Claude, si consiglia di utilizzare la Messages API. +Se il proprio sistema è già integrato con API in formato OpenAI, è possibile utilizzare la Chat Completion API per effettuare una transizione senza interruzioni. Se è necessario utilizzare tutte le funzionalità native di Claude, si consiglia di utilizzare la Messages API. ## Gestione degli errori -Le risposte di errore dell'interfaccia pubblica utilizzano l'envelope della piattaforma Ace Data Cloud: `error.code` è un codice di errore stabile, `error.message` è una descrizione e `trace_id` viene utilizzato per analizzare la richiesta. Gli stati HTTP comuni includono: +Le risposte di errore dell'interfaccia pubblica utilizzano l'envelope della piattaforma Ace Data Cloud: `error.code` è un codice di errore stabile, `error.message` è la descrizione e `trace_id` viene utilizzato per analizzare le richieste. Gli stati HTTP comuni includono: -- `400`: parametri della richiesta o contenuto del protocollo non validi. -- `401`: token di autorizzazione non valido, mancante o scaduto. -- `403`: accesso vietato, saldo insufficiente o quota limitata. -- `404`: API o modello inesistente. -- `413`: corpo della richiesta troppo grande. +- `400`: i parametri della richiesta o il contenuto del protocollo non sono validi. +- `401`: il token di autorizzazione non è valido, è mancante o è scaduto. +- `403`: accesso negato, saldo insufficiente o quota limitata. +- `404`: l'API o il modello non esiste. +- `413`: il corpo della richiesta è troppo grande. - `429`: troppe richieste. - `500` / `503` / `504`: errore del servizio, temporaneamente non disponibile o timeout di elaborazione. @@ -731,8 +729,7 @@ Le risposte di errore dell'interfaccia pubblica utilizzano l'envelope della piat } ``` -Questa struttura di errore è il contratto runtime di Ace Data Cloud e non equivale all'envelope di errore ufficiale di Anthropic; gestitela in base allo stato HTTP e a `error.code`. +Questa struttura di errore è il contratto di runtime di Ace Data Cloud e non equivale all'envelope di errore ufficiale di Anthropic; gestirla in base allo stato HTTP e a `error.code`. ## Conclusione - -Attraverso questo documento, avete già appreso come utilizzare la Claude Messages API per chiamare le funzionalità di conversazione di Claude nel formato nativo Anthropic. La Messages API supporta numerose funzionalità, tra cui conversazioni di base, prompt di sistema, risposte in streaming, conversazioni multi-turno, ragionamento approfondito, comprensione visiva, PDF, cache dei prompt e chiamate di strumenti. Per qualsiasi domanda, non esitate a contattare il nostro team di supporto tecnico. +Attraverso questo documento, hai già appreso come utilizzare la Claude Messages API per richiamare la funzionalità di conversazione di Claude nel formato nativo di Anthropic. La Messages API supporta funzionalità avanzate come conversazioni di base, prompt di sistema, risposte in streaming, conversazioni multi-turno, ragionamento approfondito, comprensione visiva, PDF, caching dei prompt e chiamate di strumenti. In caso di domande, non esitare a contattare il nostro team di supporto tecnico. diff --git a/ja/guides/claude/claude_messages.mdx b/ja/guides/claude/claude_messages.mdx index d6baa050..825279d4 100644 --- a/ja/guides/claude/claude_messages.mdx +++ b/ja/guides/claude/claude_messages.mdx @@ -3,19 +3,19 @@ title: "Claude Messages API の申請および使用" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude は非常に強力な AI 対話システムであり、プロンプトを入力するだけで、わずか数秒で流暢かつ自然な返信を生成できます。Claude Messages API は Anthropic 公式ネイティブの API 形式であり、OpenAI 互換形式（Chat Completion）とは異なり、Anthropic 独自のリクエストおよびレスポンス構造を採用しています。これにより、マルチモーダルコンテンツ入力、ツール呼び出し、拡張思考（Extended Thinking）などの高度な機能といった、Claude 独自の能力をより活用できます。 +Anthropic Claude は非常に強力な AI 対話システムであり、プロンプトを入力するだけで、わずか数秒で流暢で自然な応答を生成できます。Claude Messages API は Anthropic 公式ネイティブの API 形式であり、OpenAI 互換形式（Chat Completion）とは異なり、Anthropic 独自のリクエストおよびレスポンス構造を採用しています。これにより、マルチモーダルコンテンツ入力、ツール呼び出し、拡張思考（Extended Thinking）などの高度な機能といった Claude 独自の能力をより効果的に活用できます。 -本ドキュメントでは主に Claude Messages API 操作の使用フローを紹介します。これを利用することで、Anthropic 公式と一致するネイティブインターフェースを使用して Claude の対話機能を呼び出せます。 +本ドキュメントでは主に Claude Messages API 操作の使用手順を紹介します。これを利用することで、Anthropic 公式と一致するネイティブインターフェースを使用して Claude の対話機能を呼び出せます。 -## 申請フロー +## 申請手順 -Claude Messages API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) にアクセスして API Token を取得し、控えておいてください。 +Claude Messages API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、予備として保管してください。 ![](https://cdn.acedata.cloud/dvc3cg.jpg) -まだログインまたは登録していない場合は、自動的にログインページへ移動して登録とログインを案内します。完了後は自動的に現在のページへ戻ります。 +まだログインまたは登録していない場合は、ログインページに自動的に移動して登録とログインが案内され、完了後に現在のページへ自動的に戻ります。 -**1 つの API Token でプラットフォームのすべてのサービスを呼び出せるため、サービスごとに個別で申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で試用できます。クレジットが不足した場合は [コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。 +**1 つの API Token でプラットフォーム上のすべてのサービスを呼び出せるため、サービスごとに個別申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin)で共通残高をチャージできます。 > 📘 完全なドキュメント：[Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) @@ -23,22 +23,21 @@ Claude Messages API を使用するには、まず [Ace Data Cloud コンソー Claude Messages API のリクエストパスは `/v1/messages` であり、Anthropic 公式 API と一致しています。少なくとも以下の 3 つの必須パラメータを指定する必要があります。 -- `model`：使用する Claude モデルを選択します。`claude-opus-5-5` は Messages API でのみ提供され、100 万 Token のコンテキスト、最大 128K Token の出力をサポートし、常に適応型思考を有効にします。最新フラッグシップは `claude-fable-5-1`（100 万 Token のコンテキスト、最大 128K Token の出力）です。旧 `claude-fable-5` も引き続き互換性を維持しています。`claude-sonnet-5-5` はネイティブ Messages シリーズインターフェースに追加され、画像入力と適応型思考をサポートしています。その入力、出力、およびキャッシュ読み取りの公式参考価格は、100 万 Token あたりそれぞれ 2、10、および 0.20 米ドルです。 -- `messages`：入力メッセージの配列で、各メッセージには `role`（役割）と `content`（内容）が含まれます。`role` は `user` と `assistant` をサポートします。 -- `max_tokens`：最大出力 token 数で、1 回の返信の長さを制限するために使用します。 +- `model`：使用する Claude モデルを選択します。`claude-opus-5-5` は Messages API でのみ提供され、100 万 Token のコンテキスト、最大出力 128K Token をサポートし、常に適応型思考を有効にします。最新のフラッグシップは `claude-fable-5-1`（100 万 Token のコンテキスト、最大出力 128K Token）であり、従来の `claude-fable-5` も引き続き互換性を維持しています。`claude-sonnet-5-5` はネイティブ Messages シリーズインターフェースに追加され、画像入力と適応型思考をサポートしています。その入力、出力、キャッシュ読み取りの公式参考価格は、それぞれ 100 万 Token あたり 2、10、0.20 米ドルです。 +- `messages`：入力メッセージの配列であり、各メッセージには `role`（ロール）と `content`（内容）が含まれます。`role` は `user` と `assistant` をサポートします。 +- `max_tokens`：最大出力 token 数であり、1 回の応答の長さを制限するために使用します。 -一般的な任意パラメータ： +よく使用される任意パラメータ： -- `system`：モデルの動作と役割を設定するためのシステムプロンプト。 -- `temperature`：生成のランダム性。0～1 の間で、値が大きいほど返信はより発散的になります。 -- `stream`：ストリーミングレスポンスを使用するかどうか。`true` に設定すると、逐次返却の効果を実現できます。 +- `system`：システムプロンプト。モデルの動作とロールを設定するために使用します。 +- `temperature`：生成のランダム性。0～1 の間で、値が大きいほど応答はより発散的になります。 +- `stream`：ストリーミング応答を使用するかどうか。`true` に設定すると、1 文字ずつ返す効果を実現できます。 - `stop_sequences`：カスタム停止シーケンス。モデルはこれらのテキストに遭遇すると生成を停止します。 - `top_p`：核サンプリングパラメータ。temperature と組み合わせて生成のランダム性を制御します。 - `top_k`：確率が最も高い K 個の選択肢からのみサンプリングします。 -- `tools`：モデルに外部関数を呼び出させるためのツール定義。 +- `tools`：ツール定義。モデルが外部関数を呼び出せるようにするために使用します。 - `tool_choice`：モデルが提供されたツールをどのように使用するかを制御します。 -- `cache_control`：リクエスト内の最後のキャッシュ可能なコンテンツブロックにキャッシュブレークポイントを自動作成します。具体的なコンテンツブロックに記述することもできます。 -- `metadata`：任意のリクエストメタデータオブジェクト。`metadata.user_id` は文字列であり、`{"user_id":"example-user-001"}` のように、呼び出し元がカスタマイズしたユーザー識別子を渡せます。個人情報を含まない安定した識別子の使用を推奨します。これは `Authorization` 認証の代わりにはならず、`messages` の対話内容に記述する必要もありません。 +- `cache_control`：リクエストの最後のキャッシュ可能なコンテンツブロックにキャッシュブレークポイントを自動作成します。具体的なコンテンツブロックに記述することもできます。 ### cURL の例 @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -86,7 +83,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -呼び出し後、返却結果は以下のとおりです。 +呼び出し後、以下のような結果が返されます： ```json { @@ -109,25 +106,25 @@ print(response.json()) } ``` -返却結果フィールドの説明： -- `id`：今回のメッセージの一意の識別子。 -- `type`：常に `message`。 -- `role`：常に `assistant`。 -- `content`：応答内容の配列。各要素には `type`（例：`text`）と対応する内容が含まれる。 -- `model`：リクエストを処理するモデル名。 -- `stop_reason`：停止理由。安定した値には `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（現在の assistant 内容をそのまま返すことで継続可能）、`refusal`、および `model_context_window_exceeded` が含まれる。 -- `stop_sequence`：カスタム停止シーケンスによって停止した場合、一致した停止シーケンスのテキストを表示する。 -- `stop_details`：`stop_reason` が `refusal` の場合、拒否カテゴリと説明が含まれることがある。 -- `usage`：token 使用量の統計。`input_tokens` はキャッシュされていない入力、`cache_creation_input_tokens` と `cache_read_input_tokens` はそれぞれキャッシュの書き込みと読み取り、`output_tokens` はすべての出力 token 数。`output_tokens_details.thinking_tokens` が返される場合、この値は `output_tokens` のサブセットであり、合計または料金を計算する際に再度加算してはならない。この内訳は権威あるカウントがない場合、`null` であるか省略されることがある。 -- `usage.cache_creation`：オプションのキャッシュ書き込み TTL 内訳。`ephemeral_5m_input_tokens` と `ephemeral_1h_input_tokens` を含む。オブジェクトが存在する場合、両者の合計は `cache_creation_input_tokens` と等しい。フィールドが `null` または省略されている場合、現在の応答には利用可能な TTL 内訳がないことを意味し、`0` と解釈してはならない。 -- `usage.cost`：非ストリーミング応答には、Ace Data Cloud によって記録されたクレジット消費オブジェクトが含まれる場合がある。`amount` は今回の実際の消費量、`currency` は計測単位、`list_amount` は割引前の金額（該当する場合）。Fable 5.1 の公式キャッシュ読み取り基本価格は $0.25/100万 Token、5 分間および1時間のキャッシュ書き込み基本価格はそれぞれ $12.50 および $20/100万 Token。プラットフォームの実際の価格はプランの割引に応じて換算される。 +返却結果のフィールド説明： + +- `id`：今回のメッセージの一意な識別子。 +- `type`：常に `message` です。 +- `role`：常に `assistant` です。 +- `content`：応答内容の配列。各要素には `type`（例：`text`）と対応する内容が含まれます。 +- `model`：リクエストを処理したモデル名。 +- `stop_reason`：停止理由。安定した値には `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（現在の assistant 内容をそのまま返送して継続可能）、`refusal`、および `model_context_window_exceeded` が含まれます。 +- `stop_sequence`：カスタム停止シーケンスによって停止した場合、マッチした停止シーケンステキストを表示します。 +- `stop_details`：`stop_reason` が `refusal` の場合、拒否カテゴリと説明が含まれる可能性があります。 +- `usage`：token 使用統計。`input_tokens` はキャッシュされていない入力です。`cache_creation_input_tokens` と `cache_read_input_tokens` はそれぞれキャッシュ書き込みと読み取りです。`output_tokens` はすべての出力 token 数です。`output_tokens_details.thinking_tokens` が返された場合、この値は `output_tokens` の部分集合であるため、合計量または料金を計算する際に再度加算しないでください。この明細は権威あるカウントがない場合、`null` になるか省略される可能性があります。 +- `usage.cache_creation`：任意のキャッシュ書き込み TTL 明細。`ephemeral_5m_input_tokens` と `ephemeral_1h_input_tokens` を含みます。オブジェクトが存在する場合、両者の合計は `cache_creation_input_tokens` と等しくなります。フィールドが `null` または省略されている場合は、現在の応答に利用可能な TTL 内訳がないことを示し、`0` と解釈することはできません。 +- `usage.cost`：非ストリーミング応答には、Ace Data Cloud が記録したクレジット消費オブジェクトが含まれる場合があります。そのうち `amount` は今回の実際の消費量、`currency` は計量単位、`list_amount` は割引前の金額（存在する場合）です。Fable 5.1 の公式キャッシュ読み取り基本価格は 100 万 Token あたり $0.25 であり、5 分間および 1 時間のキャッシュ書き込み基本価格はそれぞれ $12.50 および $20/100 万 Token です。プラットフォームの実際の価格はプラン割引に基づいて換算されます。 ## システムプロンプト -Claude Messages API は、モデルの動作、役割、コンテキストを定義するために、`system` フィールドによるシステムプロンプトの設定をサポートしている。 +Claude Messages API は `system` フィールドを通じてシステムプロンプトを設定でき、モデルの動作、ロール、コンテキストを定義するために使用します。 ### Python の例 - ```python import requests @@ -152,11 +149,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -`system` プロンプトを設定することで、Claude の役割と動作方式を正確に制御できる。 +`system` プロンプトを設定することで、Claude の役割と動作方法を正確に制御できます。 ## ストリーミング応答 -このインターフェースはストリーミング応答にも対応しており、`stream` パラメータを `true` に設定すると段階的に返される効果を得られるため、ウェブページでの逐次表示の実装に非常に適している。 +このインターフェースはストリーミング応答にも対応しており、`stream` パラメータを `true` に設定すると段階的に返される効果を得られます。これはウェブページでの一文字ずつの表示を実現するのに非常に適しています。 ### Python の例 @@ -186,16 +183,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -ストリーミング応答は Server-Sent Events (SSE) 形式で返され、各行は `event:` と `data:` で始まる。ストリーミングイベントの種類には以下が含まれる： +ストリーミング応答は Server-Sent Events (SSE) 形式で返され、各行は `event:` と `data:` で始まります。ストリーミングイベントの種類には以下が含まれます： -- `message_start`：メッセージ開始。メッセージの基本情報とモデル名を含む。 -- `content_block_start`：コンテンツブロック開始。 -- `content_block_delta`：コンテンツブロックの増分更新。新たに生成されたテキスト断片を含む。 -- `content_block_stop`：コンテンツブロック終了。 -- `message_delta`：メッセージレベルの増分更新。`stop_reason` と最終的な `usage` 情報を含む。`output_tokens_details.thinking_tokens` の権威ある値は、最後の `message_delta.usage` からのみ読み取るべきであり、イベントをまたいで累積してはならない。 -- `message_stop`：メッセージ終了。 +- `message_start`：メッセージの開始。メッセージの基本情報とモデル名を含みます。 +- `content_block_start`：コンテンツブロックの開始。 +- `content_block_delta`：コンテンツブロックの増分更新。新しく生成されたテキスト断片を含みます。 +- `content_block_stop`：コンテンツブロックの終了。 +- `message_delta`：メッセージレベルの増分更新。`stop_reason` と最終的な `usage` 情報を含みます。`output_tokens_details.thinking_tokens` の権威ある値は、最後の `message_delta.usage` からのみ読み取るべきであり、イベントをまたいで累算しないでください。 +- `message_stop`：メッセージの終了。 -出力結果は以下のとおり： +出力効果は以下のとおりです： ``` event: message_start @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -確認できるように、ストリーミング応答の `content_block_delta` イベントには段階的に生成されるテキスト内容が含まれており、すべての `text_delta` を連結することで完全な応答を取得できる。 +ご覧のとおり、ストリーミング応答では `content_block_delta` イベントに段階的に生成されるテキスト内容が含まれており、すべての `text_delta` を連結することで完全な応答を取得できます。 ### JavaScript の例 @@ -254,9 +251,9 @@ while (true) { } ``` -## マルチターン会話 +## マルチターン対話 -マルチターン会話機能を連携したい場合は、`messages` 配列内で `user` と `assistant` ロールのメッセージを交互に並べ、これまでの会話履歴をまとめて渡す必要がある。 +マルチターン対話機能を連携したい場合は、`messages` 配列内で `user` と `assistant` ロールのメッセージを交互に配置し、それまでの対話履歴をあわせて渡す必要があります。 ### Python の例 @@ -285,7 +282,8 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -返却結果は以下のとおり： +返される結果は以下のとおりです： + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ print(response.json()) } ``` -`messages` で完全な会話履歴を渡すことで、Claude はコンテキストを踏まえて正確に回答できます。 +`messages` で完全な対話履歴を渡すことで、Claude はコンテキストを組み合わせて正確に回答できます。 ## 深い思考モデル -Claude の thinking と thinking summary は異なる概念です。モデルは内部推論を行えますが、API は元の思考連鎖を返しません。推論プロセスを表示する必要がある場合、API が返すのは処理済みの要約です。 +Claude の thinking と thinking summary は異なる2つの概念です。モデルは内部推論を行えますが、API は元の思考連鎖を返しません。推論過程を表示する必要がある場合、API が返すのは処理済みの要約です。 -現在のモデルでは adaptive thinking の使用が推奨されており、`output_config.effort` によって全体的な推論投入量を制御します。 +現在のモデルでは adaptive thinking の使用が推奨されており、`output_config.effort` によって全体的な推論投入量を制御します： ```python import requests @@ -343,7 +341,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -レスポンス内の thinking ブロックは以下のような形式です。 +応答内の thinking ブロックは次のような形式です： ```json { @@ -352,25 +350,24 @@ print(response.json()) "signature": "opaque-signature" } ``` +- `display: "summarized"` は読みやすい思考要約を返します；これは生の思考連鎖ではありません。 +- `display: "omitted"` は `thinking: ""` を返しますが、後続の会話をサポートするため opaque な `signature` は引き続き保持します。 +- `display: "updates"` は Anthropic の beta モードであり、`anthropic-beta: thinking-display-updates-2026-08-18` を付加する必要があります。公式の定義では、推論本文を非表示にし、ツール呼び出しの間に短い進捗更新を表示します。プラットフォームはこのパラメータと beta リクエストヘッダーを元の値のまま渡し、強制的に `summarized` へ書き換えることはありません；実際の出力内容は、選択したモデルのサポート状況に依存します。 +- `thinking`、`output_config`、effort、サンプリングパラメータおよび新規拡張フィールドは、元の値のまま渡されます。プラットフォームはモデルごとにハードコードされた値の列挙や組み合わせ制限を維持せず、thinking モードを自動的に書き換えることもありません；これらのパラメータを受け入れるかどうかは選択したモデルが判断し、モデルが返すパラメータエラーはクライアントに返されます。 +- Fable 5.1、Fable 5、Opus 5、Sonnet 5、Opus 4.8 および Opus 4.7 の display のデフォルト値は `omitted` です；Opus 4.6、Sonnet 4.6 およびそれ以前の thinking をサポートするモデルでは、デフォルトで `summarized` を使用します。 +- Display は返される内容とストリーミング遅延にのみ影響し、推論を無効化することも、thinking token の課金を減らすこともありません。 +- thinking がデフォルトで有効かどうかと、display のデフォルト値は2つの独立した問題です。Opus 5、Sonnet 5 では adaptive thinking がデフォルトで有効です；Opus 5 では、`thinking` を省略することは adaptive と同等であり、`output_config.effort` を省略することは `high` と同等です。Opus 4.8、4.7 および 4.6 では明示的な有効化が必要です。 +- Thinking と最終本文はともに `max_tokens` の出力予算を消費します。予算が小さすぎる場合、thinking が大部分の枠を占有し、本文が空になるか切り詰められる可能性があります；`max_tokens` を増やすか、`low` / `medium` effort を使用して推論の投入量を制御してください。 +- thinking を無効化できるモデルでは、`thinking: {"type":"disabled"}` を渡すことができます。`between_tools` などの新しいモードおよび effort の組み合わせは、選択したモデルに依存します；プラットフォームは古いモデルルールに基づいて事前に拒否しません。 +- 固定の思考予算は `budget_tokens` を通じて渡すことができます；新しいモデルでは通常、`thinking.type=adaptive` と `output_config.effort` を使用します。固定予算または思考の無効化をサポートするかどうかは、選択したモデルの現在の能力に準拠します。 +- マルチターン会話とツール呼び出しでは、assistant が返した完全な thinking ブロックおよび signature をそのまま返すべきです；signature を変更したり、自身で生成したりしないでください。 +- パラメータの透過渡しは、すべてのモデルがすべての機能をサポートすることを意味するものではありません。プロトコルをまたぐ呼び出しでは引き続き変換が必要であり、`redacted_thinking` などの内容のサポート範囲とエラーは、実際にリクエストを処理するモデルサービスによって決まります。 -- `display: "summarized"` は読みやすい思考の要約を返します。これは元の思考連鎖ではありません。 -- `display: "omitted"` は `thinking: ""` を返しますが、後続の会話をサポートするため opaque `signature` は保持されます。 -- `display: "updates"` は Anthropic の beta モードであり、`anthropic-beta: thinking-display-updates-2026-08-18` を付加する必要があります。公式の定義では、推論本文を隠し、ツール呼び出しの間に短い進捗更新を表示します。プラットフォームはこのパラメータと beta リクエストヘッダーを元の値のまま渡し、`summarized` へ強制的に書き換えることはありません。実際の出力内容は、選択したモデルのサポート状況に依存します。 -- `thinking`、`output_config`、effort、サンプリングパラメータ、および追加の拡張フィールドは元の値のまま渡されます。プラットフォームは、モデルごとにハードコードされた値の列挙や組み合わせ制限を維持せず、thinking モードを自動的に書き換えることもありません。これらのパラメータを受け入れるかどうかは選択したモデルが判断し、モデルが返すパラメータエラーはクライアントへ返送されます。 -- Fable 5.1、Fable 5、Opus 5、Sonnet 5、Opus 4.8、および Opus 4.7 の display のデフォルト値は `omitted` です。Opus 4.6、Sonnet 4.6、およびそれ以前の thinking をサポートするモデルは、デフォルトで `summarized` を使用します。 -- Display は返される内容とストリーミング遅延にのみ影響し、推論を無効にしたり、thinking token の課金を減らしたりすることはありません。 -- thinking をデフォルトで有効にするかどうかと、display のデフォルト値は二つの独立した問題です。Opus 5 と Sonnet 5 はデフォルトで adaptive thinking を有効にします。Opus 5 では、`thinking` を省略することは adaptive と同等であり、`output_config.effort` を省略することは `high` と同等です。Opus 4.8、4.7、および 4.6 では明示的に有効にする必要があります。 -- Thinking と最終本文はともに `max_tokens` の出力予算を消費します。予算が小さすぎる場合、thinking が大部分の枠を消費し、本文が空になるか切り詰められる可能性があります。`max_tokens` を増やすか、`low` / `medium` effort を使用して推論投入量を制御してください。 -- thinking を無効にできるモデルでは、`thinking: {"type":"disabled"}` を渡せます。`between_tools` などの新しいモードおよび effort の組み合わせは、選択したモデルに依存します。プラットフォームは古いモデル規則に基づいて事前に拒否しません。 -- 固定の思考予算は `budget_tokens` を介して渡せます。新しいモデルでは通常、`thinking.type=adaptive` と `output_config.effort` を使用します。固定予算または思考の無効化をサポートするかどうかは、選択したモデルの現在の機能に依存します。 -- マルチターン会話およびツール呼び出しでは、assistant が返した完全な thinking ブロックと signature をそのまま返す必要があります。signature を変更したり、自分で生成したりしないでください。 -- パラメータの透過は、すべてのモデルがすべての機能をサポートすることを意味しません。プロトコルをまたぐ呼び出しでは依然として変換が必要であり、`redacted_thinking` などのコンテンツのサポート範囲とエラーは、実際にリクエストを処理するモデルサービスによって決まります。 - -ストリーミングリクエストでは、`summarized` は `thinking_delta` を生成します。`omitted` は `thinking_delta` を生成せず、thinking ブロックのライフサイクルと `signature_delta` のみを保持します。 +ストリーミングリクエストでは、`summarized` は `thinking_delta` を生成します；`omitted` は `thinking_delta` を生成せず、thinking ブロックのライフサイクルと `signature_delta` のみを保持します。 -## ビジュアルモデル +## ビジョンモデル -Claude はマルチモーダル入力をサポートしており、テキストと画像を同時に処理できます。Messages API では、`content` を配列形式に設定し、画像コンテンツブロックを渡すことでビジュアル機能を使用できます。 +Claude はマルチモーダル入力をサポートしており、テキストと画像を同時に処理できます。Messages API では、`content` を配列形式に設定し、画像コンテンツブロックを渡すことでビジョン機能を使用できます。 ### Base64 エンコード画像を使用する @@ -459,6 +456,7 @@ print(response.json()) ``` ### cURL の例 + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -492,7 +490,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ ## ドキュメントと PDF -PDF では `document` コンテンツブロックを使用し、Base64 と URL の 2 種類の安定したソースをサポートします。Base64 ソースでは必ず `application/pdf` を使用する必要があります。 +PDF では `document` コンテンツブロックを使用し、Base64 と URL の2種類の安定したソースをサポートします。Base64 ソースでは必ず `application/pdf` を使用する必要があります： ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -URL ソースは `{"type":"url","url":"https://example.com/report.pdf"}` と記述します。`document` はさらに `text/plain` および text/image ブロックで構成される `content` ソースをサポートします。任意フィールドには `title`、`context`、`citations` が含まれます。Files API の `file_id` ソースは独立した beta 機能に属し、本インターフェースの安定した契約には含まれません。 +URL ソースは `{"type":"url","url":"https://example.com/report.pdf"}` と記述します。`document` は `text/plain` および text/image ブロックで構成される `content` ソースもサポートします；オプションフィールドには `title`、`context`、`citations` が含まれます。Files API の `file_id` ソースは独立した beta 機能に属しており、本インターフェースの安定した契約には含まれません。 ## プロンプトキャッシュ -トップレベルの `cache_control` は、最後のキャッシュ可能なブロックにキャッシュブレークポイントを自動的に配置します。 +トップレベルの `cache_control` は、最後のキャッシュ可能なブロックにキャッシュのブレークポイントを自動的に配置します： ```python payload = { @@ -536,10 +534,9 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +位置を正確に制御する必要がある場合は、同じ `cache_control` を text、image、document、tool_use、tool_result のコンテンツブロックまたはツール定義に記述することもできます。`ttl` は `5m`（デフォルト）と `1h` をサポートします。`usage.cache_creation_input_tokens` と `usage.cache_read_input_tokens` を通じて、キャッシュの書き込みとヒットを判断してください。 -位置を正確に制御する必要がある場合は、同じ `cache_control` を text、image、document、tool_use、tool_result コンテンツブロック、またはツール定義に記述することもできます。`ttl` は `5m`（デフォルト）と `1h` をサポートします。キャッシュの書き込みとヒットは `usage.cache_creation_input_tokens` および `usage.cache_read_input_tokens` で判断してください。 - -レスポンスが `usage.cache_creation` を提供する場合、`ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens` です。`cache_creation` が `null` または省略されている場合、キャッシュ書き込みの合計のみで、信頼できる TTL の内訳がないことを示します。この場合、いずれの bucket も既知の 0 と見なさないでください。課金と合計は引き続き aggregate フィールドに基づきます。 +レスポンスに `usage.cache_creation` が含まれる場合、`ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens` です。`cache_creation` が `null` または省略されている場合、キャッシュ書き込みの合計量のみがあり、権威ある TTL 内訳がないことを示します。この場合、いずれかの bucket を既知の 0 と見なさないでください。課金と合計量は引き続き aggregate フィールドに従います。 返却結果の例： @@ -566,7 +563,7 @@ payload = { ## ツール呼び出し（Tool Use） -Claude Messages API はツール呼び出し機能をネイティブにサポートしており、モデルは必要に応じて事前定義されたツール/関数を呼び出すことができます。 +Claude Messages API はツール呼び出し機能をネイティブにサポートしており、必要に応じてモデルが事前定義されたツール／関数を呼び出すことを可能にします。 ### Python の例 @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -モデルがツールの呼び出しを決定すると、返却結果の `content` には `tool_use` タイプのコンテンツブロックが含まれます。 +モデルがツールを呼び出すことを決定すると、返却結果の `content` には `tool_use` タイプのコンテンツブロックが含まれます。 ```json { @@ -688,30 +685,31 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -モデルはツールが返した結果に基づいて、最終的な自然言語の応答を生成します。 +モデルはツールから返された結果に基づいて、最終的な自然言語の応答を生成します。 ## Chat Completion API との違い Ace Data Cloud は 2 種類の Claude API 形式を同時に提供しており、両者の主な違いは以下のとおりです。 -Messages API の `usage.input_tokens` はキャッシュされていない入力のみを示し、`cache_read_input_tokens` と `cache_creation_input_tokens` は独立した課金バケットです。3 つはそれぞれ対応する価格で計算されます。 -| 特性 | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +Messages API の `usage.input_tokens` はキャッシュされていない入力のみを表し、`cache_read_input_tokens` と `cache_creation_input_tokens` は独立した課金バケットです。3 つはそれぞれ対応する価格で計算されます。 + +| 機能 | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | 形式 | Anthropic ネイティブ形式 | OpenAI 互換形式 | | システムプロンプト | 独立した `system` フィールド | `messages` 内の `role: "system"` を通じて渡す | -| レスポンス構造 | `content` 配列（複数のタイプをサポート） | `choices` 配列（`message` を含む） | +| レスポンス構造 | `content` 配列（複数の型をサポート） | `choices` 配列（`message` を含む） | | ストリーミング形式 | SSE イベント（複数のイベントタイプ） | SSE `data` 行 | | 深い思考 | ネイティブの `thinking` と `output_config.effort` | モデルのデフォルト戦略と互換パラメータ | | ツール呼び出し | ネイティブの `tools` + `input_schema` | OpenAI 互換の `tools` 形式 | | Token 統計 | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -お客様のシステムがすでに OpenAI 形式の API に接続されている場合は、Chat Completion API を使用してシームレスに切り替えることができます。Claude のすべてのネイティブ機能を使用する必要がある場合は、Messages API を使用することをお勧めします。 +システムがすでに OpenAI 形式の API に接続されている場合は、Chat Completion API を使用してシームレスに切り替えることができます。Claude のすべてのネイティブ機能を使用する必要がある場合は、Messages API の使用を推奨します。 ## エラー処理 -公開インターフェースのエラーレスポンスは Ace Data Cloud プラットフォームの envelope を使用します：`error.code` は安定したエラーコード、`error.message` は説明、`trace_id` はリクエストの調査に使用されます。一般的な HTTP ステータスには以下が含まれます： +公開インターフェースのエラーレスポンスでは、Ace Data Cloud プラットフォームの envelope を使用します。`error.code` は安定したエラーコード、`error.message` は説明、`trace_id` はリクエストの調査に使用されます。一般的な HTTP ステータスは以下のとおりです。 -- `400`：リクエストパラメータまたはプロトコル内容が無効です。 +- `400`：リクエストパラメータまたはプロトコルの内容が無効です。 - `401`：認可トークンが無効、欠落、または期限切れです。 - `403`：アクセス禁止、残高不足、またはクォータ制限です。 - `404`：API またはモデルが存在しません。 @@ -731,8 +729,7 @@ Messages API の `usage.input_tokens` はキャッシュされていない入力 } ``` -このエラー構造は Ace Data Cloud のランタイム契約であり、Anthropic 公式のエラー envelope と同等ではありません。HTTP ステータスと `error.code` に従って処理してください。 +このエラー構造は Ace Data Cloud のランタイム契約であり、Anthropic 公式のエラー envelope と同一ではありません。HTTP ステータスと `error.code` に従って処理してください。 ## 結論 - -本ドキュメントを通じて、Anthropic ネイティブ形式で Claude Messages API を使用して Claude の対話機能を呼び出す方法を理解しました。Messages API は、基本的な対話、システムプロンプト、ストリーミングレスポンス、マルチターン対話、深い思考、視覚理解、PDF、プロンプトキャッシュ、ツール呼び出しなどの豊富な機能をサポートしています。ご不明な点がございましたら、いつでも当社の技術サポートチームまでお問い合わせください。 +このドキュメントを通じて、Anthropic ネイティブ形式で Claude Messages API を使用して Claude の対話機能を呼び出す方法を理解しました。Messages API は、基本的な対話、システムプロンプト、ストリーミング応答、複数ターンの対話、拡張思考、視覚理解、PDF、プロンプトキャッシュ、ツール呼び出しなどの豊富な機能をサポートしています。ご不明な点がございましたら、いつでも当社のテクニカルサポートチームまでお問い合わせください。 diff --git a/ko/guides/claude/claude_messages.mdx b/ko/guides/claude/claude_messages.mdx index b51bfb15..e76506a4 100644 --- a/ko/guides/claude/claude_messages.mdx +++ b/ko/guides/claude/claude_messages.mdx @@ -3,7 +3,7 @@ title: "Claude Messages API 신청 및 사용" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude는 매우 강력한 AI 대화 시스템으로, 프롬프트를 입력하기만 하면 단 몇 초 만에 매끄럽고 자연스러운 응답을 생성할 수 있습니다. Claude Messages API는 Anthropic 공식 네이티브 API 형식으로, OpenAI 호환 형식(Chat Completion)과 달리 Anthropic 자체 요청 및 응답 구조를 채택하여 멀티모달 콘텐츠 입력, 도구 호출, 심층 사고(Extended Thinking) 등의 고급 기능과 같은 Claude의 고유한 능력을 더 잘 활용할 수 있습니다. +Anthropic Claude는 매우 강력한 AI 대화 시스템으로, 프롬프트를 입력하기만 하면 단 몇 초 만에 유창하고 자연스러운 응답을 생성할 수 있습니다. Claude Messages API는 Anthropic의 공식 네이티브 API 형식으로, OpenAI 호환 형식(Chat Completion)과 달리 Anthropic 고유의 요청 및 응답 구조를 사용하며, 멀티모달 콘텐츠 입력, 도구 호출, 심층 사고(Extended Thinking) 등의 고급 기능과 같은 Claude의 고유한 능력을 더 잘 활용할 수 있습니다. 이 문서는 주로 Claude Messages API 작업의 사용 절차를 소개하며, 이를 통해 Anthropic 공식과 일치하는 네이티브 인터페이스를 사용하여 Claude의 대화 기능을 호출할 수 있습니다. @@ -13,32 +13,31 @@ Claude Messages API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://pl ![](https://cdn.acedata.cloud/dvc3cg.jpg) -아직 로그인하거나 등록하지 않았다면 로그인 페이지로 자동 이동하여 등록 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 반환됩니다. +아직 로그인하거나 가입하지 않았다면 로그인 페이지로 자동 이동하여 가입 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 반환됩니다. -**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 범용 잔액을 충전할 수 있습니다. +**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스별로 별도 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 공용 잔액을 충전할 수 있습니다. > 📘 전체 문서: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## 기본 사용 -Claude Messages API의 요청 경로는 `/v1/messages`이며, Anthropic 공식 API와 일치합니다. 최소한 다음 세 가지 필수 매개변수를 제공해야 합니다: +Claude Messages API의 요청 경로는 `/v1/messages`이며, Anthropic 공식 API와 일치합니다. 최소한 다음 세 가지 필수 파라미터를 제공해야 합니다. -- `model`: 사용할 Claude 모델을 선택합니다. `claude-opus-5-5`는 Messages API를 통해서만 제공되며, 100만 Token 컨텍스트, 최대 출력 128K Token을 지원하고 적응형 사고를 항상 활성화합니다. 최신 플래그십은 `claude-fable-5-1`(100만 Token 컨텍스트, 최대 출력 128K Token)이며, 기존 `claude-fable-5`도 계속 호환 유지됩니다. `claude-sonnet-5-5`는 네이티브 Messages 시리즈 인터페이스에 추가되었으며, 이미지 입력과 적응형 사고를 지원합니다. 입력, 출력 및 캐시 읽기에 대한 공식 참고 가격은 각각 백만 Token당 2, 10 및 0.20달러입니다. +- `model`: 사용할 Claude 모델을 선택합니다. `claude-opus-5-5`는 Messages API를 통해서만 제공되며, 100만 Token 컨텍스트, 최대 출력 128K Token을 지원하고 항상 적응형 사고를 활성화합니다. 최신 플래그십은 `claude-fable-5-1`(100만 Token 컨텍스트, 최대 출력 128K Token)이며, 기존 `claude-fable-5`도 계속 호환 유지됩니다. `claude-sonnet-5-5`는 네이티브 Messages 시리즈 인터페이스에 추가되었으며, 이미지 입력과 적응형 사고를 지원합니다. 입력, 출력 및 캐시 읽기의 공식 기준 가격은 각각 100만 Token당 2, 10 및 0.20달러입니다. - `messages`: 입력 메시지 배열로, 각 메시지는 `role`(역할)과 `content`(내용)를 포함하며, `role`은 `user`와 `assistant`를 지원합니다. - `max_tokens`: 최대 출력 token 수로, 단일 응답의 길이를 제한하는 데 사용됩니다. -자주 사용하는 선택적 매개변수: +자주 사용하는 선택적 파라미터: -- `system`: 시스템 프롬프트로, 모델의 행동과 역할을 설정하는 데 사용됩니다. -- `temperature`: 생성 무작위성으로, 0-1 사이이며 값이 클수록 응답이 더 발산됩니다. -- `stream`: 스트리밍 응답 사용 여부로, `true`로 설정하면 한 글자씩 반환하는 효과를 구현할 수 있습니다. -- `stop_sequences`: 사용자 지정 중지 시퀀스로, 모델은 이러한 텍스트를 만나면 생성을 중지합니다. -- `top_p`: 핵 샘플링 매개변수로, temperature와 함께 생성의 무작위성을 제어합니다. -- `top_k`: 확률이 가장 높은 K개 옵션에서만 샘플링합니다. -- `tools`: 도구 정의로, 모델이 외부 함수를 호출하도록 하는 데 사용됩니다. +- `system`: 모델의 동작과 역할을 설정하는 시스템 프롬프트입니다. +- `temperature`: 생성 무작위성으로, 0-1 사이이며 값이 클수록 응답이 더 분산됩니다. +- `stream`: 스트리밍 응답 사용 여부로, `true`로 설정하면 글자 단위 반환 효과를 구현할 수 있습니다. +- `stop_sequences`: 사용자 정의 중지 시퀀스로, 모델은 이러한 텍스트를 만나면 생성을 중지합니다. +- `top_p`: 핵 샘플링 파라미터로, temperature와 함께 생성의 무작위성을 제어합니다. +- `top_k`: 확률이 가장 높은 K개 선택지에서만 샘플링합니다. +- `tools`: 모델이 외부 함수를 호출하도록 하는 도구 정의입니다. - `tool_choice`: 모델이 제공된 도구를 사용하는 방식을 제어합니다. - `cache_control`: 요청의 마지막 캐시 가능한 콘텐츠 블록에서 자동으로 캐시 중단점을 생성하며, 구체적인 콘텐츠 블록에 작성할 수도 있습니다. -- `metadata`: 선택적 요청 메타데이터 객체입니다. `metadata.user_id`는 문자열로, 예를 들어 `{"user_id":"example-user-001"}`와 같이 호출자 맞춤 사용자 식별자를 전달할 수 있으며, 개인 정보를 포함하지 않는 안정적인 식별자를 사용하는 것이 권장됩니다. 이는 `Authorization` 인증을 대체하지 않으며, `messages` 대화 내용에 작성할 필요도 없습니다. ### cURL 예시 @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -110,24 +107,24 @@ print(response.json()) ``` 반환 결과 필드 설명: + - `id`: 이번 메시지의 고유 식별자입니다. - `type`: 항상 `message`입니다. - `role`: 항상 `assistant`입니다. -- `content`: 응답 내용 배열이며, 각 요소는 `type`(예: `text`)과 해당 내용을 포함합니다. -- `model`: 요청을 처리하는 모델 이름입니다. -- `stop_reason`: 중지 이유입니다. 안정적인 값에는 `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn`(현재 assistant 내용을 원본 그대로 다시 전달하여 계속 진행 가능), `refusal`, `model_context_window_exceeded`가 포함됩니다. -- `stop_sequence`: 사용자 지정 중지 시퀀스로 인해 중지된 경우, 일치한 중지 시퀀스 텍스트를 표시합니다. +- `content`: 응답 내용 배열이며, 각 요소는 `type`(예: `text`) 및 해당 내용을 포함합니다. +- `model`: 요청을 처리한 모델 이름입니다. +- `stop_reason`: 중지 사유입니다. 안정적인 값에는 `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn`(계속하려면 현재 assistant 내용을 원본 그대로 다시 전달 가능), `refusal` 및 `model_context_window_exceeded`가 포함됩니다. +- `stop_sequence`: 사용자 정의 중지 시퀀스로 인해 중지된 경우, 일치하는 중지 시퀀스 텍스트를 표시합니다. - `stop_details`: `stop_reason`이 `refusal`인 경우, 거부 카테고리와 설명을 포함할 수 있습니다. -- `usage`: token 사용 통계입니다. `input_tokens`는 캐시되지 않은 입력이고, `cache_creation_input_tokens`와 `cache_read_input_tokens`는 각각 캐시 쓰기와 읽기이며, `output_tokens`는 전체 출력 token 수입니다. `output_tokens_details.thinking_tokens`가 반환되는 경우, 이 값은 `output_tokens`의 하위 집합이므로 총량 또는 비용 계산 시 다시 더하지 마십시오. 이 세부 정보는 권위 있는 집계가 없을 경우 `null`이거나 생략될 수 있습니다. -- `usage.cache_creation`: 선택적 캐시 쓰기 TTL 세부 정보로, `ephemeral_5m_input_tokens`와 `ephemeral_1h_input_tokens`를 포함합니다. 객체가 존재하는 경우 두 항목의 합은 `cache_creation_input_tokens`와 같으며, 필드가 `null`이거나 생략된 경우 현재 응답에 사용 가능한 TTL 분류가 없다는 의미이지 `0`으로 해석해서는 안 됩니다. -- `usage.cost`: 비스트리밍 응답에는 Ace Data Cloud가 기록한 크레딧 소비 객체가 포함될 수 있으며, 이 중 `amount`는 이번 실제 소비량, `currency`는 측정 단위, `list_amount`는 할인 전 금액(있는 경우)입니다. Fable 5.1의 공식 캐시 읽기 기본 가격은 $0.25/백만 Token이고, 5분 및 1시간 캐시 쓰기 기본 가격은 각각 $12.50 및 $20/백만 Token입니다. 플랫폼 실제 가격은 요금제 할인에 따라 환산됩니다. +- `usage`: token 사용 통계입니다. `input_tokens`는 캐시되지 않은 입력이며, `cache_creation_input_tokens`와 `cache_read_input_tokens`는 각각 캐시 쓰기 및 읽기입니다. `output_tokens`는 전체 출력 token 수입니다. `output_tokens_details.thinking_tokens`가 반환되는 경우 이 값은 `output_tokens`의 부분집합이므로, 총량 또는 비용을 계산할 때 다시 더하지 마세요. 이 세부 정보는 권위 있는 집계가 없을 경우 `null`이거나 생략될 수 있습니다. +- `usage.cache_creation`: 선택적인 캐시 쓰기 TTL 세부 정보로, `ephemeral_5m_input_tokens` 및 `ephemeral_1h_input_tokens`를 포함합니다. 객체가 존재할 경우 두 항목의 합은 `cache_creation_input_tokens`와 같으며, 필드가 `null`이거나 생략된 경우 현재 응답에 사용 가능한 TTL 분할이 없음을 의미하므로 `0`으로 해석할 수 없습니다. +- `usage.cost`: 비스트리밍 응답에는 Ace Data Cloud가 기록한 크레딧 소모 객체가 포함될 수 있으며, `amount`는 이번 실제 소모량, `currency`는 계량 단위, `list_amount`는 할인 전 금액(있는 경우)입니다. Fable 5.1의 공식 캐시 읽기 기준 가격은 100만 Token당 $0.25이며, 5분 및 1시간 캐시 쓰기 기준 가격은 각각 $12.50 및 $20/100만 Token입니다. 플랫폼 실제 가격은 요금제 할인에 따라 환산됩니다. ## 시스템 프롬프트 -Claude Messages API는 모델의 행동, 역할 및 컨텍스트를 정의하는 데 사용되는 `system` 필드를 통해 시스템 프롬프트 설정을 지원합니다. +Claude Messages API는 `system` 필드를 통해 시스템 프롬프트를 설정할 수 있으며, 모델의 동작, 역할 및 컨텍스트를 정의하는 데 사용됩니다. ### Python 예시 - ```python import requests @@ -142,7 +139,7 @@ headers = { payload = { "model": "claude-sonnet-4-20250514", "max_tokens": 1024, - "system": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。", + "system": "당신은 전문적인 중국어 번역 도우미입니다. 사용자가 입력한 영어를 중국어로 번역해 주세요.", "messages": [ {"role": "user", "content": "The quick brown fox jumps over the lazy dog."} ] @@ -152,11 +149,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -`system` 프롬프트를 설정하면 Claude의 역할과 행동 방식을 정확하게 제어할 수 있습니다. +`system` 프롬프트를 설정하면 Claude의 역할과 행동 방식을 정밀하게 제어할 수 있습니다. ## 스트리밍 응답 -이 인터페이스는 스트리밍 응답도 지원하며, `stream` 매개변수를 `true`로 설정하면 점진적으로 반환되는 효과를 얻을 수 있어 웹페이지에서 글자 단위 표시를 구현하는 데 매우 적합합니다. +이 인터페이스는 스트리밍 응답도 지원합니다. `stream` 매개변수를 `true`로 설정하면 점진적으로 반환되는 효과를 얻을 수 있으며, 웹 페이지에서 한 글자씩 표시하는 기능을 구현하는 데 매우 적합합니다. ### Python 예시 @@ -186,13 +183,13 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -스트리밍 응답은 Server-Sent Events (SSE) 형식으로 반환되며, 각 줄은 `event:` 및 `data:`로 시작합니다. 스트리밍 이벤트 유형에는 다음이 포함됩니다. +스트리밍 응답은 Server-Sent Events (SSE) 형식으로 반환되며, 각 줄은 `event:` 및 `data:`로 시작합니다. 스트리밍 이벤트 유형은 다음과 같습니다. -- `message_start`: 메시지 시작으로, 메시지의 기본 정보와 모델 이름을 포함합니다. +- `message_start`: 메시지 시작이며, 메시지의 기본 정보와 모델 이름을 포함합니다. - `content_block_start`: 콘텐츠 블록 시작입니다. -- `content_block_delta`: 콘텐츠 블록 증분 업데이트로, 새로 생성된 텍스트 조각을 포함합니다. +- `content_block_delta`: 콘텐츠 블록의 증분 업데이트이며, 새로 생성된 텍스트 조각을 포함합니다. - `content_block_stop`: 콘텐츠 블록 종료입니다. -- `message_delta`: 메시지 수준의 증분 업데이트로, `stop_reason`과 최종 `usage` 정보를 포함합니다. `output_tokens_details.thinking_tokens`의 권위 있는 값은 마지막 `message_delta.usage`에서만 읽어야 하며, 이벤트 간에 누적하지 마십시오. +- `message_delta`: 메시지 수준의 증분 업데이트이며, `stop_reason` 및 최종 `usage` 정보를 포함합니다. `output_tokens_details.thinking_tokens`의 권위 있는 값은 마지막 `message_delta.usage`에서만 읽어야 하며, 이벤트 간에 누적하지 마세요. - `message_stop`: 메시지 종료입니다. 출력 효과는 다음과 같습니다. @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -알 수 있듯이, 스트리밍 응답의 `content_block_delta` 이벤트에는 점진적으로 생성되는 텍스트 내용이 포함되어 있으며, 모든 `text_delta`를 연결하면 완전한 응답을 얻을 수 있습니다. +스트리밍 응답에서 `content_block_delta` 이벤트는 점진적으로 생성되는 텍스트 내용을 포함하며, 모든 `text_delta`를 연결하면 완전한 응답을 얻을 수 있습니다. ### JavaScript 예시 @@ -256,7 +253,7 @@ while (true) { ## 다중 턴 대화 -다중 턴 대화 기능을 연동하려면, `messages` 배열에서 `user`와 `assistant` 역할의 메시지를 번갈아 배치하고 이전 대화 기록을 함께 전달해야 합니다. +다중 턴 대화 기능을 연동하려면 `messages` 배열에서 `user` 및 `assistant` 역할의 메시지를 번갈아 배치하고, 이전 대화 기록도 함께 전달해야 합니다. ### Python 예시 @@ -286,6 +283,7 @@ print(response.json()) ``` 반환 결과는 다음과 같습니다. + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,11 +305,11 @@ print(response.json()) } ``` -`messages`에 전체 대화 기록을 전달하면 Claude는 문맥을 결합하여 정확하게 답변할 수 있습니다. +`messages`에서 전체 대화 기록을 전달하면 Claude는 문맥을 결합하여 정확하게 답변할 수 있습니다. ## 심층 사고 모델 -Claude의 thinking과 thinking summary는 서로 다른 두 개념입니다. 모델은 내부 추론을 수행할 수 있지만, API는 원본 사고 사슬을 반환하지 않습니다. 추론 과정을 표시해야 할 때 API가 반환하는 것은 처리된 요약입니다. +Claude의 thinking과 thinking summary는 서로 다른 두 가지 개념입니다. 모델은 내부 추론을 수행할 수 있지만 API는 원본 사고 사슬을 반환하지 않습니다. 추론 과정을 표시해야 할 경우 API는 처리된 요약을 반환합니다. 현재 모델에서는 adaptive thinking 사용을 권장하며, `output_config.effort`를 통해 전체 추론 투입량을 제어합니다. @@ -352,21 +350,20 @@ print(response.json()) "signature": "opaque-signature" } ``` - -- `display: "summarized"`는 읽을 수 있는 사고 요약을 반환합니다. 이는 원본 사고 사슬이 아닙니다. -- `display: "omitted"`는 `thinking: ""`를 반환하지만, 이후 대화를 지원하기 위해 opaque `signature`는 유지합니다. -- `display: "updates"`는 Anthropic의 beta 모드이며, `anthropic-beta: thinking-display-updates-2026-08-18`를 포함해야 합니다. 공식 정의는 추론 본문을 숨기고 도구 호출 사이의 짧은 진행 업데이트를 표시하는 것입니다. 플랫폼은 이 파라미터와 beta 요청 헤더를 원래 값 그대로 전달하며, `summarized`로 강제 변경하지 않습니다. 실제 출력 내용은 선택한 모델의 지원 여부에 따라 달라집니다. -- `thinking`, `output_config`, effort, 샘플링 파라미터 및 새 확장 필드는 원래 값 그대로 전달됩니다. 플랫폼은 모델별로 하드코딩된 값 열거나 조합 제한을 유지하지 않으며, thinking 모드를 자동으로 변경하지도 않습니다. 이 파라미터를 수락할지는 선택한 모델이 판단하며, 모델이 반환한 파라미터 오류는 클라이언트에 전달됩니다. -- Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 및 Opus 4.7의 display 기본값은 `omitted`이며, Opus 4.6, Sonnet 4.6 및 그 이전의 thinking 지원 모델은 기본적으로 `summarized`를 사용합니다. +- `display: "summarized"`는 읽기 쉬운 사고 요약을 반환합니다. 이는 원시 사고 체인이 아닙니다. +- `display: "omitted"`는 `thinking: ""`를 반환하지만, 후속 대화를 지원하기 위해 opaque `signature`는 계속 유지합니다. +- `display: "updates"`는 Anthropic의 beta 모드이며, `anthropic-beta: thinking-display-updates-2026-08-18`을 함께 전송해야 합니다. 공식 정의는 추론 본문을 숨기고 도구 호출 사이에 짧은 진행 상황 업데이트를 표시하는 것입니다. 플랫폼은 이 매개변수와 beta 요청 헤더를 원래 값 그대로 전달하며, 강제로 `summarized`로 재작성하지 않습니다. 실제 출력 내용은 선택한 모델의 지원 여부에 따라 달라집니다. +- `thinking`, `output_config`, effort, 샘플링 매개변수 및 새 확장 필드는 원래 값 그대로 전달됩니다. 플랫폼은 모델별로 하드코딩된 값 열거나 조합 제한을 유지하지 않으며, thinking 모드를 자동으로 재작성하지도 않습니다. 이러한 매개변수를 수락할지는 선택한 모델이 판단하며, 모델이 반환한 매개변수 오류는 클라이언트에 전달됩니다. +- Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 및 Opus 4.7의 display 기본값은 `omitted`입니다. Opus 4.6, Sonnet 4.6 및 더 이전의 thinking 지원 모델은 기본적으로 `summarized`를 사용합니다. - Display는 반환 내용과 스트리밍 지연에만 영향을 미치며, 추론을 끄거나 thinking token 청구량을 줄이지 않습니다. -- thinking이 기본적으로 활성화되는지와 display 기본값은 서로 독립적인 두 문제입니다. Opus 5와 Sonnet 5는 기본적으로 adaptive thinking을 활성화하며, Opus 5의 경우 `thinking`을 생략하는 것은 adaptive와 같고, `output_config.effort`를 생략하는 것은 `high`와 같습니다. Opus 4.8, 4.7 및 4.6은 명시적으로 활성화해야 합니다. -- Thinking과 최종 본문은 함께 `max_tokens` 출력 예산을 사용합니다. 예산이 너무 작으면 thinking이 대부분의 할당량을 차지하여 본문이 비어 있거나 잘릴 수 있습니다. `max_tokens`를 늘리거나 `low` / `medium` effort를 사용하여 추론 투입량을 제어하십시오. -- thinking을 끌 수 있는 모델의 경우 `thinking: {"type":"disabled"}`를 전달할 수 있습니다. `between_tools` 등의 새 모드와 effort 조합은 선택한 모델에 따라 달라지며, 플랫폼은 이전 모델 규칙에 따라 사전에 거부하지 않습니다. -- 고정 사고 예산은 `budget_tokens`를 통해 전달할 수 있습니다. 새 모델은 일반적으로 `thinking.type=adaptive`와 `output_config.effort`를 사용합니다. 고정 예산 또는 사고 비활성화 지원 여부는 선택한 모델의 현재 기능을 기준으로 합니다. -- 다중 턴 대화 및 도구 호출 시 assistant가 반환한 전체 thinking 블록과 signature를 원래대로 다시 전달해야 합니다. signature를 수정하거나 직접 생성하지 마십시오. -- 파라미터 전달이 모든 모델이 모든 기능을 지원한다는 의미는 아닙니다. 프로토콜 간 호출은 여전히 변환이 필요하며, `redacted_thinking` 등의 내용 지원 범위와 오류는 실제로 요청을 처리하는 모델 서비스가 결정합니다. +- 기본적으로 thinking을 활성화하는지와 display 기본값은 서로 독립된 두 가지 문제입니다. Opus 5와 Sonnet 5는 기본적으로 adaptive thinking을 활성화합니다. Opus 5의 경우 `thinking`을 생략하는 것은 adaptive와 동일하며, `output_config.effort`를 생략하는 것은 `high`와 동일합니다. Opus 4.8, 4.7 및 4.6은 명시적으로 활성화해야 합니다. +- Thinking과 최종 본문은 함께 `max_tokens` 출력 예산을 사용합니다. 예산이 너무 작으면 thinking이 대부분의 할당량을 차지하여 본문이 비어 있거나 잘릴 수 있습니다. `max_tokens`를 늘리거나 `low` / `medium` effort를 사용하여 추론 투입량을 제어하세요. +- thinking을 끌 수 있는 모델의 경우 `thinking: {"type":"disabled"}`를 전달할 수 있습니다. `between_tools` 등의 새 모드 및 effort 조합은 선택한 모델에 따라 달라집니다. 플랫폼은 이전 모델 규칙에 따라 사전에 거부하지 않습니다. +- 고정 사고 예산은 `budget_tokens`를 통해 전달할 수 있습니다. 새 모델은 일반적으로 `thinking.type=adaptive` 및 `output_config.effort`를 사용합니다. 고정 예산 또는 사고 비활성화 지원 여부는 선택한 모델의 현재 기능을 기준으로 합니다. +- 다중 턴 대화 및 도구 호출 시 assistant가 반환한 완전한 thinking 블록과 signature를 원본 그대로 다시 전달해야 합니다. signature를 수정하거나 직접 생성하지 마세요. +- 매개변수 전달은 모든 모델이 모든 기능을 지원한다는 것을 의미하지 않습니다. 프로토콜 간 호출에는 여전히 변환이 필요하며, `redacted_thinking` 등의 콘텐츠 지원 범위와 오류는 실제로 요청을 처리하는 모델 서비스가 결정합니다. -스트리밍 요청에서 `summarized`는 `thinking_delta`를 생성하며, `omitted`는 `thinking_delta`를 생성하지 않고 thinking 블록 수명 주기와 `signature_delta`만 유지합니다. +스트리밍 요청에서 `summarized`는 `thinking_delta`를 생성합니다. `omitted`는 `thinking_delta`를 생성하지 않고, thinking 블록 수명 주기와 `signature_delta`만 유지합니다. ## 비전 모델 @@ -459,6 +456,7 @@ print(response.json()) ``` ### cURL 예시 + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -492,7 +490,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ ## 문서 및 PDF -PDF는 `document` 콘텐츠 블록을 사용하며, Base64와 URL이라는 두 가지 안정적인 소스를 지원합니다. Base64 소스는 반드시 `application/pdf`를 사용해야 합니다: +PDF는 `document` 콘텐츠 블록을 사용하며, Base64와 URL 두 가지 안정적인 소스를 지원합니다. Base64 소스는 반드시 `application/pdf`를 사용해야 합니다. ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -URL 소스는 `{"type":"url","url":"https://example.com/report.pdf"}`로 작성합니다. `document`는 `text/plain`과 text/image 블록으로 구성된 `content` 소스도 지원합니다. 선택적 필드에는 `title`, `context`, `citations`가 포함됩니다. Files API의 `file_id` 소스는 독립적인 beta 기능에 속하며, 본 인터페이스의 안정적인 계약에 포함되지 않습니다. +URL 소스는 `{"type":"url","url":"https://example.com/report.pdf"}`로 작성합니다. `document`는 `text/plain` 및 text/image 블록으로 구성된 `content` 소스도 지원합니다. 선택적 필드에는 `title`, `context`, `citations`가 포함됩니다. Files API의 `file_id` 소스는 독립적인 beta 기능에 속하며, 이 인터페이스의 안정적인 계약에 포함되지 않습니다. -## 프롬프트 캐싱 +## 프롬프트 캐시 -최상위 `cache_control`은 마지막 캐시 가능한 블록에 캐시 중단점을 자동으로 배치합니다: +최상위 `cache_control`은 캐시 중단점을 마지막 캐시 가능 블록에 자동으로 배치합니다. ```python payload = { @@ -536,10 +534,9 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +정확한 위치 제어가 필요할 때는 동일한 `cache_control`을 text, image, document, tool_use, tool_result 콘텐츠 블록 또는 도구 정의에 작성할 수도 있습니다. `ttl`은 `5m`(기본값)과 `1h`를 지원합니다. `usage.cache_creation_input_tokens` 및 `usage.cache_read_input_tokens`를 통해 캐시 쓰기와 적중을 판단하십시오. -위치를 정확하게 제어해야 하는 경우, 동일한 `cache_control`을 text, image, document, tool_use, tool_result 콘텐츠 블록 또는 도구 정의에 작성할 수도 있습니다. `ttl`은 `5m`(기본값) 및 `1h`를 지원합니다. `usage.cache_creation_input_tokens` 및 `usage.cache_read_input_tokens`를 통해 캐시 쓰기 및 적중 여부를 판단하십시오. - -응답이 `usage.cache_creation`을 제공하는 경우, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`입니다. `cache_creation`이 `null`이거나 생략된 경우, 캐시 쓰기 총량만 있고 권위 있는 TTL 분할이 없음을 의미합니다. 이때 어느 bucket도 알려진 0으로 간주하지 마십시오. 과금 및 총량은 여전히 aggregate 필드를 기준으로 합니다. +응답에서 `usage.cache_creation`이 제공되는 경우, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`입니다. `cache_creation`이 `null`이거나 생략된 경우, 캐시 쓰기 총량만 있고 권위 있는 TTL 분할은 없음을 의미합니다. 이때 어느 bucket도 알려진 0으로 간주하지 마십시오. 과금 및 총량은 여전히 aggregate 필드를 기준으로 합니다. 반환 결과 예시: @@ -564,9 +561,9 @@ payload = { } ``` -## 도구 호출(Tool Use) +## 도구 호출（Tool Use） -Claude Messages API는 도구 호출 기능을 기본적으로 지원하며, 모델이 필요할 때 사전 정의한 도구/함수를 호출할 수 있도록 합니다. +Claude Messages API는 기본적으로 도구 호출 기능을 지원하며, 모델이 필요할 때 사전 정의한 도구/함수를 호출할 수 있도록 합니다. ### Python 예시 @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -모델이 도구 호출을 결정하면 반환 결과의 `content`에는 `tool_use` 유형의 콘텐츠 블록이 포함됩니다: +모델이 도구 호출을 결정하면, 반환 결과의 `content`에는 `tool_use` 유형의 콘텐츠 블록이 포함됩니다: ```json { @@ -640,7 +637,7 @@ print(response.json()) } ``` -`stop_reason`이 `tool_use`인 점에 유의하십시오. 이는 모델이 도구를 호출해야 함을 의미합니다. 해당 결과를 받은 후에는 도구 함수를 실행하고 결과를 `tool_result` 형식으로 모델에 다시 전달해야 합니다: +`stop_reason`이 `tool_use`라는 점에 유의하십시오. 이는 모델이 도구를 호출해야 함을 나타냅니다. 이 결과를 받은 후에는 도구 함수를 실행하고 결과를 `tool_result` 형식으로 모델에 다시 전달해야 합니다: ```python payload = { @@ -692,28 +689,29 @@ print(response.json()) ## Chat Completion API와의 차이점 -Ace Data Cloud는 두 가지 Claude API 형식을 동시에 제공하며, 두 형식의 주요 차이점은 다음과 같습니다: +Ace Data Cloud는 두 가지 Claude API 형식을 동시에 제공하며, 둘의 주요 차이점은 다음과 같습니다: + +Messages API의 `usage.input_tokens`는 캐시되지 않은 입력만을 의미하며, `cache_read_input_tokens`와 `cache_creation_input_tokens`는 독립적인 과금 버킷입니다. 세 항목은 각각 해당 가격에 따라 계산됩니다. -Messages API의 `usage.input_tokens`는 캐시되지 않은 입력만 나타내며, `cache_read_input_tokens`와 `cache_creation_input_tokens`는 독립적인 과금 버킷입니다. 세 항목은 각각 해당 가격에 따라 계산됩니다. | 특성 | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | 형식 | Anthropic 네이티브 형식 | OpenAI 호환 형식 | -| 시스템 프롬프트 | 독립적인 `system` 필드 | `messages` 내의 `role: "system"`을 통해 전달 | +| 시스템 프롬프트 | 독립된 `system` 필드 | `messages`의 `role: "system"`을 통해 전달 | | 응답 구조 | `content` 배열(여러 유형 지원) | `choices` 배열(`message` 포함) | | 스트리밍 형식 | SSE 이벤트(여러 이벤트 유형) | SSE `data` 행 | -| 심층 사고 | 네이티브 `thinking` 및 `output_config.effort` | 모델 기본 정책 및 호환 파라미터 | +| 심층 사고 | 네이티브 `thinking` 및 `output_config.effort` | 모델 기본 전략 및 호환 파라미터 | | 도구 호출 | 네이티브 `tools` + `input_schema` | OpenAI 호환 `tools` 형식 | | Token 통계 | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -시스템이 이미 OpenAI 형식의 API와 연동되어 있다면 Chat Completion API를 사용하여 원활하게 전환할 수 있습니다. Claude의 모든 네이티브 기능을 사용해야 하는 경우 Messages API 사용을 권장합니다. +시스템이 이미 OpenAI 형식의 API와 연동되어 있다면 Chat Completion API를 사용하여 원활하게 전환할 수 있습니다. Claude의 모든 네이티브 기능을 사용해야 한다면 Messages API 사용을 권장합니다. ## 오류 처리 -공개 인터페이스의 오류 응답은 Ace Data Cloud 플랫폼 envelope를 사용합니다. `error.code`는 안정적인 오류 코드이고, `error.message`는 설명이며, `trace_id`는 요청을 조사하는 데 사용됩니다. 일반적인 HTTP 상태는 다음과 같습니다. +공개 인터페이스의 오류 응답은 Ace Data Cloud 플랫폼 envelope를 사용합니다: `error.code`는 안정적인 오류 코드이고, `error.message`는 설명이며, `trace_id`는 요청 문제를 조사하는 데 사용됩니다. 일반적인 HTTP 상태는 다음과 같습니다: - `400`: 요청 파라미터 또는 프로토콜 내용이 유효하지 않습니다. - `401`: 인증 토큰이 유효하지 않거나, 누락되었거나, 만료되었습니다. -- `403`: 접근이 금지되었거나, 잔액이 부족하거나, 할당량이 제한되었습니다. +- `403`: 접근 금지, 잔액 부족 또는 할당량 제한입니다. - `404`: API 또는 모델이 존재하지 않습니다. - `413`: 요청 본문이 너무 큽니다. - `429`: 요청이 너무 많습니다. @@ -731,8 +729,7 @@ Messages API의 `usage.input_tokens`는 캐시되지 않은 입력만 나타내 } ``` -이 오류 구조는 Ace Data Cloud의 런타임 계약이며, Anthropic 공식 오류 envelope와 동일하지 않습니다. HTTP 상태와 `error.code`에 따라 처리하십시오. +이 오류 구조는 Ace Data Cloud의 런타임 계약이며, Anthropic 공식 오류 envelope와 동일하지 않습니다. HTTP 상태 및 `error.code`에 따라 처리하십시오. ## 결론 - -이 문서를 통해 Anthropic 네이티브 형식으로 Claude Messages API를 사용하여 Claude의 대화 기능을 호출하는 방법을 이해했습니다. Messages API는 기본 대화, 시스템 프롬프트, 스트리밍 응답, 멀티턴 대화, 심층 사고, 시각적 이해, PDF, 프롬프트 캐싱 및 도구 호출 등의 풍부한 기능을 지원합니다. 궁금한 사항이 있으면 언제든지 기술 지원 팀에 문의하십시오. +이 문서를 통해 Anthropic 네이티브 형식으로 Claude Messages API를 사용하여 Claude의 대화 기능을 호출하는 방법을 이미 알아보았습니다. Messages API는 기본 대화, 시스템 프롬프트, 스트리밍 응답, 다중 턴 대화, 심층 사고, 시각적 이해, PDF, 프롬프트 캐싱 및 도구 호출 등 풍부한 기능을 지원합니다. 궁금한 사항이 있으시면 언제든지 기술 지원팀에 문의해 주세요. diff --git a/pl/guides/claude/claude_messages.mdx b/pl/guides/claude/claude_messages.mdx index 1ce46666..8b394b3a 100644 --- a/pl/guides/claude/claude_messages.mdx +++ b/pl/guides/claude/claude_messages.mdx @@ -1,21 +1,21 @@ --- -title: "Wnioskowanie o Claude Messages API i jego użycie" +title: "Wniosek o Claude Messages API i jego użycie" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude to bardzo potężny system konwersacyjny AI, który po wprowadzeniu promptu potrafi w zaledwie kilka sekund wygenerować płynną i naturalną odpowiedź. Claude Messages API jest oficjalnym natywnym formatem API Anthropic, różniącym się od formatu kompatybilnego z OpenAI (Chat Completion), wykorzystuje własną strukturę żądań i odpowiedzi Anthropic, co pozwala lepiej wykorzystać unikalne możliwości Claude, takie jak multimodalne wprowadzanie treści, wywoływanie narzędzi, głębokie myślenie (Extended Thinking) i inne zaawansowane funkcje. +Anthropic Claude to bardzo potężny system konwersacyjny AI, który po prostu po wprowadzeniu promptu potrafi w ciągu kilku sekund wygenerować płynną i naturalną odpowiedź. Claude Messages API to oficjalny, natywny format API Anthropic. W odróżnieniu od formatu kompatybilnego z OpenAI (Chat Completion), wykorzystuje własną strukturę żądań i odpowiedzi Anthropic, co pozwala lepiej wykorzystywać unikalne możliwości Claude, takie jak wielomodalne wprowadzanie treści, wywoływanie narzędzi, pogłębione myślenie (Extended Thinking) oraz inne zaawansowane funkcje. -Ten dokument przedstawia głównie proces używania operacji Claude Messages API, dzięki któremu możemy korzystać z natywnego interfejsu zgodnego z oficjalnym Anthropic, aby wywoływać funkcję konwersacji Claude. +Ten dokument przedstawia głównie proces korzystania z Claude Messages API. Za jego pomocą możemy używać natywnego interfejsu zgodnego z oficjalnym Anthropic do wywoływania funkcji konwersacyjnych Claude. -## Proces wnioskowania +## Proces składania wniosku -Aby używać Claude Messages API, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój API Token i zachować go do użycia później. +Aby korzystać z Claude Messages API, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój API Token i zachować go do późniejszego użycia. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zaprosi Cię do rejestracji i zalogowania się, a po zakończeniu automatycznie powrócisz na bieżącą stronę. +Jeśli nie jesteś jeszcze zalogowany ani zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, gdzie zostaniesz zaproszony do rejestracji i zalogowania się. Po zakończeniu automatycznie wrócisz na bieżącą stronę. -**Jeden API Token pozwala wywoływać wszystkie usługi platformy, nie ma potrzeby składania osobnego wniosku dla każdej usługi.** Przy pierwszym wnioskowaniu otrzymasz bezpłatny limit, z którego możesz korzystać bezpłatnie; gdy limit jest niewystarczający, możesz doładować ogólne saldo w [konsoli](https://platform.acedata.cloud/console/coin). +**Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez konieczności składania osobnego wniosku dla każdej usługi.** Przy pierwszym wniosku otrzymasz bezpłatny limit, aby móc korzystać z bezpłatnego okresu próbnego; gdy limit będzie niewystarczający, możesz doładować uniwersalne saldo w [konsoli](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) @@ -23,22 +23,21 @@ Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, zostaniesz automatyczn Ścieżka żądania Claude Messages API to `/v1/messages`, zgodna z oficjalnym API Anthropic. Musimy podać co najmniej trzy wymagane parametry: -- `model`: wybierz używany model Claude. `claude-opus-5-5` jest udostępniany wyłącznie przez Messages API, obsługuje kontekst 1 miliona Tokenów, maksymalne wyjście 128K Tokenów i zawsze włącza adaptacyjne myślenie. Najnowszym flagowym modelem jest `claude-fable-5-1` (kontekst 1 miliona Tokenów, maksymalne wyjście 128K Tokenów); wcześniejszy `claude-fable-5` nadal jest zachowany dla kompatybilności. `claude-sonnet-5-5` został dodany do natywnego interfejsu serii Messages, obsługuje wejście obrazów i adaptacyjne myślenie; jego oficjalne ceny referencyjne za wejście, wyjście i odczyt z pamięci podręcznej wynoszą odpowiednio 2, 10 i 0,20 USD za milion Tokenów. -- `messages`: tablica wiadomości wejściowych, każda wiadomość zawiera `role` (rolę) i `content` (treść), gdzie `role` obsługuje `user` i `assistant`. -- `max_tokens`: maksymalna liczba tokenów wyjściowych, używana do ograniczenia długości pojedynczej odpowiedzi. +- `model`: wybór używanego modelu Claude. `claude-opus-5-5` jest dostępny wyłącznie przez Messages API, obsługuje kontekst 1 miliona Tokenów, maksymalne wyjście 128K Tokenów i zawsze ma włączone adaptacyjne myślenie. Najnowszym flagowym modelem jest `claude-fable-5-1` (kontekst 1 miliona Tokenów, maksymalne wyjście 128K Tokenów); wcześniejszy `claude-fable-5` pozostaje nadal zachowany dla zgodności. `claude-sonnet-5-5` został dodany do natywnego interfejsu serii Messages i obsługuje wejście obrazowe oraz adaptacyjne myślenie; jego oficjalne ceny referencyjne za wejście, wyjście i odczyt z pamięci podręcznej wynoszą odpowiednio 2, 10 i 0,20 USD za milion Tokenów. +- `messages`: tablica wprowadzanych wiadomości, gdzie każda wiadomość zawiera `role` (rolę) oraz `content` (treść), a `role` obsługuje `user` i `assistant`. +- `max_tokens`: maksymalna liczba tokenów wyjściowych, używana do ograniczania długości pojedynczej odpowiedzi. Często używane parametry opcjonalne: -- `system`: prompt systemowy, używany do określenia zachowania i roli modelu. -- `temperature`: losowość generowania, między 0 a 1, im większa wartość, tym bardziej rozproszone odpowiedzi. -- `stream`: czy używać odpowiedzi strumieniowej, ustawienie `true` pozwala uzyskać efekt zwracania znak po znaku. -- `stop_sequences`: niestandardowe sekwencje zatrzymania, model przestanie generować po napotkaniu tych tekstów. -- `top_p`: parametr próbkowania jądrowego, współpracuje z temperature w celu kontrolowania losowości generowania. -- `top_k`: próbkowanie wyłącznie spośród K opcji o najwyższym prawdopodobieństwie. -- `tools`: definicje narzędzi, używane do umożliwienia modelowi wywoływania zewnętrznych funkcji. -- `tool_choice`: kontroluje, jak model używa dostarczonych narzędzi. -- `cache_control`: automatycznie tworzy punkt przerwania pamięci podręcznej przy ostatnim zawartościowym bloku możliwym do zapisania w pamięci podręcznej żądania; można też zapisać go w konkretnym bloku treści. -- `metadata`: opcjonalny obiekt metadanych żądania. `metadata.user_id` jest ciągiem znaków i może przekazywać niestandardowy identyfikator użytkownika wywołującego, na przykład `{"user_id":"example-user-001"}`; zaleca się używanie stabilnego identyfikatora niezawierającego danych osobowych. Nie zastępuje on uwierzytelniania `Authorization` ani nie musi być zapisywany w treści konwersacji `messages`. +- `system`: systemowy prompt, używany do ustawiania zachowania i roli modelu. +- `temperature`: losowość generowania, wartość od 0 do 1; im większa wartość, tym bardziej rozbieżne odpowiedzi. +- `stream`: czy używać odpowiedzi strumieniowej; ustawienie na `true` pozwala uzyskać efekt zwracania znak po znaku. +- `stop_sequences`: niestandardowe sekwencje zatrzymania; model przestanie generować po napotkaniu tych tekstów. +- `top_p`: parametr próbkowania jądrowego, który wraz z temperature kontroluje losowość generowania. +- `top_k`: próbkuje wyłącznie spośród K opcji o najwyższym prawdopodobieństwie. +- `tools`: definicje narzędzi, używane, aby umożliwić modelowi wywoływanie funkcji zewnętrznych. +- `tool_choice`: kontroluje sposób używania przez model dostarczonych narzędzi. +- `cache_control`: automatycznie tworzy punkt przerwania pamięci podręcznej przy ostatnim buforowalnym bloku treści w żądaniu; można go również umieścić w konkretnym bloku treści. ### Przykład cURL @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -86,7 +83,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Po wywołaniu wynik zwracany jest następujący: +Po wywołaniu wynik zwracany jest następująco: ```json { @@ -110,24 +107,24 @@ Po wywołaniu wynik zwracany jest następujący: ``` Opis pól wyniku zwracanego: -- `id`: Unikalny identyfikator tej wiadomości. -- `type`: Zawsze `message`. -- `role`: Zawsze `assistant`. -- `content`: Tablica treści odpowiedzi, każdy element zawiera `type` (np. `text`) oraz odpowiadającą mu treść. -- `model`: Nazwa modelu przetwarzającego żądanie. -- `stop_reason`: Powód zatrzymania. Stabilne wartości obejmują `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (można zwrócić bieżącą treść assistant bez zmian, aby kontynuować), `refusal` oraz `model_context_window_exceeded`. -- `stop_sequence`: Jeśli zatrzymanie nastąpiło z powodu niestandardowej sekwencji zatrzymania, wyświetla dopasowany tekst sekwencji zatrzymania. -- `stop_details`: Gdy `stop_reason` ma wartość `refusal`, może zawierać kategorię odmowy i opis. -- `usage`: Statystyki użycia tokenów. `input_tokens` to niebuforowane dane wejściowe; `cache_creation_input_tokens` i `cache_read_input_tokens` oznaczają odpowiednio zapis do pamięci podręcznej i odczyt z niej; `output_tokens` to całkowita liczba tokenów wyjściowych. Jeśli zwracane jest `output_tokens_details.thinking_tokens`, ta wartość jest podzbiorem `output_tokens`, więc nie należy jej ponownie dodawać podczas obliczania sumy lub kosztu. Ten szczegół może mieć wartość `null` lub być pominięty, gdy nie ma autorytatywnego licznika. -- `usage.cache_creation`: Opcjonalne szczegóły TTL zapisu do pamięci podręcznej, zawierające `ephemeral_5m_input_tokens` i `ephemeral_1h_input_tokens`. Gdy obiekt istnieje, suma tych dwóch wartości jest równa `cache_creation_input_tokens`; wartość `null` lub pominięcie pola oznacza, że bieżąca odpowiedź nie ma dostępnego podziału TTL i nie należy interpretować tego jako `0`. -- `usage.cost`: Odpowiedzi niestreamowane mogą zawierać obiekt zużycia limitu zarejestrowany przez Ace Data Cloud, gdzie `amount` to faktyczne zużycie w tym żądaniu, `currency` to jednostka rozliczeniowa, a `list_amount` to kwota przed rabatem (jeśli występuje). Oficjalna cena bazowa odczytu z pamięci podręcznej dla Fable 5.1 wynosi $0.25/milion tokenów, a ceny bazowe zapisu do pamięci podręcznej na 5 minut i 1 godzinę wynoszą odpowiednio $12.50 i $20/milion tokenów; rzeczywiste ceny platformy są przeliczane zgodnie ze zniżkami planu. -## Komunikat systemowy +- `id`: unikalny identyfikator tej wiadomości. +- `type`: zawsze `message`. +- `role`: zawsze `assistant`. +- `content`: tablica treści odpowiedzi, gdzie każdy element zawiera `type` (np. `text`) oraz odpowiadającą mu treść. +- `model`: nazwa modelu przetwarzającego żądanie. +- `stop_reason`: powód zatrzymania. Stabilne wartości obejmują `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (można zwrócić bieżącą treść assistant bez zmian, aby kontynuować), `refusal` oraz `model_context_window_exceeded`. +- `stop_sequence`: jeśli zatrzymanie nastąpiło z powodu niestandardowej sekwencji zatrzymania, wyświetla pasujący tekst sekwencji zatrzymania. +- `stop_details`: gdy `stop_reason` ma wartość `refusal`, może zawierać kategorię odmowy oraz opis. +- `usage`: statystyki użycia tokenów. `input_tokens` oznacza niewykorzystane z pamięci podręcznej wejście; `cache_creation_input_tokens` i `cache_read_input_tokens` oznaczają odpowiednio zapis i odczyt z pamięci podręcznej; `output_tokens` to całkowita liczba tokenów wyjściowych. Jeśli zwracane jest `output_tokens_details.thinking_tokens`, wartość ta jest podzbiorem `output_tokens` i nie należy jej ponownie dodawać przy obliczaniu sumy lub kosztu. Gdy brak autorytatywnego licznika dla tego zestawienia, może ono mieć wartość `null` lub zostać pominięte. +- `usage.cache_creation`: opcjonalne zestawienie TTL zapisu do pamięci podręcznej, zawierające `ephemeral_5m_input_tokens` oraz `ephemeral_1h_input_tokens`. Gdy obiekt istnieje, suma obu wartości jest równa `cache_creation_input_tokens`; wartość pola `null` lub pominięcie oznacza, że bieżąca odpowiedź nie ma dostępnego podziału TTL i nie może być interpretowana jako `0`. +- `usage.cost`: odpowiedzi niestrumieniowe mogą zawierać obiekt zużycia limitu zarejestrowany przez Ace Data Cloud, gdzie `amount` oznacza rzeczywiste zużycie w tym przypadku, `currency` jest jednostką rozliczeniową, a `list_amount` to kwota przed rabatem (jeśli występuje). Oficjalne ceny bazowe Fable 5.1 za odczyt z pamięci podręcznej wynoszą $0.25/milion Tokenów, a ceny bazowe zapisu do pamięci podręcznej na 5 minut i 1 godzinę wynoszą odpowiednio $12.50 i $20/milion Tokenów; rzeczywiste ceny na platformie są przeliczane zgodnie z rabatem pakietu. -Claude Messages API obsługuje ustawianie komunikatu systemowego za pomocą pola `system`, używanego do definiowania zachowania, roli i kontekstu modelu. +## Systemowy prompt -### Przykład w Pythonie +Claude Messages API obsługuje ustawianie systemowego promptu za pomocą pola `system`, używanego do definiowania zachowania, roli i kontekstu modelu. +### Przykład Python ```python import requests @@ -152,13 +149,13 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Poprzez ustawienie komunikatu `system` można precyzyjnie kontrolować rolę i sposób zachowania Claude'a. +Poprzez ustawienie promptu `system` można precyzyjnie kontrolować rolę i sposób działania Claude. ## Odpowiedzi strumieniowe -Ten interfejs obsługuje również odpowiedzi strumieniowe; ustawienie parametru `stream` na `true` pozwala uzyskać efekt stopniowego zwracania, co doskonale nadaje się do implementacji wyświetlania znak po znaku na stronie internetowej. +Ten interfejs również obsługuje odpowiedzi strumieniowe — ustawienie parametru `stream` na `true` umożliwia uzyskanie efektu stopniowego zwracania, co bardzo dobrze nadaje się do implementacji wyświetlania znak po znaku na stronie internetowej. -### Przykład w Pythonie +### Przykład Python ```python import requests @@ -186,16 +183,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Odpowiedzi strumieniowe są zwracane w formacie Server-Sent Events (SSE), przy czym każda linia ma prefiks `event:` i `data:`. Typy zdarzeń strumieniowych obejmują: +Odpowiedź strumieniowa jest zwracana w formacie Server-Sent Events (SSE), a każda linia rozpoczyna się od `event:` i `data:`. Typy zdarzeń strumieniowych obejmują: -- `message_start`: Rozpoczęcie wiadomości, zawiera podstawowe informacje o wiadomości i nazwę modelu. -- `content_block_start`: Rozpoczęcie bloku treści. -- `content_block_delta`: Przyrostowa aktualizacja bloku treści, zawiera nowo wygenerowany fragment tekstu. -- `content_block_stop`: Zakończenie bloku treści. -- `message_delta`: Przyrostowa aktualizacja na poziomie wiadomości, zawiera informacje `stop_reason` i końcowe `usage`. Autorytatywną wartość `output_tokens_details.thinking_tokens` należy odczytywać wyłącznie z ostatniego `message_delta.usage`, nie należy sumować jej między zdarzeniami. -- `message_stop`: Zakończenie wiadomości. +- `message_start`: rozpoczęcie wiadomości, zawiera podstawowe informacje o wiadomości i nazwę modelu. +- `content_block_start`: rozpoczęcie bloku treści. +- `content_block_delta`: przyrostowa aktualizacja bloku treści, zawiera nowo wygenerowany fragment tekstu. +- `content_block_stop`: zakończenie bloku treści. +- `message_delta`: przyrostowa aktualizacja na poziomie wiadomości, zawiera informacje `stop_reason` i końcowe `usage`. Miarodajną wartość `output_tokens_details.thinking_tokens` należy odczytywać wyłącznie z ostatniego `message_delta.usage`, nie należy sumować jej między zdarzeniami. +- `message_stop`: zakończenie wiadomości. -Efekt wyjściowy jest następujący: +Wynik wyjściowy wygląda następująco: ``` event: message_start @@ -223,9 +220,9 @@ event: message_stop data: {"type":"message_stop"} ``` -Jak można zauważyć, zdarzenia `content_block_delta` w odpowiedzi strumieniowej zawierają stopniowo generowaną treść tekstową, a połączenie wszystkich `text_delta` pozwala uzyskać pełną odpowiedź. +Jak widać, w odpowiedzi strumieniowej zdarzenia `content_block_delta` zawierają stopniowo generowaną treść tekstową, a pełną odpowiedź można uzyskać przez połączenie wszystkich `text_delta`. -### Przykład w JavaScript +### Przykład JavaScript ```javascript const options = { @@ -256,9 +253,9 @@ while (true) { ## Rozmowy wieloturowe -Jeśli chcesz korzystać z funkcji rozmów wieloturowych, musisz naprzemiennie umieszczać wiadomości ról `user` i `assistant` w tablicy `messages`, przekazując razem całą wcześniejszą historię rozmowy. +Jeśli chcesz podłączyć funkcję rozmów wieloturowych, musisz naprzemiennie umieścić wiadomości o rolach `user` i `assistant` w tablicy `messages`, przekazując jednocześnie poprzednią historię rozmowy. -### Przykład w Pythonie +### Przykład Python ```python import requests @@ -285,7 +282,8 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Wynik zwracany jest następująco: +Wynik zwracany jest następujący: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -309,11 +307,11 @@ Wynik zwracany jest następująco: Przekazując pełną historię rozmowy w `messages`, Claude może udzielać dokładnych odpowiedzi z uwzględnieniem kontekstu. -## Modele głębokiego rozumowania +## Model głębokiego rozumowania -Thinking Claude'a i thinking summary to dwa różne pojęcia: model może prowadzić wewnętrzne rozumowanie, ale API nie zwraca oryginalnego łańcucha myśli. Gdy konieczne jest pokazanie procesu rozumowania, API zwraca przetworzone podsumowanie. +Thinking i thinking summary Claude to dwa różne pojęcia: model może przeprowadzać wewnętrzne rozumowanie, ale API nie zwraca oryginalnego łańcucha myśli. Gdy wymagane jest wyświetlenie procesu rozumowania, API zwraca przetworzone podsumowanie. -W przypadku obecnych modeli zalecane jest używanie adaptive thinking oraz kontrolowanie ogólnego nakładu rozumowania za pomocą `output_config.effort`: +Obecne modele zalecają używanie adaptive thinking oraz kontrolowanie ogólnego nakładu rozumowania za pomocą `output_config.effort`: ```python import requests @@ -352,25 +350,24 @@ Blok thinking w odpowiedzi wygląda następująco: "signature": "opaque-signature" } ``` - -- `display: "summarized"` zwraca czytelne podsumowanie rozumowania; nie jest to oryginalny łańcuch myśli. -- `display: "omitted"` zwraca `thinking: ""`, ale nadal zachowuje opaque `signature`, aby wspierać kolejne rozmowy. -- `display: "updates"` to beta tryb Anthropic, który wymaga przekazania `anthropic-beta: thinking-display-updates-2026-08-18`. Oficjalna definicja mówi o ukrywaniu treści rozumowania i wyświetlaniu krótkich aktualizacji postępu między wywołaniami narzędzi. Platforma przekazuje ten parametr i nagłówek beta w oryginalnej postaci, nie wymuszając zmiany na `summarized`; rzeczywista zawartość wyjścia zależy od obsługi wybranego modelu. -- `thinking`, `output_config`, effort, parametry próbkowania oraz nowe rozszerzone pola są przekazywane w oryginalnej postaci. Platforma nie utrzymuje zakodowanych na stałe dla poszczególnych modeli wyliczeń wartości ani ograniczeń kombinacji, a także nie zmienia automatycznie trybu thinking; o przyjęciu tych parametrów decyduje wybrany model, a błędy parametrów zwrócone przez model są przekazywane klientowi. +- `display: "summarized"` zwraca czytelne podsumowanie toku rozumowania; nie jest ono surowym łańcuchem myśli. +- `display: "omitted"` zwraca `thinking: ""`, ale nadal zachowuje nieprzezroczysty `signature`, aby wspierać kolejne rozmowy. +- `display: "updates"` to tryb beta Anthropic, który wymaga przekazania `anthropic-beta: thinking-display-updates-2026-08-18`. Oficjalna definicja mówi o ukryciu treści rozumowania i wyświetlaniu krótkich aktualizacji postępu między wywołaniami narzędzi. Platforma przekazuje ten parametr i nagłówek żądania beta w oryginalnej wartości, nie wymusza jego przepisania na `summarized`; rzeczywista zawartość wyjścia zależy od wsparcia wybranego modelu. +- `thinking`, `output_config`, effort, parametry próbkowania oraz nowe rozszerzone pola są przekazywane w oryginalnych wartościach. Platforma nie utrzymuje zakodowanych na stałe według modeli wyliczeń wartości ani ograniczeń kombinacji, ani nie przepisuje automatycznie trybu thinking; o akceptacji tych parametrów decyduje wybrany model, a błędy parametrów zwrócone przez model są przekazywane klientowi. - Domyślną wartością display dla Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 i Opus 4.7 jest `omitted`; Opus 4.6, Sonnet 4.6 oraz wcześniejsze modele obsługujące thinking domyślnie używają `summarized`. - Display wpływa tylko na zwracaną zawartość i opóźnienie strumieniowania, nie wyłącza rozumowania ani nie zmniejsza rozliczania tokenów thinking. -- Domyślne włączenie thinking i domyślna wartość display to dwa niezależne zagadnienia. Opus 5 i Sonnet 5 domyślnie włączają adaptive thinking; dla Opus 5 pominięcie `thinking` jest równoważne adaptive, a pominięcie `output_config.effort` jest równoważne `high`. Opus 4.8, 4.7 i 4.6 wymagają jawnego włączenia. -- Thinking i końcowa treść wspólnie wykorzystują budżet wyjściowy `max_tokens`. Gdy budżet jest zbyt mały, thinking może wykorzystać większość limitu, przez co treść będzie pusta lub obcięta; zwiększ `max_tokens` albo użyj effort `low` / `medium`, aby kontrolować nakład rozumowania. -- W przypadku modeli, które pozwalają wyłączyć thinking, można przekazać `thinking: {"type":"disabled"}`. Nowe tryby, takie jak `between_tools`, oraz kombinacje effort zależą od wybranego modelu; platforma nie odrzuca ich z wyprzedzeniem na podstawie starych reguł modeli. -- Stały budżet rozumowania można przekazać za pomocą `budget_tokens`; nowe modele zazwyczaj używają `thinking.type=adaptive` i `output_config.effort`. To, czy stały budżet lub wyłączenie rozumowania są obsługiwane, zależy od bieżących możliwości wybranego modelu. -- W przypadku rozmów wieloturowych i wywołań narzędzi należy przekazać z powrotem w niezmienionej postaci pełny blok thinking oraz signature zwrócone przez assistant; nie modyfikuj ani nie generuj samodzielnie signature. -- Przekazywanie parametrów nie oznacza, że każdy model obsługuje wszystkie funkcje. Wywołania między protokołami nadal wymagają konwersji, a zakres obsługi i błędy dotyczące treści takich jak `redacted_thinking` zależą od usługi modelu, która faktycznie przetwarza żądanie. +- To, czy thinking jest domyślnie włączone, oraz domyślna wartość display to dwa niezależne zagadnienia. Opus 5 i Sonnet 5 domyślnie włączają adaptive thinking; dla Opus 5 pominięcie `thinking` jest równoważne adaptive, a pominięcie `output_config.effort` jest równoważne `high`. Opus 4.8, 4.7 i 4.6 wymagają jawnego włączenia. +- Thinking i końcowa treść wspólnie wykorzystują budżet wyjściowy `max_tokens`. Gdy budżet jest zbyt mały, thinking może wykorzystać większość limitu, przez co treść może być pusta lub obcięta; zwiększ `max_tokens` albo użyj effort `low` / `medium`, aby kontrolować nakład rozumowania. +- Dla modeli pozwalających wyłączyć thinking można przekazać `thinking: {"type":"disabled"}`. Nowe tryby, takie jak `between_tools`, oraz kombinacje effort zależą od wybranego modelu; platforma nie odrzuca ich z wyprzedzeniem na podstawie starych reguł dotyczących modeli. +- Stały budżet rozumowania można przekazać przez `budget_tokens`; nowe modele zazwyczaj używają `thinking.type=adaptive` i `output_config.effort`. To, czy obsługiwany jest stały budżet lub wyłączenie myślenia, zależy od aktualnych możliwości wybranego modelu. +- W rozmowach wieloturowych i przy wywołaniach narzędzi należy zwracać w niezmienionej postaci pełny blok thinking oraz signature zwrócone przez assistant; nie modyfikuj ani nie generuj samodzielnie signature. +- Przekazywanie parametrów nie oznacza, że każdy model obsługuje wszystkie funkcje. Wywołania między protokołami nadal wymagają konwersji, a zakres wsparcia i błędy dla treści takich jak `redacted_thinking` są określane przez usługę modelu faktycznie przetwarzającą żądanie. -W żądaniach strumieniowych `summarized` generuje `thinking_delta`; `omitted` nie generuje `thinking_delta`, zachowując jedynie cykl życia bloku thinking oraz `signature_delta`. +W żądaniach strumieniowych `summarized` generuje `thinking_delta`; `omitted` nie generuje `thinking_delta`, zachowuje jedynie cykl życia bloku thinking i `signature_delta`. -## Modele wizualne +## Modele wizyjne -Claude obsługuje wejścia multimodalne i może jednocześnie przetwarzać tekst oraz obrazy. W Messages API możliwości wizualne można wykorzystać, ustawiając `content` jako tablicę i przekazując blok zawartości obrazu. +Claude obsługuje wejścia multimodalne i może jednocześnie przetwarzać tekst oraz obrazy. W Messages API możliwości wizyjne można wykorzystać, ustawiając `content` w formacie tablicy i przekazując blok zawartości obrazu. ### Używanie obrazów zakodowanych w Base64 @@ -459,6 +456,7 @@ print(response.json()) ``` ### Przykład cURL + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -492,7 +490,7 @@ Obsługiwane formaty obrazów obejmują: `image/jpeg`, `image/png`, `image/gif`, ## Dokumenty i PDF -PDF używa bloku treści `document`, obsługując dwa stabilne źródła: Base64 i URL. Źródło Base64 musi używać `application/pdf`: +PDF używa bloku zawartości `document`, obsługując dwa stabilne źródła: Base64 i URL. Źródło Base64 musi używać `application/pdf`: ```python import base64 @@ -521,7 +519,7 @@ payload = { } ``` -Źródło URL zapisuje się jako `{"type":"url","url":"https://example.com/report.pdf"}`. `document` obsługuje również `text/plain` oraz źródło `content` składające się z bloków text/image; pola opcjonalne obejmują `title`, `context` i `citations`. Źródło `file_id` z Files API należy do niezależnej funkcji beta i nie jest objęte stabilnym kontraktem tego interfejsu. +Źródło URL zapisuje się jako `{"type":"url","url":"https://example.com/report.pdf"}`. `document` obsługuje również `text/plain` oraz źródło `content` złożone z bloków text/image; opcjonalne pola obejmują `title`, `context` i `citations`. Źródło `file_id` w Files API należy do niezależnej funkcji beta i nie jest objęte stabilnym kontraktem tego interfejsu. ## Buforowanie promptów @@ -536,10 +534,9 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Gdy wymagane jest precyzyjne sterowanie pozycją, można również zapisać tę samą wartość `cache_control` w blokach zawartości text, image, document, tool_use, tool_result lub w definicji narzędzia. `ttl` obsługuje `5m` (domyślnie) i `1h`; proszę użyć `usage.cache_creation_input_tokens` oraz `usage.cache_read_input_tokens`, aby określić zapis do pamięci podręcznej i trafienia w pamięci podręcznej. -Gdy wymagana jest precyzyjna kontrola pozycji, ten sam `cache_control` można również zapisać w blokach treści text, image, document, tool_use, tool_result lub w definicjach narzędzi. `ttl` obsługuje `5m` (domyślnie) i `1h`; należy użyć `usage.cache_creation_input_tokens` oraz `usage.cache_read_input_tokens`, aby określić zapis do pamięci podręcznej i trafienia. - -Gdy odpowiedź udostępnia `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Jeśli `cache_creation` ma wartość `null` lub zostało pominięte, oznacza to, że istnieje tylko łączna wartość zapisu do pamięci podręcznej, bez wiarygodnego podziału TTL; w takim przypadku nie należy traktować żadnego bucketu jako znanego 0, a rozliczenia i sumy nadal opierają się na polu agregującym. +Gdy odpowiedź zawiera `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Jeżeli `cache_creation` ma wartość `null` lub jest pominięte, oznacza to, że istnieje jedynie łączna wartość zapisów do pamięci podręcznej, bez autorytatywnego podziału TTL; w takim przypadku nie należy traktować żadnego bucketu jako znanego 0, a rozliczenia i sumy nadal opierają się na polu zagregowanym. Przykład zwracanego wyniku: @@ -566,9 +563,9 @@ Przykład zwracanego wyniku: ## Wywoływanie narzędzi (Tool Use) -Claude Messages API natywnie obsługuje funkcję wywoływania narzędzi, umożliwiając modelowi wywoływanie w razie potrzeby zdefiniowanych przez Ciebie narzędzi/funkcji. +Claude Messages API natywnie obsługuje funkcję wywoływania narzędzi, umożliwiając modelowi wywoływanie zdefiniowanych przez Państwa narzędzi/funkcji, gdy jest to potrzebne. -### Przykład w Pythonie +### Przykład Python ```python import requests @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Gdy model zdecyduje się wywołać narzędzie, `content` w zwracanym wyniku będzie zawierać blok treści typu `tool_use`: +Gdy model zdecyduje się wywołać narzędzie, `content` w zwracanym wyniku będzie zawierać blok zawartości typu `tool_use`: ```json { @@ -640,7 +637,7 @@ Gdy model zdecyduje się wywołać narzędzie, `content` w zwracanym wyniku będ } ``` -Zauważ, że `stop_reason` ma wartość `tool_use`, co oznacza, że model musi wywołać narzędzie. Po otrzymaniu tego wyniku należy wykonać funkcję narzędzia i przekazać wynik z powrotem do modelu w formie `tool_result`: +Należy zwrócić uwagę, że `stop_reason` ma wartość `tool_use`, co oznacza, że model musi wywołać narzędzie. Po otrzymaniu tego wyniku należy wykonać funkcję narzędzia i przekazać wynik z powrotem do modelu w formie `tool_result`: ```python payload = { @@ -692,32 +689,33 @@ Model wygeneruje końcową odpowiedź w języku naturalnym na podstawie wyniku z ## Różnice względem Chat Completion API -Ace Data Cloud oferuje jednocześnie dwa formaty Claude API, a ich główne różnice są następujące: +Ace Data Cloud udostępnia jednocześnie dwa formaty Claude API, a ich główne różnice są następujące: -`usage.input_tokens` w Messages API oznacza wyłącznie niebuforowane dane wejściowe, a `cache_read_input_tokens` i `cache_creation_input_tokens` są niezależnymi bucketami rozliczeniowymi; wszystkie trzy są obliczane oddzielnie według odpowiednich cen. -| Cecha | API Messages (`/v1/messages`) | API Chat Completion (`/v1/chat/completions`) | +`usage.input_tokens` w Messages API oznacza wyłącznie dane wejściowe niepochodzące z pamięci podręcznej, a `cache_read_input_tokens` i `cache_creation_input_tokens` są niezależnymi bucketami rozliczeniowymi; wszystkie trzy są obliczane osobno według odpowiadających im cen. + +| Funkcja | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| Format | Natywny format Anthropic | Format kompatybilny z OpenAI | -| Prompt systemowy | Niezależne pole `system` | Przekazywany przez `role: "system"` w `messages` | -| Struktura odpowiedzi | Tablica `content` (obsługuje wiele typów) | Tablica `choices` (zawierająca `message`) | -| Format strumieniowy | Zdarzenia SSE (wiele typów zdarzeń) | Linie SSE `data` | -| Głębokie myślenie | Natywne `thinking` oraz `output_config.effort` | Domyślna strategia modelu i parametry kompatybilności | -| Wywołania narzędzi | Natywny format `tools` + `input_schema` | Format `tools` kompatybilny z OpenAI | +| Format | Natywny format Anthropic | Format zgodny z OpenAI | +| Komunikat systemowy | Niezależne pole `system` | Przekazywany przez `role: "system"` w `messages` | +| Struktura odpowiedzi | Tablica `content` (obsługuje wiele typów) | Tablica `choices` (zawiera `message`) | +| Format strumieniowy | Zdarzenia SSE (wiele typów zdarzeń) | Wiersze SSE `data` | +| Głębokie rozumowanie | Natywne `thinking` i `output_config.effort` | Domyślna strategia modelu i parametry zgodności | +| Wywoływanie narzędzi | Natywne `tools` + `input_schema` | Format `tools` zgodny z OpenAI | | Statystyki tokenów | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Jeśli Państwa system jest już zintegrowany z API w formacie OpenAI, można użyć Chat Completion API w celu płynnego przełączenia. Jeśli potrzebują Państwo korzystać ze wszystkich natywnych możliwości Claude, zalecane jest użycie Messages API. +Jeśli Państwa system jest już zintegrowany z API w formacie OpenAI, można użyć Chat Completion API, aby bezproblemowo się przełączyć. Jeśli potrzebują Państwo wszystkich natywnych możliwości Claude, zaleca się użycie Messages API. ## Obsługa błędów -Odpowiedzi błędów publicznego interfejsu używają envelope platformy Ace Data Cloud: `error.code` jest stabilnym kodem błędu, `error.message` zawiera opis, a `trace_id` służy do analizy żądań. Typowe statusy HTTP obejmują: +Odpowiedzi błędów publicznego interfejsu używają envelope platformy Ace Data Cloud: `error.code` jest stabilnym kodem błędu, `error.message` jest opisem, a `trace_id` służy do diagnozowania żądań. Typowe statusy HTTP obejmują: -- `400`：Nieprawidłowe parametry żądania lub nieprawidłowa zawartość protokołu. -- `401`：Nieprawidłowy, brakujący lub wygasły token autoryzacji. -- `403`：Dostęp zabroniony, niewystarczające saldo lub ograniczony limit. -- `404`：API lub model nie istnieje. -- `413`：Treść żądania jest zbyt duża. -- `429`：Zbyt wiele żądań. -- `500` / `503` / `504`：Błąd usługi, tymczasowa niedostępność lub przekroczenie czasu przetwarzania. +- `400`: Parametry żądania lub zawartość protokołu są nieprawidłowe. +- `401`: Token autoryzacyjny jest nieprawidłowy, nieobecny lub wygasł. +- `403`: Dostęp zabroniony, niewystarczające saldo lub ograniczony limit. +- `404`: API lub model nie istnieje. +- `413`: Treść żądania jest zbyt duża. +- `429`: Zbyt wiele żądań. +- `500` / `503` / `504`: Błąd usługi, tymczasowa niedostępność lub przekroczenie limitu czasu przetwarzania. ### Przykład odpowiedzi błędu @@ -731,8 +729,7 @@ Odpowiedzi błędów publicznego interfejsu używają envelope platformy Ace Dat } ``` -Ta struktura błędu jest kontraktem środowiska uruchomieniowego Ace Data Cloud i nie jest równoważna z oficjalnym envelope błędów Anthropic; należy obsługiwać ją zgodnie ze statusem HTTP oraz `error.code`. - -## Podsumowanie +Ta struktura błędu jest kontraktem wykonawczym Ace Data Cloud i nie jest równoważna oficjalnemu envelope błędu Anthropic; należy obsługiwać ją zgodnie ze statusem HTTP i `error.code`. -Dzięki temu dokumentowi poznali Państwo sposób korzystania z Claude Messages API w celu wywoływania funkcji konwersacyjnych Claude w natywnym formacie Anthropic. Messages API obsługuje podstawowe rozmowy, prompty systemowe, odpowiedzi strumieniowe, rozmowy wieloetapowe, głębokie myślenie, rozumienie wizualne, pliki PDF, buforowanie promptów oraz wywołania narzędzi i inne bogate funkcje. W przypadku jakichkolwiek pytań prosimy o kontakt z zespołem wsparcia technicznego. +## Wnioski +Dzięki temu dokumentowi wiesz już, jak używać Claude Messages API do wywoływania funkcji konwersacyjnych Claude w natywnym formacie Anthropic. Messages API obsługuje bogate funkcje, takie jak podstawowe rozmowy, prompty systemowe, odpowiedzi strumieniowe, rozmowy wieloturowe, głębokie myślenie, rozumienie obrazu, PDF-y, buforowanie promptów i wywoływanie narzędzi. Jeśli masz jakiekolwiek pytania, skontaktuj się z naszym zespołem wsparcia technicznego w dowolnym momencie. diff --git a/pt/guides/claude/claude_messages.mdx b/pt/guides/claude/claude_messages.mdx index ac55a516..cea7c376 100644 --- a/pt/guides/claude/claude_messages.mdx +++ b/pt/guides/claude/claude_messages.mdx @@ -3,19 +3,19 @@ title: "Solicitação e uso da API Claude Messages" description: "Claude AI API guide - Ace Data Cloud" --- -O Anthropic Claude é um sistema de conversação de IA muito poderoso que, basta inserir um prompt, pode gerar respostas fluentes e naturais em poucos segundos. A API Claude Messages é o formato de API nativo oficial da Anthropic. Diferente do formato compatível com OpenAI (Chat Completion), ela adota a própria estrutura de solicitação e resposta da Anthropic, permitindo aproveitar melhor as capacidades exclusivas do Claude, como entrada de conteúdo multimodal, chamada de ferramentas, pensamento profundo (Extended Thinking) e outros recursos avançados. +O Anthropic Claude é um sistema de diálogo de IA muito poderoso que, basta inserir um prompt, pode gerar respostas fluentes e naturais em poucos segundos. A API Claude Messages é o formato de API nativo oficial da Anthropic. Diferente do formato compatível com OpenAI (Chat Completion), ela adota a própria estrutura de solicitação e resposta da Anthropic, permitindo utilizar melhor as capacidades exclusivas do Claude, como entrada de conteúdo multimodal, chamada de ferramentas, pensamento profundo (Extended Thinking) e outros recursos avançados. -Este documento apresenta principalmente o processo de uso das operações da API Claude Messages. Com ela, podemos usar uma interface nativa consistente com a oficial da Anthropic para chamar os recursos de conversação do Claude. +Este documento apresenta principalmente o processo de uso das operações da API Claude Messages. Com ela, podemos usar uma interface nativa consistente com a oficial da Anthropic para chamar os recursos de diálogo do Claude. ## Processo de solicitação -Para usar a API Claude Messages, primeiro acesse o [Console Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu API Token e guarde-o para uso posterior. +Para usar a API Claude Messages, primeiro acesse o [Console do Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu API Token e guarde-o para uso posterior. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Se você ainda não tiver feito login ou se registrado, será automaticamente redirecionado para a página de login para se registrar e fazer login, retornando automaticamente à página atual após a conclusão. +Se você ainda não tiver feito login ou se registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e fazer login. Após concluir, retornará automaticamente para a página atual. -**Um único API Token pode chamar todos os serviços da plataforma, sem a necessidade de solicitar separadamente para cada serviço.** A primeira solicitação concede créditos gratuitos, permitindo uma experiência gratuita; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin). +**Um único API Token permite chamar todos os serviços da plataforma, sem a necessidade de solicitar um separadamente para cada serviço.** A primeira solicitação oferece créditos gratuitos para experimentar sem custo; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin). > 📘 Documentação completa: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) @@ -23,22 +23,21 @@ Se você ainda não tiver feito login ou se registrado, será automaticamente re O caminho de solicitação da API Claude Messages é `/v1/messages`, mantendo-se consistente com a API oficial da Anthropic. Precisamos fornecer pelo menos três parâmetros obrigatórios: -- `model`: Seleciona o modelo Claude a ser usado. `claude-opus-5-5` é fornecido apenas pela API Messages, suporta contexto de 1 milhão de Tokens, saída máxima de 128K Tokens e sempre ativa o pensamento adaptativo. O mais recente modelo principal é `claude-fable-5-1` (contexto de 1 milhão de Tokens, saída máxima de 128K Tokens); o antigo `claude-fable-5` permanece compatível. `claude-sonnet-5-5` foi adicionado à série de interfaces nativas Messages, suporta entrada de imagens e pensamento adaptativo; seus preços de referência oficiais para entrada, saída e leitura de cache são, respectivamente, 2, 10 e 0,20 dólares por milhão de Tokens. -- `messages`: Array de mensagens de entrada, em que cada mensagem contém `role` (função) e `content` (conteúdo), e `role` suporta `user` e `assistant`. -- `max_tokens`: Número máximo de tokens de saída, usado para limitar o comprimento de uma única resposta. +- `model`: escolha o modelo Claude a ser usado. `claude-opus-5-5` é fornecido apenas pela API Messages, suporta contexto de 1 milhão de Tokens, saída máxima de 128K Tokens e sempre ativa o pensamento adaptativo. O mais recente modelo principal é o `claude-fable-5-1` (contexto de 1 milhão de Tokens, saída máxima de 128K Tokens); o antigo `claude-fable-5` permanece mantido por compatibilidade. O `claude-sonnet-5-5` foi adicionado à série de interfaces nativas Messages, suportando entrada de imagens e pensamento adaptativo; seus preços de referência oficiais para entrada, saída e leitura de cache são, respectivamente, 2, 10 e 0,20 dólares por milhão de Tokens. +- `messages`: array de mensagens de entrada, em que cada mensagem contém `role` (função) e `content` (conteúdo), sendo que `role` suporta `user` e `assistant`. +- `max_tokens`: número máximo de tokens de saída, usado para limitar o comprimento de uma única resposta. Parâmetros opcionais comuns: -- `system`: Prompt de sistema, usado para definir o comportamento e a função do modelo. -- `temperature`: Aleatoriedade de geração, entre 0 e 1; quanto maior o valor, mais divergente será a resposta. -- `stream`: Define se deve usar resposta em streaming; configurá-lo como `true` permite um efeito de retorno palavra por palavra. -- `stop_sequences`: Sequências de parada personalizadas; o modelo interromperá a geração ao encontrar esses textos. -- `top_p`: Parâmetro de amostragem de núcleo, usado em conjunto com temperature para controlar a aleatoriedade da geração. -- `top_k`: Amostra apenas entre as K opções com maior probabilidade. -- `tools`: Definições de ferramentas, usadas para permitir que o modelo chame funções externas. -- `tool_choice`: Controla como o modelo usa as ferramentas fornecidas. -- `cache_control`: Cria automaticamente um ponto de interrupção de cache no último bloco de conteúdo armazenável em cache da solicitação; também pode ser escrito em blocos de conteúdo específicos. -- `metadata`: Objeto opcional de metadados da solicitação. `metadata.user_id` é uma string e pode transmitir o identificador de usuário personalizado do chamador, por exemplo, `{"user_id":"example-user-001"}`; recomenda-se usar um identificador estável que não contenha informações pessoais. Ele não substitui a autenticação `Authorization`, nem precisa ser incluído no conteúdo da conversa em `messages`. +- `system`: prompt de sistema, usado para definir o comportamento e a função do modelo. +- `temperature`: aleatoriedade da geração, entre 0 e 1; quanto maior o valor, mais divergente será a resposta. +- `stream`: se usa resposta em streaming; definido como `true`, permite o efeito de retorno palavra por palavra. +- `stop_sequences`: sequências de parada personalizadas; o modelo interromperá a geração ao encontrar esses textos. +- `top_p`: parâmetro de amostragem de núcleo, que controla a aleatoriedade da geração junto com temperature. +- `top_k`: amostra somente entre as K opções com maior probabilidade. +- `tools`: definição de ferramentas, usada para permitir que o modelo chame funções externas. +- `tool_choice`: controla como o modelo usa as ferramentas fornecidas. +- `cache_control`: cria automaticamente um ponto de interrupção de cache no último bloco de conteúdo armazenável em cache da solicitação; também pode ser escrito em um bloco de conteúdo específico. ### Exemplo cURL @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -110,24 +107,24 @@ Após a chamada, o resultado retornado é o seguinte: ``` Descrição dos campos do resultado retornado: -- `id`：o identificador único desta mensagem. -- `type`：sempre `message`. -- `role`：sempre `assistant`. -- `content`：a matriz de conteúdo da resposta, cada elemento contém `type` (como `text`) e o conteúdo correspondente. -- `model`：o nome do modelo que processa a solicitação. -- `stop_reason`：o motivo da interrupção. Os valores estáveis incluem `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (pode devolver o conteúdo atual do assistant sem alterações para continuar), `refusal` e `model_context_window_exceeded`. -- `stop_sequence`：se a interrupção ocorrer devido a uma sequência de parada personalizada, exibe o texto da sequência de parada correspondente. -- `stop_details`：quando `stop_reason` for `refusal`, pode conter a categoria e a descrição da recusa. -- `usage`：estatísticas de uso de tokens. `input_tokens` é a entrada não armazenada em cache; `cache_creation_input_tokens` e `cache_read_input_tokens` são, respectivamente, a gravação e a leitura do cache; `output_tokens` é o número total de tokens de saída. Se `output_tokens_details.thinking_tokens` for retornado, esse valor será um subconjunto de `output_tokens`; não o some novamente ao calcular o total ou o custo. Esse detalhamento pode ser `null` ou ser omitido quando não houver uma contagem autoritativa. -- `usage.cache_creation`：detalhes opcionais do TTL de gravação do cache, contendo `ephemeral_5m_input_tokens` e `ephemeral_1h_input_tokens`. Quando o objeto existir, a soma dos dois será igual a `cache_creation_input_tokens`; um campo `null` ou omitido indica que a resposta atual não possui uma divisão de TTL disponível e não deve ser interpretado como `0`. -- `usage.cost`：respostas não transmitidas por streaming podem conter o objeto de consumo de créditos registrado pela Ace Data Cloud, no qual `amount` é o consumo real desta vez, `currency` é a unidade de medição e `list_amount` é o valor antes do desconto (se houver). O preço-base oficial de leitura de cache do Fable 5.1 é de US$ 0,25/milhão de Tokens, e os preços-base de gravação de cache de 5 minutos e 1 hora são de US$ 12,50 e US$ 20/milhão de Tokens, respectivamente; os preços reais da plataforma são convertidos de acordo com o desconto do plano. -## Prompt de sistema +- `id`: identificador exclusivo desta mensagem. +- `type`: sempre é `message`. +- `role`: sempre é `assistant`. +- `content`: array de conteúdo da resposta; cada elemento contém `type` (como `text`) e o conteúdo correspondente. +- `model`: nome do modelo que processou a solicitação. +- `stop_reason`: motivo da interrupção. Os valores estáveis incluem `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (você pode reenviar o conteúdo atual do assistant sem alterações para continuar), `refusal` e `model_context_window_exceeded`. +- `stop_sequence`: se a interrupção ocorreu devido a uma sequência de parada personalizada, exibe o texto da sequência de parada correspondente. +- `stop_details`: quando `stop_reason` for `refusal`, pode incluir a categoria e a descrição da recusa. +- `usage`: estatísticas de uso de tokens. `input_tokens` é a entrada não armazenada em cache; `cache_creation_input_tokens` e `cache_read_input_tokens` são, respectivamente, gravação e leitura de cache; `output_tokens` é o número total de tokens de saída. Se `output_tokens_details.thinking_tokens` for retornado, esse valor será um subconjunto de `output_tokens`; não o some novamente ao calcular o total ou o custo. Esse detalhamento poderá ser `null` ou ser omitido quando não houver uma contagem confiável. +- `usage.cache_creation`: detalhamento opcional do TTL de gravação de cache, incluindo `ephemeral_5m_input_tokens` e `ephemeral_1h_input_tokens`. Quando o objeto existir, a soma dos dois será igual a `cache_creation_input_tokens`; se o campo for `null` ou omitido, isso indica que a resposta atual não possui uma divisão de TTL disponível e não deve ser interpretado como `0`. +- `usage.cost`: respostas não em streaming podem incluir o objeto de consumo de créditos registrado pelo Ace Data Cloud, em que `amount` é o consumo real desta vez, `currency` é a unidade de medição, e `list_amount` é o valor antes do desconto (se houver). O preço base oficial de leitura de cache do Fable 5.1 é de US$ 0,25/milhão de Tokens, e os preços base de gravação de cache de 5 minutos e 1 hora são, respectivamente, US$ 12,50 e US$ 20/milhão de Tokens; os preços reais da plataforma são convertidos conforme os descontos do plano. -A Claude Messages API oferece suporte à definição de prompts de sistema por meio do campo `system`, usados para definir o comportamento, o papel e o contexto do modelo. +## Prompt de sistema -### Exemplo em Python +A API Claude Messages permite definir o prompt de sistema por meio do campo `system`, usado para definir o comportamento, a função e o contexto do modelo. +### Exemplo Python ```python import requests @@ -142,7 +139,7 @@ headers = { payload = { "model": "claude-sonnet-4-20250514", "max_tokens": 1024, - "system": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。", + "system": "Você é um assistente profissional de tradução para chinês. Por favor, traduza o inglês inserido pelo usuário para chinês.", "messages": [ {"role": "user", "content": "The quick brown fox jumps over the lazy dog."} ] @@ -152,11 +149,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Ao configurar o prompt `system`, é possível controlar precisamente o papel e o comportamento do Claude. +Ao definir o prompt `system`, é possível controlar com precisão o papel e o comportamento do Claude. ## Resposta em streaming -Esta interface também oferece suporte a respostas em streaming; basta definir o parâmetro `stream` como `true` para obter um efeito de retorno gradual, sendo muito adequada para implementar a exibição de texto caractere por caractere em páginas da web. +Esta interface também oferece suporte a respostas em streaming; basta definir o parâmetro `stream` como `true` para obter um efeito de retorno gradual, sendo muito adequado para implementar a exibição palavra por palavra em páginas da web. ### Exemplo em Python @@ -186,14 +183,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -As respostas em streaming são retornadas no formato Server-Sent Events (SSE), e cada linha é prefixada por `event:` e `data:`. Os tipos de eventos de streaming incluem: +A resposta em streaming é retornada no formato Server-Sent Events (SSE), com cada linha prefixada por `event:` e `data:`. Os tipos de eventos em streaming incluem: -- `message_start`：início da mensagem, contendo as informações básicas da mensagem e o nome do modelo. -- `content_block_start`：início do bloco de conteúdo. -- `content_block_delta`：atualização incremental do bloco de conteúdo, contendo o fragmento de texto recém-gerado. -- `content_block_stop`：fim do bloco de conteúdo. -- `message_delta`：atualização incremental no nível da mensagem, contendo `stop_reason` e as informações finais de `usage`. O valor autoritativo de `output_tokens_details.thinking_tokens` deve ser lido somente do último `message_delta.usage`; não o acumule entre eventos. -- `message_stop`：fim da mensagem. +- `message_start`: início da mensagem, contendo as informações básicas da mensagem e o nome do modelo. +- `content_block_start`: início do bloco de conteúdo. +- `content_block_delta`: atualização incremental do bloco de conteúdo, contendo o fragmento de texto recém-gerado. +- `content_block_stop`: fim do bloco de conteúdo. +- `message_delta`: atualização incremental no nível da mensagem, contendo `stop_reason` e as informações finais de `usage`. O valor autoritativo de `output_tokens_details.thinking_tokens` deve ser lido somente do último `message_delta.usage`; não o acumule entre eventos. +- `message_stop`: fim da mensagem. O efeito de saída é o seguinte: @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Pode-se observar que, na resposta em streaming, o evento `content_block_delta` contém o conteúdo de texto gerado gradualmente; ao concatenar todos os `text_delta`, é possível obter a resposta completa. +Pode-se ver que, na resposta em streaming, o evento `content_block_delta` contém o conteúdo de texto gerado gradualmente; ao concatenar todos os `text_delta`, é possível obter a resposta completa. ### Exemplo em JavaScript @@ -254,9 +251,9 @@ while (true) { } ``` -## Conversas de múltiplos turnos +## Conversas com múltiplas rodadas -Se você quiser integrar a funcionalidade de conversas de múltiplos turnos, será necessário alternar as mensagens com os papéis `user` e `assistant` na matriz `messages` e enviar junto o histórico anterior da conversa. +Se você quiser integrar a funcionalidade de conversas com múltiplas rodadas, deverá alternar as mensagens dos papéis `user` e `assistant` no array `messages` e enviar junto todo o histórico anterior da conversa. ### Exemplo em Python @@ -286,6 +283,7 @@ print(response.json()) ``` O resultado retornado é o seguinte: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -309,11 +307,11 @@ O resultado retornado é o seguinte: Ao transmitir o histórico completo da conversa em `messages`, o Claude pode fornecer respostas precisas com base no contexto. -## Modelos de raciocínio profundo +## Modelo de raciocínio profundo -O thinking e o thinking summary do Claude são dois conceitos diferentes: o modelo pode realizar raciocínio interno, mas a API não retorna a cadeia de pensamento original. Quando é necessário exibir o processo de raciocínio, a API retorna um resumo processado. +O thinking e o thinking summary do Claude são dois conceitos diferentes: o modelo pode realizar raciocínio interno, mas a API não retorna a cadeia de pensamento original. Quando é necessário exibir o processo de raciocínio, o que a API retorna é um resumo processado. -Atualmente, recomenda-se que os modelos usem adaptive thinking e controlem o investimento geral de raciocínio por meio de `output_config.effort`: +Atualmente, recomenda-se que o modelo use adaptive thinking e controle o investimento geral de raciocínio por meio de `output_config.effort`: ```python import requests @@ -352,25 +350,24 @@ O bloco thinking na resposta tem a seguinte forma: "signature": "opaque-signature" } ``` - -- `display: "summarized"` retorna um resumo de pensamento legível; ele não é a cadeia de pensamento original. -- `display: "omitted"` retorna `thinking: ""`, mas ainda mantém a `signature` opaque para dar suporte a conversas subsequentes. -- `display: "updates"` é o modo beta da Anthropic, que requer `anthropic-beta: thinking-display-updates-2026-08-18`. A definição oficial é ocultar o texto do raciocínio e exibir breves atualizações de progresso entre chamadas de ferramentas. A plataforma transmite esse parâmetro e o cabeçalho de solicitação beta conforme os valores originais, sem forçar a reescrita para `summarized`; o conteúdo real da saída depende do suporte do modelo selecionado. -- `thinking`, `output_config`, effort, parâmetros de amostragem e novos campos de extensão são transmitidos conforme os valores originais. A plataforma não mantém enumerações de valores ou restrições de combinação codificadas por modelo, nem reescreve automaticamente o modo thinking; cabe ao modelo selecionado decidir se aceita esses parâmetros, e os erros de parâmetros retornados pelo modelo são repassados ao cliente. -- O valor padrão de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 é `omitted`; Opus 4.6, Sonnet 4.6 e modelos anteriores com suporte a thinking usam `summarized` por padrão. +- `display: "summarized"` retorna um resumo legível do raciocínio; não é a cadeia de pensamento original. +- `display: "omitted"` retorna `thinking: ""`, mas ainda preserva a `signature` opaca para oferecer suporte a conversas subsequentes. +- `display: "updates"` é o modo beta da Anthropic, e requer `anthropic-beta: thinking-display-updates-2026-08-18`. A definição oficial é ocultar o corpo do raciocínio e exibir breves atualizações de progresso entre chamadas de ferramentas. A plataforma transmite esse parâmetro e o cabeçalho beta conforme os valores originais, e não os reescreve forçadamente como `summarized`; o conteúdo real da saída depende do suporte do modelo selecionado. +- `thinking`, `output_config`, effort, parâmetros de amostragem e campos de extensão recém-adicionados são transmitidos conforme os valores originais. A plataforma não mantém enumerações de valores codificadas por modelo, restrições de combinação, nem reescreve automaticamente o modo thinking; cabe ao modelo selecionado determinar se aceita esses parâmetros, e os erros de parâmetros retornados pelo modelo serão repassados ao cliente. +- Os valores padrão de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 são `omitted`; Opus 4.6, Sonnet 4.6 e modelos anteriores que suportam thinking usam `summarized` por padrão. - Display afeta apenas o conteúdo retornado e a latência de streaming, não desativa o raciocínio nem reduz a cobrança de tokens de thinking. -- A ativação padrão de thinking e o valor padrão de display são duas questões independentes. Opus 5 e Sonnet 5 ativam adaptive thinking por padrão; para o Opus 5, omitir `thinking` equivale a adaptive, e omitir `output_config.effort` equivale a `high`. Opus 4.8, 4.7 e 4.6 exigem ativação explícita. -- Thinking e o texto final compartilham o orçamento de saída de `max_tokens`. Quando o orçamento é muito pequeno, thinking pode consumir grande parte da cota, deixando o texto vazio ou truncado; aumente `max_tokens` ou use effort `low` / `medium` para controlar o investimento de raciocínio. -- Para modelos que permitem desativar thinking, pode-se transmitir `thinking: {"type":"disabled"}`. Novos modos como `between_tools` e combinações de effort dependem do modelo selecionado; a plataforma não os rejeita antecipadamente com base em regras antigas de modelos. -- Um orçamento fixo de pensamento pode ser transmitido por meio de `budget_tokens`; os novos modelos normalmente usam `thinking.type=adaptive` e `output_config.effort`. O suporte a orçamento fixo ou à desativação do pensamento depende dos recursos atuais do modelo selecionado. -- Em conversas de múltiplos turnos e chamadas de ferramentas, o bloco thinking completo e a signature retornados pelo assistant devem ser retransmitidos sem alterações; não modifique nem gere a signature por conta própria. +- A ativação padrão de thinking e o valor padrão de display são duas questões independentes. Opus 5 e Sonnet 5 ativam adaptive thinking por padrão; para Opus 5, omitir `thinking` equivale a adaptive, e omitir `output_config.effort` equivale a `high`. Opus 4.8, 4.7 e 4.6 exigem ativação explícita. +- Thinking e o corpo final compartilham o orçamento de saída de `max_tokens`. Quando o orçamento é muito pequeno, thinking pode consumir a maior parte do limite, deixando o corpo vazio ou truncado; aumente `max_tokens` ou use effort `low` / `medium` para controlar o investimento de raciocínio. +- Para modelos que permitem desativar thinking, é possível passar `thinking: {"type":"disabled"}`. Novos modos como `between_tools` e combinações de effort dependem do modelo selecionado; a plataforma não rejeita antecipadamente com base em regras de modelos antigos. +- Orçamentos fixos de raciocínio podem ser transmitidos por meio de `budget_tokens`; novos modelos normalmente usam `thinking.type=adaptive` e `output_config.effort`. O suporte a orçamentos fixos ou à desativação de raciocínio depende das capacidades atuais do modelo selecionado. +- Em conversas de múltiplos turnos e chamadas de ferramentas, o bloco thinking completo e a signature retornados pelo assistant devem ser enviados de volta sem alterações; não modifique nem gere signatures por conta própria. - A transmissão de parâmetros não significa que todos os modelos suportam todos os recursos. Chamadas entre protocolos ainda exigem conversão, e o escopo de suporte e os erros para conteúdos como `redacted_thinking` são determinados pelo serviço do modelo que realmente processa a solicitação. -Em solicitações de streaming, `summarized` produz `thinking_delta`; `omitted` não produz `thinking_delta`, mantendo apenas o ciclo de vida do bloco thinking e `signature_delta`. +Em solicitações de streaming, `summarized` produz `thinking_delta`; `omitted` não produz `thinking_delta`, preservando apenas o ciclo de vida do bloco thinking e `signature_delta`. ## Modelos visuais -O Claude oferece suporte a entradas multimodais e pode processar texto e imagens simultaneamente. Na Messages API, os recursos visuais podem ser usados definindo `content` no formato de array e transmitindo blocos de conteúdo de imagem. +Claude oferece suporte a entradas multimodais e pode processar texto e imagens simultaneamente. Na Messages API, os recursos visuais podem ser usados definindo `content` como um formato de array e passando blocos de conteúdo de imagem. ### Usando imagens codificadas em Base64 @@ -459,6 +456,7 @@ print(response.json()) ``` ### Exemplo de cURL + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -488,11 +486,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Os formatos de imagem compatíveis incluem: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Os formatos de imagem suportados incluem: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Documentos e PDF -PDF usa o bloco de conteúdo `document`, oferecendo suporte a duas fontes estáveis: Base64 e URL. A fonte Base64 deve usar `application/pdf`: +PDF usa o bloco de conteúdo `document`, oferecendo suporte a duas fontes estáveis: Base64 e URL. Fontes Base64 devem usar `application/pdf`: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -A fonte URL é escrita como `{"type":"url","url":"https://example.com/report.pdf"}`. `document` também oferece suporte a `text/plain` e à fonte `content` composta por blocos text/image; os campos opcionais incluem `title`, `context` e `citations`. A fonte `file_id` da Files API pertence a uma funcionalidade beta independente e não faz parte do contrato estável desta interface. +Fontes URL são escritas como `{"type":"url","url":"https://example.com/report.pdf"}`. `document` também oferece suporte a `text/plain` e a fontes `content` compostas por blocos text/image; os campos opcionais incluem `title`, `context` e `citations`. A fonte `file_id` da Files API pertence a uma funcionalidade beta independente e não faz parte do contrato estável desta interface. -## Cache de prompt +## Cache de prompts -O `cache_control` de nível superior coloca automaticamente o ponto de interrupção do cache no último bloco armazenável em cache: +O `cache_control` de nível superior coloca automaticamente o ponto de interrupção de cache no último bloco armazenável em cache: ```python payload = { @@ -536,10 +534,9 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Quando for necessário controlar a posição com precisão, você também pode escrever o mesmo `cache_control` nos blocos de conteúdo text, image, document, tool_use, tool_result ou nas definições de ferramentas. `ttl` oferece suporte a `5m` (padrão) e `1h`; determine a gravação e os acertos do cache por meio de `usage.cache_creation_input_tokens` e `usage.cache_read_input_tokens`. -Quando for necessário controlar precisamente a posição, também é possível escrever o mesmo `cache_control` nos blocos de conteúdo text, image, document, tool_use, tool_result ou na definição da ferramenta. `ttl` oferece suporte a `5m` (padrão) e `1h`; use `usage.cache_creation_input_tokens` e `usage.cache_read_input_tokens` para determinar a gravação e o acerto do cache. - -Quando a resposta fornece `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Se `cache_creation` for `null` ou for omitido, isso indica que há apenas o total de gravações em cache, sem uma divisão de TTL autoritativa; nesse caso, não trate nenhum bucket como um 0 conhecido, e a cobrança e o total ainda devem se basear no campo agregado. +Quando a resposta fornecer `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Se `cache_creation` for `null` ou estiver omitido, isso indica que há apenas o total de gravações em cache, sem uma divisão autoritativa de TTL; nesse caso, não trate nenhum bucket como um 0 conhecido, e a cobrança e o total ainda devem se basear no campo agregado. Exemplo de resultado retornado: @@ -566,7 +563,7 @@ Exemplo de resultado retornado: ## Chamada de ferramentas (Tool Use) -A Claude Messages API oferece suporte nativo à funcionalidade de chamada de ferramentas, permitindo que o modelo chame suas ferramentas/funções predefinidas quando necessário. +A Claude Messages API oferece suporte nativo ao recurso de chamada de ferramentas, permitindo que o modelo chame suas ferramentas/funções predefinidas quando necessário. ### Exemplo em Python @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Quando o modelo decide chamar uma ferramenta, o resultado retornado conterá um bloco de conteúdo do tipo `tool_use` em `content`: +Quando o modelo decide chamar uma ferramenta, o `content` no resultado retornado incluirá um bloco de conteúdo do tipo `tool_use`: ```json { @@ -688,36 +685,37 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -O modelo gerará uma resposta final em linguagem natural com base no resultado retornado pela ferramenta. +O modelo gerará a resposta final em linguagem natural com base no resultado retornado pela ferramenta. ## Diferenças em relação à Chat Completion API -A Ace Data Cloud fornece simultaneamente dois formatos de Claude API, e as principais diferenças entre eles são as seguintes: +A Ace Data Cloud fornece simultaneamente dois formatos de Claude API, cujas principais diferenças são as seguintes: + +O `usage.input_tokens` da Messages API representa apenas a entrada não armazenada em cache, enquanto `cache_read_input_tokens` e `cache_creation_input_tokens` são buckets de cobrança independentes; os três serão calculados separadamente de acordo com os preços correspondentes. -O `usage.input_tokens` da Messages API representa apenas entradas não armazenadas em cache; `cache_read_input_tokens` e `cache_creation_input_tokens` são buckets de cobrança independentes; os três serão calculados separadamente de acordo com os preços correspondentes. | Recurso | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Formato | Formato nativo da Anthropic | Formato compatível com OpenAI | | Prompt do sistema | Campo `system` independente | Transmitido por meio de `role: "system"` em `messages` | -| Estrutura da resposta | Array `content` (suporta vários tipos) | Array `choices` (contém `message`) | -| Formato de streaming | Eventos SSE (vários tipos de eventos) | Linhas SSE `data` | -| Pensamento profundo | `thinking` nativo e `output_config.effort` | Estratégia padrão do modelo e parâmetros compatíveis | -| Chamada de ferramentas | `tools` nativo + `input_schema` | Formato `tools` compatível com OpenAI | +| Estrutura de resposta | Array `content` (oferece suporte a vários tipos) | Array `choices` (inclui `message`) | +| Formato de streaming | Eventos SSE (vários tipos de evento) | Linhas SSE `data` | +| Raciocínio profundo | `thinking` nativo e `output_config.effort` | Estratégia padrão do modelo e parâmetros de compatibilidade | +| Chamada de ferramentas | `tools` + `input_schema` nativos | Formato `tools` compatível com OpenAI | | Estatísticas de Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Se o seu sistema já está integrado à API no formato OpenAI, você pode usar a Chat Completion API para alternar perfeitamente. Se você precisar usar todos os recursos nativos do Claude, recomenda-se usar a Messages API. +Se o seu sistema já estiver integrado com a API no formato OpenAI, você pode usar a Chat Completion API para alternar perfeitamente. Se precisar usar todos os recursos nativos do Claude, é recomendável usar a Messages API. ## Tratamento de erros -As respostas de erro da interface pública usam o envelope da plataforma Ace Data Cloud: `error.code` é um código de erro estável, `error.message` é a descrição, e `trace_id` é usado para rastrear solicitações. Os status HTTP comuns incluem: +As respostas de erro da interface pública usam o envelope da plataforma Ace Data Cloud: `error.code` é um código de erro estável, `error.message` é uma descrição, e `trace_id` é usado para investigar a solicitação. Os status HTTP comuns incluem: -- `400`: Os parâmetros da solicitação ou o conteúdo do protocolo são inválidos. -- `401`: O token de autorização é inválido, está ausente ou expirou. -- `403`: Acesso proibido, saldo insuficiente ou cota limitada. -- `404`: A API ou o modelo não existe. -- `413`: O corpo da solicitação é muito grande. -- `429`: Solicitações em excesso. -- `500` / `503` / `504`: Erro de serviço, temporariamente indisponível ou tempo limite de processamento excedido. +- `400`: os parâmetros da solicitação ou o conteúdo do protocolo são inválidos. +- `401`: o token de autorização é inválido, está ausente ou expirou. +- `403`: acesso proibido, saldo insuficiente ou cota limitada. +- `404`: a API ou o modelo não existe. +- `413`: o corpo da solicitação é grande demais. +- `429`: solicitações demais. +- `500` / `503` / `504`: erro de serviço, indisponibilidade temporária ou tempo limite de processamento excedido. ### Exemplo de resposta de erro @@ -731,8 +729,7 @@ As respostas de erro da interface pública usam o envelope da plataforma Ace Dat } ``` -Essa estrutura de erro é o contrato de tempo de execução do Ace Data Cloud e não equivale ao envelope de erro oficial da Anthropic; trate-o de acordo com o status HTTP e `error.code`. +Essa estrutura de erro é o contrato de tempo de execução da Ace Data Cloud e não equivale ao envelope de erro oficial da Anthropic; processe-a de acordo com o status HTTP e `error.code`. ## Conclusão - -Por meio deste documento, você já entendeu como usar a Claude Messages API para chamar as funcionalidades de conversa do Claude no formato nativo da Anthropic. A Messages API oferece suporte a recursos avançados como conversas básicas, prompts de sistema, respostas em streaming, conversas de múltiplas rodadas, pensamento profundo, compreensão visual, PDF, cache de prompts e chamadas de ferramentas. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento. +Através deste documento, você já aprendeu como usar a API Claude Messages para chamar a funcionalidade de conversação do Claude no formato nativo da Anthropic. A API Messages oferece suporte a recursos avançados, como conversas básicas, prompts de sistema, respostas em streaming, conversas de múltiplas rodadas, raciocínio aprofundado, compreensão visual, PDFs, cache de prompts e chamadas de ferramentas. Caso tenha alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento. diff --git a/ru/guides/claude/claude_messages.mdx b/ru/guides/claude/claude_messages.mdx index bed8f2e8..117dc656 100644 --- a/ru/guides/claude/claude_messages.mdx +++ b/ru/guides/claude/claude_messages.mdx @@ -1,11 +1,11 @@ --- -title: "Получение и использование Claude Messages API" +title: "Запрос и использование Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude — это очень мощная система диалогов с ИИ: достаточно ввести промпт, и она сможет за несколько секунд сгенерировать плавный и естественный ответ. Claude Messages API — это официальный нативный формат API Anthropic, который отличается от формата, совместимого с OpenAI (Chat Completion). Он использует собственные структуры запросов и ответов Anthropic, что позволяет лучше использовать уникальные возможности Claude, такие как мультимодальный ввод контента, вызов инструментов, глубокое мышление (Extended Thinking) и другие расширенные функции. +Anthropic Claude — очень мощная система диалогов с ИИ: достаточно ввести промпт, и она сможет всего за несколько секунд сгенерировать плавный и естественный ответ. Claude Messages API — это официальный нативный формат API Anthropic. В отличие от совместимого с OpenAI формата (Chat Completion), он использует собственную структуру запросов и ответов Anthropic, что позволяет лучше задействовать уникальные возможности Claude, такие как мультимодальный ввод контента, вызов инструментов, глубокое мышление (Extended Thinking) и другие расширенные функции. -В этом документе в основном описывается процесс использования операций Claude Messages API. С его помощью мы можем использовать нативный интерфейс, соответствующий официальному Anthropic, для вызова диалоговых функций Claude. +Этот документ в основном описывает процесс использования операций Claude Messages API. С его помощью мы можем использовать нативный интерфейс, согласованный с официальным Anthropic, для вызова диалоговых функций Claude. ## Процесс получения @@ -15,30 +15,29 @@ Anthropic Claude — это очень мощная система диалог Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти; после завершения вы автоматически вернётесь на текущую страницу. -**Один API Token позволяет вызывать все сервисы платформы, не требуется подавать отдельную заявку для каждого сервиса.** При первом получении предоставляется бесплатный лимит, позволяющий бесплатно попробовать сервис; при недостатке лимита можно пополнить универсальный баланс в [консоли](https://platform.acedata.cloud/console/coin). +**Один API Token позволяет вызывать все сервисы платформы, не нужно подавать отдельную заявку для каждого сервиса.** При первом получении предоставляется бесплатный лимит, который можно использовать для бесплатного ознакомления; при недостаточном лимите можно пополнить общий баланс в [консоли](https://platform.acedata.cloud/console/coin). > 📘 Полная документация: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Базовое использование -Путь запроса Claude Messages API — `/v1/messages`, что соответствует официальному API Anthropic. Необходимо предоставить как минимум три обязательных параметра: +Путь запроса Claude Messages API — `/v1/messages`, он соответствует официальному API Anthropic. Нам необходимо предоставить как минимум три обязательных параметра: -- `model`: выбор используемой модели Claude. `claude-opus-5-5` предоставляется только через Messages API, поддерживает контекст в 1 миллион Token, максимальный вывод 128K Token и всегда включает адаптивное мышление. Новейшей флагманской моделью является `claude-fable-5-1` (контекст в 1 миллион Token, максимальный вывод 128K Token); прежняя `claude-fable-5` всё ещё сохранена для совместимости. `claude-sonnet-5-5` добавлена в серию нативных интерфейсов Messages, поддерживает ввод изображений и адаптивное мышление; её официальные справочные цены на ввод, вывод и чтение из кэша составляют соответственно 2, 10 и 0,20 доллара США за миллион Token. +- `model`: выбор используемой модели Claude. `claude-opus-5-5` предоставляется только через Messages API, поддерживает контекст в 1 миллион Token, максимальный вывод 128K Token и всегда включает адаптивное мышление. Новейшим флагманом является `claude-fable-5-1` (контекст в 1 миллион Token, максимальный вывод 128K Token); исходный `claude-fable-5` всё ещё сохранён для совместимости. `claude-sonnet-5-5` добавлен в серию нативных интерфейсов Messages, поддерживает ввод изображений и адаптивное мышление; его официальные справочные цены на ввод, вывод и чтение кэша составляют соответственно 2, 10 и 0,20 доллара США за миллион Token. - `messages`: массив входных сообщений, каждое сообщение содержит `role` (роль) и `content` (содержимое), при этом `role` поддерживает `user` и `assistant`. -- `max_tokens`: максимальное количество выходных token, используемое для ограничения длины одного ответа. +- `max_tokens`: максимальное число выходных token, используется для ограничения длины одного ответа. -Часто используемые необязательные параметры: +Распространённые необязательные параметры: -- `system`: системный промпт, используемый для задания поведения и роли модели. -- `temperature`: случайность генерации, от 0 до 1; чем больше значение, тем более разнообразным будет ответ. -- `stream`: использовать ли потоковый ответ; установка значения `true` позволяет реализовать эффект посимвольного возврата. -- `stop_sequences`: пользовательские последовательности остановки; модель прекратит генерацию при встрече с этим текстом. -- `top_p`: параметр ядерной выборки, совместно с temperature управляющий случайностью генерации. +- `system`: системный промпт, используется для задания поведения и роли модели. +- `temperature`: случайность генерации, от 0 до 1; чем больше значение, тем более вариативным будет ответ. +- `stream`: использовать ли потоковый ответ; при значении `true` можно реализовать эффект посимвольного возврата. +- `stop_sequences`: пользовательские последовательности остановки; модель прекратит генерацию при обнаружении этих текстов. +- `top_p`: параметр ядерной выборки, вместе с temperature управляет случайностью генерации. - `top_k`: выборка только из K вариантов с наивысшей вероятностью. -- `tools`: определения инструментов, используемые для того, чтобы модель вызывала внешние функции. +- `tools`: определения инструментов, используются для вызова моделью внешних функций. - `tool_choice`: управление тем, как модель использует предоставленные инструменты. -- `cache_control`: автоматически создаёт точку остановки кэша на последнем кэшируемом блоке содержимого запроса; также может быть записан на конкретном блоке содержимого. -- `metadata`: необязательный объект метаданных запроса. `metadata.user_id` является строкой и может передавать пользовательский идентификатор пользователя, определённый вызывающей стороной, например `{"user_id":"example-user-001"}`; рекомендуется использовать стабильный идентификатор, не содержащий персональной информации. Он не заменяет аутентификацию `Authorization` и не требует записи в содержимое диалога `messages`. +- `cache_control`: автоматически создаёт контрольную точку кэша на последнем кэшируемом блоке содержимого запроса; также может быть записан в конкретном блоке содержимого. ### Пример cURL @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -86,7 +83,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -После вызова результат возврата выглядит следующим образом: +После вызова результат будет следующим: ```json { @@ -109,25 +106,25 @@ print(response.json()) } ``` -Описание полей результата возврата: -- `id`：Уникальный идентификатор текущего сообщения. -- `type`：Всегда `message`. -- `role`：Всегда `assistant`. -- `content`：Массив содержимого ответа, каждый элемент содержит `type` (например, `text`) и соответствующее содержимое. -- `model`：Название модели, обрабатывающей запрос. -- `stop_reason`：Причина остановки. Стабильные значения включают `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (можно вернуть текущее содержимое assistant без изменений для продолжения), `refusal` и `model_context_window_exceeded`. -- `stop_sequence`：Если остановка произошла из-за пользовательской последовательности остановки, отображается текст совпавшей последовательности остановки. -- `stop_details`：Когда `stop_reason` имеет значение `refusal`, может содержать категорию отказа и описание. -- `usage`：Статистика использования token. `input_tokens` — некэшированный ввод; `cache_creation_input_tokens` и `cache_read_input_tokens` соответственно означают запись в кэш и чтение из него; `output_tokens` — общее число выходных token. Если возвращается `output_tokens_details.thinking_tokens`, это значение является подмножеством `output_tokens`; не добавляйте его повторно при подсчёте общего количества или стоимости. При отсутствии авторитетного подсчёта эта детализация может иметь значение `null` или быть опущена. -- `usage.cache_creation`：Необязательная детализация TTL записи в кэш, содержащая `ephemeral_5m_input_tokens` и `ephemeral_1h_input_tokens`. Если объект присутствует, сумма двух значений равна `cache_creation_input_tokens`; если поле имеет значение `null` или опущено, это означает, что для текущего ответа недоступно разбиение по TTL, и его нельзя интерпретировать как `0`. -- `usage.cost`：Непотоковые ответы могут содержать объект потребления квоты, записанный Ace Data Cloud, где `amount` — фактическое потребление за текущий раз, `currency` — единица измерения, а `list_amount` — сумма до скидки (если есть). Официальная базовая цена чтения из кэша для Fable 5.1 составляет $0.25/миллион Token, а базовые цены записи в кэш на 5 минут и 1 час составляют $12.50 и $20/миллион Token соответственно; фактическая цена платформы рассчитывается с учётом скидки тарифа. +Описание полей результата: + +- `id`: уникальный идентификатор текущего сообщения. +- `type`: всегда `message`. +- `role`: всегда `assistant`. +- `content`: массив содержимого ответа, каждый элемент содержит `type` (например, `text`) и соответствующее содержимое. +- `model`: название модели, обрабатывающей запрос. +- `stop_reason`: причина остановки. Стабильные значения включают `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (можно передать текущее содержимое assistant без изменений для продолжения), `refusal` и `model_context_window_exceeded`. +- `stop_sequence`: если остановка произошла из-за пользовательской последовательности остановки, отображается текст совпавшей последовательности остановки. +- `stop_details`: когда `stop_reason` имеет значение `refusal`, может содержать категорию отказа и описание. +- `usage`: статистика использования token. `input_tokens` — некэшированный ввод; `cache_creation_input_tokens` и `cache_read_input_tokens` — соответственно запись и чтение кэша; `output_tokens` — общее количество выходных token. Если возвращается `output_tokens_details.thinking_tokens`, это значение является подмножеством `output_tokens`; при подсчёте общего объёма или стоимости не добавляйте его повторно. При отсутствии авторитетного подсчёта эта детализация может быть `null` или опущена. +- `usage.cache_creation`: необязательная детализация TTL записи кэша, включает `ephemeral_5m_input_tokens` и `ephemeral_1h_input_tokens`. При наличии объекта сумма двух значений равна `cache_creation_input_tokens`; значение поля `null` или отсутствие поля означает, что в текущем ответе нет доступной разбивки TTL, и его нельзя интерпретировать как `0`. +- `usage.cost`: непотоковый ответ может содержать объект расхода лимита, зафиксированный Ace Data Cloud, где `amount` — фактический расход в этот раз, `currency` — единица измерения, а `list_amount` — сумма до скидки (при наличии). Официальная базовая цена чтения кэша Fable 5.1 составляет $0.25/миллион Token, а базовые цены записи кэша на 5 минут и 1 час составляют соответственно $12.50 и $20/миллион Token; фактическая цена платформы пересчитывается согласно скидке тарифа. ## Системный промпт -Claude Messages API поддерживает настройку системного промпта через поле `system`, используемое для определения поведения, роли и контекста модели. +Claude Messages API поддерживает задание системного промпта через поле `system`, используемого для определения поведения, роли и контекста модели. ### Пример Python - ```python import requests @@ -152,11 +149,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Настроив промпт `system`, можно точно контролировать роль Claude и способ его поведения. +Установив системный промпт `system`, можно точно контролировать роль и поведение Claude. -## Потоковые ответы +## Потоковый ответ -Этот интерфейс также поддерживает потоковые ответы: установите параметр `stream` в `true`, чтобы получить эффект постепенного возврата, что особенно подходит для реализации посимвольного отображения на веб-страницах. +Этот интерфейс также поддерживает потоковые ответы: установите параметр `stream` в значение `true`, чтобы получать постепенный вывод, что особенно подходит для реализации посимвольного отображения на веб-страницах. ### Пример Python @@ -186,16 +183,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Потоковые ответы возвращаются в формате Server-Sent Events (SSE), каждая строка начинается с префиксов `event:` и `data:`. Типы потоковых событий включают: +Потоковый ответ возвращается в формате Server-Sent Events (SSE), каждая строка начинается с `event:` и `data:`. Типы потоковых событий включают: -- `message_start`：Начало сообщения, содержит основную информацию о сообщении и название модели. -- `content_block_start`：Начало блока содержимого. -- `content_block_delta`：Инкрементальное обновление блока содержимого, содержит вновь сгенерированный фрагмент текста. -- `content_block_stop`：Конец блока содержимого. -- `message_delta`：Инкрементальное обновление на уровне сообщения, содержит `stop_reason` и окончательную информацию `usage`. Авторитетное значение `output_tokens_details.thinking_tokens` следует считывать только из последнего `message_delta.usage`; не суммируйте его между событиями. -- `message_stop`：Конец сообщения. +- `message_start`: начало сообщения, содержит основную информацию о сообщении и название модели. +- `content_block_start`: начало блока содержимого. +- `content_block_delta`: инкрементальное обновление блока содержимого, содержит новый сгенерированный фрагмент текста. +- `content_block_stop`: конец блока содержимого. +- `message_delta`: инкрементальное обновление на уровне сообщения, содержит информацию `stop_reason` и итоговую `usage`. Авторитетное значение `output_tokens_details.thinking_tokens` следует считывать только из последнего `message_delta.usage`, не суммируйте его между событиями. +- `message_stop`: конец сообщения. -Эффект вывода выглядит следующим образом: +Результат вывода выглядит следующим образом: ``` event: message_start @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Как видно, в потоковом ответе событие `content_block_delta` содержит постепенно генерируемое текстовое содержимое; полный ответ можно получить, объединив все `text_delta`. +Как видно, событие `content_block_delta` в потоковом ответе содержит постепенно сгенерированный текст; объединив все `text_delta`, можно получить полный ответ. ### Пример JavaScript @@ -256,7 +253,7 @@ while (true) { ## Многораундовый диалог -Если вы хотите подключить функцию многораундового диалога, необходимо поочерёдно размещать сообщения с ролями `user` и `assistant` в массиве `messages`, одновременно передавая всю предыдущую историю диалога. +Если вы хотите подключить функцию многораундового диалога, необходимо попеременно располагать сообщения с ролями `user` и `assistant` в массиве `messages` и передавать всю предыдущую историю диалога. ### Пример Python @@ -285,7 +282,8 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Результат возврата выглядит следующим образом: +Возвращаемый результат выглядит следующим образом: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -309,11 +307,11 @@ print(response.json()) Передавая полную историю диалога в `messages`, Claude может давать точные ответы с учётом контекста. -## Модели глубокого мышления +## Модель глубокого мышления -thinking и thinking summary в Claude — это два разных понятия: модель может выполнять внутренние рассуждения, но API не возвращает исходную цепочку мыслей. Когда необходимо показать процесс рассуждения, API возвращает обработанное резюме. +Thinking и thinking summary Claude — это два разных понятия: модель может выполнять внутренние рассуждения, но API не возвращает исходную цепочку мыслей. Когда необходимо отобразить процесс рассуждения, API возвращает обработанное резюме. -Для текущих моделей рекомендуется использовать adaptive thinking и управлять общими затратами на рассуждение через `output_config.effort`: +Для текущих моделей рекомендуется использовать adaptive thinking и управлять общими затратами на рассуждения через `output_config.effort`: ```python import requests @@ -352,19 +350,18 @@ print(response.json()) "signature": "opaque-signature" } ``` - - `display: "summarized"` возвращает читаемое резюме размышлений; это не исходная цепочка мыслей. -- `display: "omitted"` возвращает `thinking: ""`, но при этом сохраняет непрозрачную `signature` для поддержки последующих диалогов. -- `display: "updates"` — это beta-режим Anthropic, для которого необходимо передать `anthropic-beta: thinking-display-updates-2026-08-18`. Официальное определение: скрывает текст рассуждений и показывает краткие обновления прогресса между вызовами инструментов. Платформа передаёт этот параметр и beta-заголовок запроса без изменений и не принудительно преобразует его в `summarized`; фактическое содержимое вывода зависит от поддержки выбранной модели. -- `thinking`, `output_config`, effort, параметры семплирования и новые расширенные поля передаются без изменений. Платформа не поддерживает жёстко закодированные по моделям перечисления допустимых значений или ограничения комбинаций и не изменяет автоматически режим thinking; решение о принятии этих параметров принимает выбранная модель, а ошибки параметров, возвращаемые моделью, передаются клиенту. -- Значение display по умолчанию для Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 и Opus 4.7 — `omitted`; для Opus 4.6, Sonnet 4.6 и более ранних моделей с поддержкой thinking по умолчанию используется `summarized`. -- Display влияет только на возвращаемое содержимое и задержку потоковой передачи, но не отключает рассуждения и не уменьшает тарификацию thinking token. -- Вопрос о том, включён ли thinking по умолчанию, и вопрос о значении display по умолчанию — это два независимых вопроса. Opus 5 и Sonnet 5 по умолчанию включают adaptive thinking; для Opus 5 отсутствие `thinking` эквивалентно adaptive, а отсутствие `output_config.effort` эквивалентно `high`. Для Opus 4.8, 4.7 и 4.6 требуется явное включение. -- Thinking и итоговый текст совместно используют выходной бюджет `max_tokens`. При слишком малом бюджете thinking может занять большую часть лимита, из-за чего основной текст будет пустым или обрезанным; увеличьте `max_tokens` или используйте effort `low` / `medium` для управления затратами на рассуждение. -- Для моделей, допускающих отключение thinking, можно передать `thinking: {"type":"disabled"}`. Новые режимы, такие как `between_tools`, а также комбинации effort зависят от выбранной модели; платформа не отклоняет их заранее на основании старых правил для моделей. -- Фиксированный бюджет рассуждений можно передать через `budget_tokens`; новые модели обычно используют `thinking.type=adaptive` и `output_config.effort`. Поддержка фиксированного бюджета или отключения thinking определяется текущими возможностями выбранной модели. -- В многоходовых диалогах и при вызовах инструментов необходимо передавать обратно полный блок thinking и signature, возвращённые assistant, без изменений; не изменяйте и не создавайте signature самостоятельно. -- Прозрачная передача параметров не означает, что каждая модель поддерживает все функции. При межпротокольных вызовах всё равно требуется преобразование, а область поддержки и ошибки для такого содержимого, как `redacted_thinking`, определяются сервисом модели, фактически обрабатывающим запрос. +- `display: "omitted"` возвращает `thinking: ""`, но по-прежнему сохраняет непрозрачную `signature` для поддержки последующих диалогов. +- `display: "updates"` — это beta-режим Anthropic, требующий передачи `anthropic-beta: thinking-display-updates-2026-08-18`. Официальное определение — скрывать основной текст рассуждений и показывать краткие обновления прогресса между вызовами инструментов. Платформа передаёт этот параметр и beta-заголовок в исходном виде и не принудительно переписывает его в `summarized`; фактическое содержимое вывода зависит от поддержки выбранной моделью. +- `thinking`, `output_config`, effort, параметры сэмплирования и добавленные поля расширений передаются в исходном виде. Платформа не поддерживает жёстко закодированные по моделям перечисления значений или ограничения комбинаций и не переписывает автоматически режим thinking; решение о принятии этих параметров принимает выбранная модель, а ошибки параметров, возвращённые моделью, передаются обратно клиенту. +- Значение display по умолчанию для Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 и Opus 4.7 — `omitted`; Opus 4.6, Sonnet 4.6 и более ранние модели с поддержкой thinking по умолчанию используют `summarized`. +- Display влияет только на возвращаемое содержимое и задержку потоковой передачи, не отключает рассуждения и не уменьшает тарификацию thinking token. +- Вопрос о том, включён ли thinking по умолчанию, и значение display по умолчанию — это два независимых вопроса. Opus 5 и Sonnet 5 по умолчанию включают adaptive thinking; для Opus 5 пропуск `thinking` эквивалентен adaptive, а пропуск `output_config.effort` эквивалентен `high`. Opus 4.8, 4.7 и 4.6 требуют явного включения. +- Thinking и итоговый текст совместно используют выходной бюджет `max_tokens`. При слишком малом бюджете thinking может занять большую часть лимита, оставив текст пустым или обрезанным; увеличьте `max_tokens` или используйте effort `low` / `medium`, чтобы контролировать затраты на рассуждения. +- Для моделей, которым разрешено отключать thinking, можно передать `thinking: {"type":"disabled"}`. Новые режимы, такие как `between_tools`, а также комбинации effort зависят от выбранной модели; платформа не отклоняет их заранее на основе старых правил для моделей. +- Фиксированный бюджет размышлений можно передать через `budget_tokens`; новые модели обычно используют `thinking.type=adaptive` и `output_config.effort`. Поддержка фиксированного бюджета или отключения размышлений определяется текущими возможностями выбранной модели. +- В многоходовых диалогах и при вызовах инструментов следует передавать обратно полный блок thinking и signature, возвращённые assistant, без изменений; не изменяйте и не создавайте signature самостоятельно. +- Прозрачная передача параметров не означает, что каждая модель поддерживает все функции. Вызовы между протоколами по-прежнему требуют преобразования, а область поддержки и ошибки для такого содержимого, как `redacted_thinking`, определяются модельным сервисом, который фактически обрабатывает запрос. В потоковых запросах `summarized` создаёт `thinking_delta`; `omitted` не создаёт `thinking_delta`, сохраняя только жизненный цикл блока thinking и `signature_delta`. @@ -372,7 +369,7 @@ print(response.json()) Claude поддерживает мультимодальный ввод и может одновременно обрабатывать текст и изображения. В Messages API визуальные возможности можно использовать, установив `content` в формат массива и передав блок содержимого изображения. -### Использование изображений в кодировке Base64 +### Использование изображения с кодированием Base64 ```python import base64 @@ -418,7 +415,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### Использование URL-изображений +### Использование изображения по URL ```python import requests @@ -459,6 +456,7 @@ print(response.json()) ``` ### Пример cURL + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -488,11 +486,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Поддерживаемые форматы изображений включают: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Поддерживаемые форматы изображений: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Документы и PDF -PDF использует блок содержимого `document` и поддерживает два стабильных источника: Base64 и URL. Источник Base64 должен использовать `application/pdf`: +PDF использует блок содержимого `document` и поддерживает два стабильных источника: Base64 и URL. Источник Base64 обязательно должен использовать `application/pdf`: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -Источник URL записывается как `{"type":"url","url":"https://example.com/report.pdf"}`. `document` также поддерживает `text/plain` и источник `content`, состоящий из блоков text/image; необязательные поля включают `title`, `context` и `citations`. Источник `file_id` Files API относится к отдельной beta-функции и не входит в стабильный контракт этого интерфейса. +Источник URL записывается как `{"type":"url","url":"https://example.com/report.pdf"}`. `document` также поддерживает `text/plain` и источник `content`, состоящий из блоков text/image; необязательные поля включают `title`, `context` и `citations`. Источник `file_id` из Files API относится к отдельной beta-функции и не входит в стабильный контракт данного интерфейса. ## Кэширование промптов -`cache_control` верхнего уровня автоматически размещает точку остановки кэша на последнем кэшируемом блоке: +Верхнеуровневый `cache_control` автоматически размещает точку останова кэша на последнем кэшируемом блоке: ```python payload = { @@ -536,10 +534,9 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Когда требуется точный контроль позиции, тот же `cache_control` также можно указать в блоках содержимого text, image, document, tool_use, tool_result или в определении инструмента. `ttl` поддерживает `5m` (по умолчанию) и `1h`; определяйте запись в кэш и попадание в кэш с помощью `usage.cache_creation_input_tokens` и `usage.cache_read_input_tokens`. -Когда требуется точно контролировать расположение, такой же `cache_control` также можно записать в блоки содержимого text, image, document, tool_use, tool_result или в определение инструмента. `ttl` поддерживает `5m` (по умолчанию) и `1h`; используйте `usage.cache_creation_input_tokens` и `usage.cache_read_input_tokens` для определения записи в кэш и попадания в кэш. - -Когда ответ предоставляет `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Если `cache_creation` имеет значение `null` или опущен, это означает, что есть только общий объём записи в кэш без авторитетного разделения по TTL; в этом случае не считайте ни один bucket известным как 0, а для расчёта стоимости и общего объёма по-прежнему используйте aggregate-поля. +Когда ответ предоставляет `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Если `cache_creation` имеет значение `null` или опущен, это означает, что имеется только общий объём записи в кэш без авторитетной разбивки по TTL; в этом случае не считайте ни один bucket заведомо равным 0, а тарификация и общие объёмы по-прежнему должны основываться на aggregate-поле. Пример возвращаемого результата: @@ -566,9 +563,9 @@ payload = { ## Вызов инструментов (Tool Use) -Claude Messages API нативно поддерживает функцию вызова инструментов, позволяя модели при необходимости вызывать предварительно определённые вами инструменты/функции. +Claude Messages API нативно поддерживает функцию вызова инструментов, позволяя модели при необходимости вызывать заранее определённые вами инструменты/функции. -### Пример Python +### Пример на Python ```python import requests @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Когда модель решает вызвать инструмент, `content` в возвращаемом результате будет содержать блок содержимого типа `tool_use`: +Когда модель решает вызвать инструмент, в возвращаемом результате `content` будет содержать блок содержимого типа `tool_use`: ```json { @@ -640,7 +637,7 @@ print(response.json()) } ``` -Обратите внимание, что `stop_reason` равен `tool_use`, что означает необходимость вызова инструмента моделью. После получения этого результата вам нужно выполнить функцию инструмента и вернуть результат модели в форме `tool_result`: +Обратите внимание, что `stop_reason` имеет значение `tool_use`, что означает необходимость вызова инструмента моделью. После получения этого результата вам нужно выполнить функцию инструмента и передать результат обратно модели в форме `tool_result`: ```python payload = { @@ -692,28 +689,29 @@ print(response.json()) ## Отличия от Chat Completion API -Ace Data Cloud одновременно предоставляет два формата Claude API, основные различия между ними следующие: +Ace Data Cloud одновременно предоставляет два формата Claude API; их основные отличия приведены ниже: + +`usage.input_tokens` в Messages API обозначает только некэшированный ввод, а `cache_read_input_tokens` и `cache_creation_input_tokens` являются независимыми тарифицируемыми корзинами; все три рассчитываются отдельно по соответствующим ценам. -`usage.input_tokens` Messages API обозначает только некэшированный ввод, а `cache_read_input_tokens` и `cache_creation_input_tokens` являются отдельными тарифицируемыми bucket; все три рассчитываются отдельно по соответствующим ценам. | Характеристика | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| Формат | Нативный формат Anthropic | Совместимый с OpenAI формат | +| Формат | Нативный формат Anthropic | OpenAI-совместимый формат | | Системный промпт | Отдельное поле `system` | Передаётся через `role: "system"` в `messages` | | Структура ответа | Массив `content` (поддерживает несколько типов) | Массив `choices` (содержит `message`) | -| Формат потоковой передачи | SSE-события (несколько типов событий) | SSE-строки `data` | +| Потоковый формат | SSE-события (несколько типов событий) | Строки SSE `data` | | Глубокое мышление | Нативные `thinking` и `output_config.effort` | Стратегия модели по умолчанию и совместимые параметры | -| Вызов инструментов | Нативные `tools` + `input_schema` | Совместимый с OpenAI формат `tools` | +| Вызов инструментов | Нативные `tools` + `input_schema` | OpenAI-совместимый формат `tools` | | Статистика Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Если ваша система уже интегрирована с API формата OpenAI, вы можете использовать Chat Completion API для бесшовного переключения. Если вам необходимо использовать все нативные возможности Claude, рекомендуется использовать Messages API. +Если ваша система уже интегрирована с API формата OpenAI, для бесшовного переключения можно использовать Chat Completion API. Если вам необходимо использовать все нативные возможности Claude, рекомендуется использовать Messages API. ## Обработка ошибок -Ответы с ошибками публичного интерфейса используют envelope платформы Ace Data Cloud: `error.code` — стабильный код ошибки, `error.message` — описание, а `trace_id` используется для диагностики запроса. Распространённые HTTP-статусы включают: +Ответы об ошибках публичного интерфейса используют envelope платформы Ace Data Cloud: `error.code` — стабильный код ошибки, `error.message` — описание, а `trace_id` используется для диагностики запроса. Распространённые HTTP-статусы включают: - `400`: параметры запроса или содержимое протокола недействительны. - `401`: токен авторизации недействителен, отсутствует или истёк. -- `403`: доступ запрещён, недостаточно средств или ограничена квота. +- `403`: доступ запрещён, недостаточно средств или действуют ограничения квоты. - `404`: API или модель не существуют. - `413`: тело запроса слишком велико. - `429`: слишком много запросов. @@ -731,8 +729,7 @@ Ace Data Cloud одновременно предоставляет два фор } ``` -Эта структура ошибки является контрактом времени выполнения Ace Data Cloud и не равнозначна официальному envelope ошибок Anthropic; обрабатывайте её по HTTP-статусу и `error.code`. +Эта структура ошибки является контрактом времени выполнения Ace Data Cloud и не эквивалентна официальному envelope ошибок Anthropic; обрабатывайте её по HTTP-статусу и `error.code`. ## Заключение - -С помощью этого документа вы уже узнали, как использовать Claude Messages API для вызова диалоговых функций Claude в нативном формате Anthropic. Messages API поддерживает богатые функции, такие как базовый диалог, системные промпты, потоковые ответы, многораундовые диалоги, глубокое мышление, визуальное понимание, PDF, кэширование промптов и вызов инструментов. Если у вас возникнут какие-либо вопросы, пожалуйста, в любое время свяжитесь с нашей командой технической поддержки. +Из этого документа вы уже узнали, как использовать Claude Messages API для вызова диалоговых функций Claude в нативном формате Anthropic. Messages API поддерживает богатые возможности, такие как базовый диалог, системные подсказки, потоковые ответы, многораундовые диалоги, глубокое мышление, визуальное понимание, PDF, кэширование подсказок и вызов инструментов. Если у вас возникнут какие-либо вопросы, пожалуйста, свяжитесь с нашей командой технической поддержки в любое время. diff --git a/sr/guides/claude/claude_messages.mdx b/sr/guides/claude/claude_messages.mdx index 0f9820a1..63d0a320 100644 --- a/sr/guides/claude/claude_messages.mdx +++ b/sr/guides/claude/claude_messages.mdx @@ -3,42 +3,41 @@ title: "Prijava i korišćenje Claude Messages API-ja" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude je veoma moćan AI sistem za razgovor koji može da generiše tečne i prirodne odgovore za samo nekoliko sekundi nakon unosa prompta. Claude Messages API je zvanični izvorni API format kompanije Anthropic. Za razliku od formata kompatibilnog sa OpenAI-jem (Chat Completion), koristi sopstvenu strukturu zahteva i odgovora kompanije Anthropic, što omogućava bolje korišćenje jedinstvenih mogućnosti Claude-a, kao što su multimodalni unos sadržaja, pozivanje alata, dubinsko razmišljanje (Extended Thinking) i druge napredne funkcije. +Anthropic Claude je veoma moćan AI sistem za razgovor, koji može generisati tečne i prirodne odgovore za samo nekoliko sekundi nakon unosa upita. Claude Messages API je zvanični izvorni API format kompanije Anthropic. Za razliku od formata kompatibilnog sa OpenAI-jem (Chat Completion), koristi Anthropic-ovu sopstvenu strukturu zahteva i odgovora, što omogućava bolje korišćenje jedinstvenih Claude mogućnosti, kao što su multimodalni unos sadržaja, pozivanje alata, duboko razmišljanje (Extended Thinking) i druge napredne funkcije. -Ovaj dokument uglavnom predstavlja proces korišćenja Claude Messages API operacija. Pomoću njega možemo da koristimo izvorni interfejs usklađen sa zvaničnim Anthropic interfejsom za pozivanje Claude-ovih funkcija razgovora. +Ovaj dokument uglavnom predstavlja tok korišćenja Claude Messages API operacija. Pomoću njega možemo koristiti izvorni interfejs usklađen sa zvaničnim Anthropic-ovim za pozivanje Claude funkcije razgovora. ## Proces prijave -Da biste koristili Claude Messages API, prvo preuzmite svoj API Token sa [Ace Data Cloud konzole](https://platform.acedata.cloud/console/applications) i sačuvajte ga za kasniju upotrebu. +Da biste koristili Claude Messages API, najpre idite na [Ace Data Cloud konzolu](https://platform.acedata.cloud/console/applications) da biste dobili svoj API Token i sačuvali ga za kasnije. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Ako još niste prijavljeni ili registrovani, bićete automatski preusmereni na stranicu za prijavu, gde ćete biti pozvani da se registrujete i prijavite; nakon završetka automatski ćete se vratiti na trenutnu stranicu. +Ako još niste prijavljeni ili registrovani, automatski ćete biti preusmereni na stranicu za prijavu, koja će vas pozvati da se registrujete i prijavite, a nakon završetka automatski ćete se vratiti na trenutnu stranicu. -**Jedan API Token može da poziva sve usluge platforme, bez potrebe da se posebno prijavljujete za svaku uslugu.** Prva prijava donosi besplatni kredit za besplatno isprobavanje; kada kredit nije dovoljan, možete dopuniti univerzalni saldo u [konzoli](https://platform.acedata.cloud/console/coin). +**Jedan API Token može pozivati sve usluge platforme, bez potrebe da se posebno prijavljujete za svaku uslugu.** Prva prijava daje besplatni kredit za besplatno isprobavanje; kada kredit nije dovoljan, možete dopuniti opšti saldo u [konzoli](https://platform.acedata.cloud/console/coin). > 📘 Kompletna dokumentacija: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Osnovno korišćenje -Putanja zahteva za Claude Messages API je `/v1/messages`, što je u skladu sa zvaničnim Anthropic API-jem. Potrebno je da navedemo najmanje tri obavezna parametra: +Putanja zahteva Claude Messages API-ja je `/v1/messages`, što je u skladu sa zvaničnim Anthropic API-jem. Potrebno je da obezbedimo najmanje tri obavezna parametra: -- `model`: Izaberite Claude model koji želite da koristite. `claude-opus-5-5` je dostupan samo putem Messages API-ja, podržava kontekst od 1 milion Token-a, maksimalni izlaz od 128K Token-a i uvek ima uključeno adaptivno razmišljanje. Najnoviji vodeći model je `claude-fable-5-1` (kontekst od 1 milion Token-a, maksimalni izlaz od 128K Token-a); prethodni `claude-fable-5` je i dalje kompatibilno zadržan. `claude-sonnet-5-5` je dodat seriji izvornih Messages interfejsa, podržava unos slika i adaptivno razmišljanje; njegove zvanične referentne cene za ulaz, izlaz i čitanje keša iznose 2, 10 i 0,20 američkih dolara po milionu Token-a. -- `messages`: Niz ulaznih poruka, pri čemu svaka poruka sadrži `role` (ulogu) i `content` (sadržaj), a `role` podržava `user` i `assistant`. -- `max_tokens`: Maksimalan broj izlaznih tokena, koji se koristi za ograničavanje dužine jednog odgovora. +- `model`: Izaberite Claude model koji će se koristiti. `claude-opus-5-5` je dostupan samo putem Messages API-ja, podržava kontekst od 1 milion Token-a, maksimalni izlaz od 128K Token-a i uvek omogućava adaptivno razmišljanje. Najnoviji vodeći model je `claude-fable-5-1` (kontekst od 1 milion Token-a, maksimalni izlaz od 128K Token-a); prethodni `claude-fable-5` je i dalje zadržan radi kompatibilnosti. `claude-sonnet-5-5` je dodat u izvorni Messages serijski interfejs, podržava unos slika i adaptivno razmišljanje; njegove zvanične referentne cene za unos, izlaz i čitanje keša iznose 2, 10 i 0,20 USD po milionu Token-a. +- `messages`: Niz unetih poruka, pri čemu svaka poruka sadrži `role` (ulogu) i `content` (sadržaj), a `role` podržava `user` i `assistant`. +- `max_tokens`: Maksimalan broj izlaznih token-a, koji se koristi za ograničavanje dužine jednog odgovora. Često korišćeni opcioni parametri: -- `system`: Sistemski prompt, koji se koristi za definisanje ponašanja i uloge modela. -- `temperature`: Nasumičnost generisanja, između 0 i 1; što je vrednost veća, odgovor je divergentniji. -- `stream`: Da li se koristi strimovani odgovor; podešavanje na `true` može da ostvari efekat vraćanja reč po reč. -- `stop_sequences`: Prilagođene sekvence za zaustavljanje; model će prestati sa generisanjem kada naiđe na ove tekstove. +- `system`: Sistemski upit, koji se koristi za postavljanje ponašanja i uloge modela. +- `temperature`: Nasumičnost generisanja, između 0 i 1; što je vrednost veća, odgovor je raznovrsniji. +- `stream`: Da li koristiti strimovani odgovor; postavljanjem na `true` može se ostvariti efekat vraćanja znak po znak. +- `stop_sequences`: Prilagođene sekvence zaustavljanja; model će prestati sa generisanjem kada naiđe na ove tekstove. - `top_p`: Parametar nuklearnog uzorkovanja, koji zajedno sa temperature kontroliše nasumičnost generisanja. -- `top_k`: Uzorkuje samo iz K opcija sa najvećom verovatnoćom. -- `tools`: Definicije alata, koje se koriste kako bi model pozivao spoljne funkcije. -- `tool_choice`: Kontroliše kako model koristi ponuđene alate. -- `cache_control`: Automatski kreira tačku prekida keša na poslednjem bloku sadržaja koji se može keširati u zahtevu; može se zapisati i na konkretnom bloku sadržaja. -- `metadata`: Opcioni objekat metapodataka zahteva. `metadata.user_id` je string i može proslediti korisnički identifikator koji prilagođava pozivalac, na primer `{"user_id":"example-user-001"}`; preporučuje se korišćenje stabilnog identifikatora koji ne sadrži lične podatke. Ne zamenjuje `Authorization` autentifikaciju i ne mora se upisivati u sadržaj razgovora u `messages`. +- `top_k`: Uzorkuje se samo iz K opcija sa najvećom verovatnoćom. +- `tools`: Definicije alata, koje se koriste da model poziva spoljne funkcije. +- `tool_choice`: Kontroliše kako model koristi obezbeđene alate. +- `cache_control`: Automatski kreira prekidnu tačku keša na poslednjem kešabilnom bloku sadržaja zahteva; može se napisati i na konkretnom bloku sadržaja. ### cURL primer @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -110,24 +107,24 @@ Nakon poziva, rezultat vraćanja je sledeći: ``` Objašnjenje polja rezultata vraćanja: + - `id`: Jedinstveni identifikator ove poruke. - `type`: Uvek je `message`. - `role`: Uvek je `assistant`. -- `content`: Niz sadržaja odgovora, svaki element sadrži `type` (kao što je `text`) i odgovarajući sadržaj. +- `content`: Niz sadržaja odgovora, pri čemu svaki element sadrži `type` (kao što je `text`) i odgovarajući sadržaj. - `model`: Naziv modela koji obrađuje zahtev. -- `stop_reason`: Razlog zaustavljanja. Stabilne vrednosti uključuju `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (trenutni sadržaj assistant-a može se vratiti neizmenjen radi nastavka), `refusal` i `model_context_window_exceeded`. +- `stop_reason`: Razlog zaustavljanja. Stabilne vrednosti uključuju `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (trenutni assistant sadržaj može se vratiti neizmenjen radi nastavka), `refusal` i `model_context_window_exceeded`. - `stop_sequence`: Ako je zaustavljeno zbog prilagođene sekvence zaustavljanja, prikazuje tekst odgovarajuće sekvence zaustavljanja. -- `stop_details`: Kada je `stop_reason` `refusal`, može sadržati kategoriju i objašnjenje odbijanja. -- `usage`: Statistika korišćenja tokena. `input_tokens` su ulazni podaci koji nisu keširani; `cache_creation_input_tokens` i `cache_read_input_tokens` predstavljaju upis i čitanje keša; `output_tokens` je ukupan broj izlaznih tokena. Ako se vrati `output_tokens_details.thinking_tokens`, ta vrednost je podskup `output_tokens`; nemojte je ponovo sabirati prilikom izračunavanja ukupne količine ili troškova. Kada nema autoritativnog brojanja, ovaj detalj može biti `null` ili izostavljen. -- `usage.cache_creation`: Opcioni detalji TTL-a za upis u keš, koji sadrže `ephemeral_5m_input_tokens` i `ephemeral_1h_input_tokens`. Kada objekat postoji, zbir ove dve stavke jednak je `cache_creation_input_tokens`; ako su polja `null` ili izostavljena, to znači da trenutni odgovor nema dostupnu TTL podelu i ne može se tumačiti kao `0`. -- `usage.cost`: Neprotočni odgovori mogu sadržati objekat potrošnje kredita koji beleži Ace Data Cloud, gde je `amount` stvarno potrošen iznos za ovaj put, `currency` je merna jedinica, a `list_amount` je iznos pre popusta (ako postoji). Zvanična osnovna cena za čitanje keša za Fable 5.1 je $0.25/milion tokena, a osnovne cene upisa u keš od 5 minuta i 1 sata su $12.50 odnosno $20/milion tokena; stvarne cene platforme obračunavaju se prema popustu paketa. +- `stop_details`: Kada je `stop_reason` `refusal`, može sadržati kategoriju odbijanja i objašnjenje. +- `usage`: Statistika korišćenja token-a. `input_tokens` je nekeširani unos; `cache_creation_input_tokens` i `cache_read_input_tokens` su upisivanje u keš i čitanje iz keša; `output_tokens` je ukupan broj izlaznih token-a. Ako se vrati `output_tokens_details.thinking_tokens`, ta vrednost je podskup `output_tokens`; pri izračunavanju ukupne količine ili troškova nemojte je ponovo sabirati. Ovaj detalj može biti `null` ili izostavljen kada ne postoji autoritativno brojanje. +- `usage.cache_creation`: Opcioni detalji TTL-a za upisivanje u keš, koji sadrže `ephemeral_5m_input_tokens` i `ephemeral_1h_input_tokens`. Kada objekat postoji, zbir ove dve stavke jednak je `cache_creation_input_tokens`; polje koje je `null` ili izostavljeno znači da trenutni odgovor nema dostupnu TTL podelu i ne može se tumačiti kao `0`. +- `usage.cost`: Nestrimovani odgovor može sadržati objekat potrošnje kredita koji beleži Ace Data Cloud, gde je `amount` stvarna potrošnja ovog puta, `currency` je merna jedinica, a `list_amount` je iznos pre popusta (ako postoji). Zvanična osnovna cena za čitanje Fable 5.1 keša je $0.25/milion Token-a, a osnovne cene za upisivanje u keš od 5 minuta i 1 sata su $12.50 i $20/milion Token-a; stvarne cene platforme obračunavaju se prema popustu paketa. -## Sistemski prompt +## Sistemski upit -Claude Messages API podržava postavljanje sistemskog prompta putem polja `system`, koje se koristi za definisanje ponašanja, uloge i konteksta modela. +Claude Messages API podržava postavljanje sistemskog upita kroz polje `system`, koje se koristi za definisanje ponašanja, uloge i konteksta modela. ### Python primer - ```python import requests @@ -152,11 +149,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Postavljanjem `system` prompta možete precizno kontrolisati Claude-ovu ulogu i način ponašanja. +Podešavanjem `system` prompta možete precizno kontrolisati Claude-ovu ulogu i način ponašanja. -## Protočni odgovor +## Striming odgovor -Ovaj interfejs takođe podržava protočne odgovore; postavite parametar `stream` na `true` da biste dobili efekat postepenog vraćanja, što je veoma pogodno za implementaciju prikaza reč po reč na veb-stranici. +Ovaj interfejs takođe podržava striming odgovore; postavite parametar `stream` na `true` da biste dobili efekat postepenog vraćanja, što je veoma pogodno za ostvarivanje prikaza znak po znak na veb-stranici. ### Python primer @@ -186,14 +183,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Protočni odgovor vraća se u formatu Server-Sent Events (SSE), pri čemu svaki red počinje prefiksima `event:` i `data:`. Tipovi protočnih događaja uključuju: +Striming odgovor se vraća u formatu Server-Sent Events (SSE), pri čemu svaki red počinje sa `event:` i `data:`. Tipovi striming događaja uključuju: -- `message_start`: Početak poruke, sadrži osnovne informacije o poruci i naziv modela. -- `content_block_start`: Početak bloka sadržaja. -- `content_block_delta`: Inkrementalno ažuriranje bloka sadržaja, sadrži novogenerisani fragment teksta. -- `content_block_stop`: Kraj bloka sadržaja. -- `message_delta`: Inkrementalno ažuriranje na nivou poruke, sadrži informacije `stop_reason` i konačne `usage`. Autoritativna vrednost `output_tokens_details.thinking_tokens` treba da se čita samo iz poslednjeg `message_delta.usage`, nemojte je sabirati kroz događaje. -- `message_stop`: Kraj poruke. +- `message_start`: početak poruke, uključuje osnovne informacije o poruci i naziv modela. +- `content_block_start`: početak bloka sadržaja. +- `content_block_delta`: inkrementalno ažuriranje bloka sadržaja, uključuje novo generisani fragment teksta. +- `content_block_stop`: kraj bloka sadržaja. +- `message_delta`: inkrementalno ažuriranje na nivou poruke, uključuje informacije `stop_reason` i konačne `usage`. Merodavna vrednost `output_tokens_details.thinking_tokens` treba da se čita samo iz poslednjeg `message_delta.usage`, bez sabiranja između događaja. +- `message_stop`: kraj poruke. Efekat izlaza je sledeći: @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Može se videti da događaj `content_block_delta` u protočnom odgovoru sadrži postepeno generisani tekstualni sadržaj, a kompletan odgovor može se dobiti spajanjem svih `text_delta` vrednosti. +Može se videti da događaj `content_block_delta` u striming odgovoru sadrži postepeno generisani tekstualni sadržaj, a kompletan odgovor se može dobiti spajanjem svih `text_delta`. ### JavaScript primer @@ -256,7 +253,7 @@ while (true) { ## Višekružni razgovor -Ako želite da povežete funkciju višekružnog razgovora, potrebno je da u nizu `messages` naizmenično poređate poruke sa ulogama `user` i `assistant`, i zajedno prosledite prethodnu istoriju razgovora. +Ako želite da povežete funkciju višekružnog razgovora, potrebno je da naizmenično rasporedite poruke sa ulogama `user` i `assistant` u nizu `messages` i zajedno prosledite prethodnu istoriju razgovora. ### Python primer @@ -286,6 +283,7 @@ print(response.json()) ``` Rezultat vraćanja je sledeći: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ Rezultat vraćanja je sledeći: } ``` -Prosleđivanjem kompletne istorije razgovora u `messages`, Claude može da kombinuje kontekst kako bi davao tačne odgovore. +Prosleđivanjem kompletne istorije razgovora u `messages`, Claude može da daje precizne odgovore u skladu sa kontekstom. ## Model dubokog razmišljanja -Claude-ovi thinking i thinking summary su dva različita koncepta: model može da obavlja interno zaključivanje, ali API ne vraća originalni lanac misli. Kada je potrebno prikazati proces zaključivanja, API vraća obrađeni sažetak. +Claude-ov thinking i thinking summary su dva različita koncepta: model može da vrši interno zaključivanje, ali API ne vraća originalni lanac misli. Kada je potrebno prikazati proces zaključivanja, API vraća obrađeni sažetak. -Za trenutne modele preporučuje se korišćenje adaptive thinking-a i kontrolisanje ukupnog ulaganja u zaključivanje putem `output_config.effort`: +Za trenutni model preporučuje se korišćenje adaptive thinking-a, uz kontrolu ukupnog uloženog zaključivanja putem `output_config.effort`: ```python import requests @@ -352,27 +350,26 @@ Thinking blok u odgovoru izgleda ovako: "signature": "opaque-signature" } ``` - -- `display: "summarized"` vraća čitljiv sažetak razmišljanja; to nije originalni lanac misli. +- `display: "summarized"` vraća čitljiv sažetak razmišljanja; to nije originalni lanac razmišljanja. - `display: "omitted"` vraća `thinking: ""`, ali i dalje zadržava opaque `signature` za podršku narednim razgovorima. -- `display: "updates"` je Anthropic-ov beta režim, koji zahteva `anthropic-beta: thinking-display-updates-2026-08-18`. Zvanična definicija je skrivanje teksta zaključivanja i prikazivanje kratkih ažuriranja napretka između poziva alata. Platforma prosleđuje ovaj parametar i beta zaglavlje zahteva u izvornoj vrednosti, i neće ga prinudno prepisati u `summarized`; stvarni sadržaj izlaza zavisi od podrške izabranog modela. -- `thinking`, `output_config`, effort, parametri uzorkovanja i nova proširena polja prosleđuju se u izvornim vrednostima. Platforma ne održava tvrdo kodirane enumeracije vrednosti ili ograničenja kombinacija po modelu, niti automatski prepisuje thinking režime; o prihvatanju ovih parametara odlučuje izabrani model, a greške parametara koje vrati model biće prosleđene klijentu. -- Podrazumevana vrednost display-a za Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 i Opus 4.7 je `omitted`; Opus 4.6, Sonnet 4.6 i raniji modeli koji podržavaju thinking podrazumevano koriste `summarized`. -- Display utiče samo na vraćeni sadržaj i kašnjenje pri strimovanju, ne isključuje zaključivanje niti smanjuje naplatu thinking tokena. -- Podrazumevano omogućavanje thinking-a i podrazumevana vrednost display-a su dva nezavisna pitanja. Opus 5 i Sonnet 5 podrazumevano omogućavaju adaptive thinking; za Opus 5, izostavljanje `thinking` je ekvivalentno adaptive, a izostavljanje `output_config.effort` je ekvivalentno `high`. -- Thinking i konačni tekst zajedno zauzimaju izlazni budžet `max_tokens`. Kada je budžet premali, thinking može zauzeti većinu kvote, ostavljajući tekst praznim ili odsečenim; povećajte `max_tokens`, ili koristite `low` / `medium` effort za kontrolu ulaganja u zaključivanje. -- Za modele kojima je dozvoljeno isključivanje thinking-a, može se proslediti `thinking: {"type":"disabled"}`. Novi režimi poput `between_tools`, kao i effort kombinacije, zavise od izabranog modela; platforma ih ne odbija unapred na osnovu starih pravila za modele. +- `display: "updates"` je Anthropic-ov beta režim, koji zahteva `anthropic-beta: thinking-display-updates-2026-08-18`. Zvanična definicija je skrivanje glavnog teksta rezonovanja i prikazivanje kratkih ažuriranja napretka između poziva alata. Platforma prosleđuje ovaj parametar i beta zaglavlje zahteva u izvornom obliku i neće ga prisilno prepisivati u `summarized`; stvarni izlazni sadržaj zavisi od podrške izabranog modela. +- `thinking`, `output_config`, effort, parametri uzorkovanja i nova proširena polja prosleđuju se u izvornom obliku. Platforma ne održava hardkodirane enumeracije vrednosti ni ograničenja kombinacija po modelu, niti automatski prepisuje thinking režim; izabrani model određuje da li prihvata ove parametre, a greške parametara koje vrati model biće prosleđene klijentu. +- Podrazumevana vrednost display za Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 i Opus 4.7 je `omitted`; Opus 4.6, Sonnet 4.6 i raniji modeli koji podržavaju thinking podrazumevano koriste `summarized`. +- Display utiče samo na vraćeni sadržaj i kašnjenje strimovanja, ne isključuje rezonovanje niti smanjuje naplatu thinking tokena. +- Da li je thinking podrazumevano omogućen i podrazumevana vrednost display su dva nezavisna pitanja. Opus 5 i Sonnet 5 podrazumevano omogućavaju adaptive thinking; za Opus 5, izostavljanje `thinking` ekvivalentno je adaptive, a izostavljanje `output_config.effort` ekvivalentno je `high`. Opus 4.8, 4.7 i 4.6 zahtevaju eksplicitno omogućavanje. +- Thinking i završni tekst zajedno zauzimaju izlazni budžet `max_tokens`. Kada je budžet premali, thinking može zauzeti najveći deo limita, zbog čega tekst može biti prazan ili skraćen; povećajte `max_tokens` ili koristite `low` / `medium` effort za kontrolu ulaganja u rezonovanje. +- Za modele kod kojih je dozvoljeno isključivanje thinking-a, može se proslediti `thinking: {"type":"disabled"}`. Novi režimi poput `between_tools` i kombinacije effort-a zavise od izabranog modela; platforma ih ne odbija unapred na osnovu starih pravila za modele. - Fiksni budžet za razmišljanje može se proslediti putem `budget_tokens`; novi modeli obično koriste `thinking.type=adaptive` i `output_config.effort`. Da li su podržani fiksni budžet ili isključivanje razmišljanja zavisi od trenutnih mogućnosti izabranog modela. -- Tokom višekružnih razgovora i poziva alata, kompletan thinking blok i signature koje vrati assistant treba vratiti neizmenjene; ne menjajte niti sami generišite signature. -- Prosleđivanje parametara ne znači da svaki model podržava sve funkcije. Pozivi preko različitih protokola i dalje zahtevaju konverziju, a opseg podrške za sadržaje poput `redacted_thinking` i greške određuje servis modela koji stvarno obrađuje zahtev. +- Tokom višekružnih razgovora i poziva alata, kompletan thinking blok i signature koje vrati assistant treba vratiti neizmenjene; nemojte menjati niti samostalno generisati signature. +- Prosleđivanje parametara ne znači da svaki model podržava sve funkcije. Pozivi preko različitih protokola i dalje zahtevaju konverziju, a opseg podrške za sadržaj kao što je `redacted_thinking` i greške određuje servis modela koji stvarno obrađuje zahtev. -U strimovanim zahtevima, `summarized` će proizvesti `thinking_delta`; `omitted` neće proizvesti `thinking_delta`, već samo zadržava životni ciklus thinking bloka i `signature_delta`. +U strimovanim zahtevima, `summarized` proizvodi `thinking_delta`; `omitted` ne proizvodi `thinking_delta`, već zadržava samo životni ciklus thinking bloka i `signature_delta`. ## Vizuelni modeli -Claude podržava multimodalni unos i može istovremeno da obrađuje tekst i slike. U Messages API-ju, vizuelne mogućnosti se mogu koristiti postavljanjem `content` u format niza i prosleđivanjem bloka sadržaja slike. +Claude podržava multimodalni unos i može istovremeno obrađivati tekst i slike. U Messages API-ju, vizuelne mogućnosti se mogu koristiti postavljanjem `content` na format niza i prosleđivanjem bloka sadržaja slike. -### Korišćenje slika kodiranih u Base64 formatu +### Korišćenje Base64 kodiranih slika ```python import base64 @@ -459,6 +456,7 @@ print(response.json()) ``` ### cURL primer + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -488,11 +486,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Podržani formati slika uključuju: `image/jpeg`, `image/png`, `image/gif` i `image/webp`. +Podržani formati slika uključuju: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Dokumenti i PDF -PDF koristi sadržajni blok `document` i podržava dva stabilna izvora: Base64 i URL. Base64 izvor mora koristiti `application/pdf`: +PDF koristi sadržajni blok `document`, koji podržava dva stabilna izvora: Base64 i URL. Base64 izvor mora koristiti `application/pdf`: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -URL izvor se piše kao `{"type":"url","url":"https://example.com/report.pdf"}`. `document` takođe podržava `text/plain` i `content` izvore sastavljene od text/image blokova; opciona polja uključuju `title`, `context` i `citations`. Izvor `file_id` iz Files API-ja pripada zasebnoj beta funkciji i nije deo stabilnog ugovora ovog interfejsa. +URL izvor se piše kao `{"type":"url","url":"https://example.com/report.pdf"}`. `document` takođe podržava `text/plain` i `content` izvor sastavljen od text/image blokova; opciona polja uključuju `title`, `context` i `citations`. `file_id` izvor Files API-ja pripada nezavisnoj beta funkciji i nije deo stabilnog ugovora ovog interfejsa. -## Keširanje upita +## Keširanje promptova -`cache_control` na najvišem nivou automatski postavlja tačku prekida keširanja na poslednji blok koji se može keširati: +`cache_control` na najvišem nivou automatski postavlja tačku prekida keša na poslednji blok koji se može keširati: ```python payload = { @@ -536,12 +534,11 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Kada je potrebno precizno kontrolisati pozicije, isti `cache_control` se takođe može napisati na sadržajnim blokovima text, image, document, tool_use, tool_result ili na definicijama alata. `ttl` podržava `5m` (podrazumevano) i `1h`; koristite `usage.cache_creation_input_tokens` i `usage.cache_read_input_tokens` da biste utvrdili upis u keš i pogodak keša. -Kada je potrebna precizna kontrola pozicije, isti `cache_control` se takođe može zapisati na sadržajne blokove text, image, document, tool_use, tool_result ili na definicije alata. `ttl` podržava `5m` (podrazumevano) i `1h`; koristite `usage.cache_creation_input_tokens` i `usage.cache_read_input_tokens` da biste utvrdili upisivanje u keš i pogodak u kešu. - -Kada odgovor pruža `usage.cache_creation`, važi `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Ako je `cache_creation` `null` ili je izostavljen, to znači da postoji samo ukupna količina upisivanja u keš, bez pouzdane TTL podele; u tom slučaju nijedan bucket ne treba smatrati poznatim kao 0, a naplata i ukupna količina i dalje se zasnivaju na agregatnom polju. +Kada odgovor pruža `usage.cache_creation`, važi `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Ako je `cache_creation` `null` ili izostavljen, to znači da postoji samo ukupna količina upisa u keš, bez autoritativne TTL podele; u tom slučaju nemojte nijedan bucket smatrati poznatim kao 0, a naplata i ukupna količina i dalje se zasnivaju na agregatnom polju. -Primer vraćenog rezultata: +Primer rezultata povratka: ```json { @@ -566,7 +563,7 @@ Primer vraćenog rezultata: ## Pozivanje alata (Tool Use) -Claude Messages API izvorno podržava funkciju pozivanja alata, omogućavajući modelu da po potrebi pozove vaše unapred definisane alate/funkcije. +Claude Messages API izvorno podržava funkcionalnost pozivanja alata, omogućavajući modelu da po potrebi poziva vaše unapred definisane alate/funkcije. ### Python primer @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Kada model odluči da pozove alat, `content` u vraćenom rezultatu će sadržati sadržajni blok tipa `tool_use`: +Kada model odluči da pozove alat, `content` u rezultatu povratka će sadržati sadržajni blok tipa `tool_use`: ```json { @@ -640,7 +637,7 @@ Kada model odluči da pozove alat, `content` u vraćenom rezultatu će sadržati } ``` -Imajte na umu da je `stop_reason` `tool_use`, što ukazuje da model treba da pozove alat. Nakon prijema ovog rezultata, potrebno je da izvršite funkciju alata i vratite rezultat modelu u obliku `tool_result`: +Imajte na umu da je `stop_reason` `tool_use`, što ukazuje na to da model treba da pozove alat. Nakon prijema ovog rezultata, potrebno je da izvršite funkciju alata i vratite rezultat modelu u obliku `tool_result`: ```python payload = { @@ -688,38 +685,39 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Model će na osnovu rezultata koje je alat vratio generisati konačni odgovor na prirodnom jeziku. +Model će na osnovu rezultata koji vrati alat generisati konačan odgovor na prirodnom jeziku. ## Razlike u odnosu na Chat Completion API Ace Data Cloud istovremeno pruža dva Claude API formata, a njihove glavne razlike su sledeće: -`usage.input_tokens` u Messages API-ju predstavlja samo ulaz koji nije keširan, dok su `cache_read_input_tokens` i `cache_creation_input_tokens` nezavisni obračunski bucket-i; sva tri se zasebno obračunavaju prema odgovarajućim cenama. +`usage.input_tokens` u Messages API-ju predstavlja samo ulaz bez keša, dok su `cache_read_input_tokens` i `cache_creation_input_tokens` nezavisni obračunski bucket-i; sva tri se posebno izračunavaju prema odgovarajućim cenama. + | Karakteristika | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| Format | Anthropic izvorni format | OpenAI kompatibilan format | -| Sistemska prompt poruka | Nezavisno polje `system` | Prosleđuje se kroz `role: "system"` u `messages` | +| Format | Anthropic izvorni format | OpenAI kompatibilni format | +| Sistemski prompt | Nezavisno polje `system` | Prosleđuje se putem `role: "system"` u `messages` | | Struktura odgovora | Niz `content` (podržava više tipova) | Niz `choices` (sadrži `message`) | -| Format strimovanja | SSE događaji (više tipova događaja) | SSE `data` redovi | -| Duboko razmišljanje | Izvorni `thinking` i `output_config.effort` | Podrazumevana strategija modela i kompatibilni parametri | -| Pozivanje alata | Izvorni `tools` + `input_schema` | OpenAI kompatibilan format `tools` | +| Striming format | SSE događaji (više tipova događaja) | SSE `data` redovi | +| Dubinsko razmišljanje | Izvorni `thinking` i `output_config.effort` | Podrazumevana strategija modela i kompatibilni parametri | +| Pozivanje alata | Izvorni `tools` + `input_schema` | OpenAI kompatibilni `tools` format | | Token statistika | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Ako je vaš sistem već integrisan sa API-jem u OpenAI formatu, možete koristiti Chat Completion API za neometano prebacivanje. Ako vam je potrebno da koristite sve Claude-ove izvorne mogućnosti, preporučuje se korišćenje Messages API-ja. +Ako je vaš sistem već integrisan sa API-jem u OpenAI formatu, možete koristiti Chat Completion API za neprimetno prebacivanje. Ako vam je potrebno da koristite sve Claude izvorne mogućnosti, preporučuje se korišćenje Messages API-ja. -## Rukovanje greškama +## Obrada grešaka -Odgovori na greške javnog interfejsa koriste Ace Data Cloud platform envelope: `error.code` je stabilan kod greške, `error.message` je objašnjenje, a `trace_id` se koristi za istraživanje zahteva. Uobičajeni HTTP statusi uključuju: +Odgovori o greškama javnog interfejsa koriste Ace Data Cloud platform envelope: `error.code` je stabilan kod greške, `error.message` je objašnjenje, a `trace_id` se koristi za dijagnostikovanje zahteva. Uobičajeni HTTP statusi uključuju: - `400`: Parametri zahteva ili sadržaj protokola su nevažeći. -- `401`: Token za autorizaciju je nevažeći, nedostaje ili je istekao. +- `401`: Autorizacioni token je nevažeći, nedostaje ili je istekao. - `403`: Pristup je zabranjen, stanje je nedovoljno ili je kvota ograničena. - `404`: API ili model ne postoji. - `413`: Telo zahteva je preveliko. - `429`: Previše zahteva. -- `500` / `503` / `504`: Greška usluge, privremeno nedostupno ili je obrada istekla. +- `500` / `503` / `504`: Greška usluge, privremena nedostupnost ili istek vremena obrade. -### Primer odgovora na grešku +### Primer odgovora o grešci ```json { @@ -731,8 +729,7 @@ Odgovori na greške javnog interfejsa koriste Ace Data Cloud platform envelope: } ``` -Ova struktura greške je ugovor u toku izvršavanja za Ace Data Cloud i nije ekvivalentna zvaničnom Anthropic error envelope-u; postupajte prema HTTP statusu i `error.code`. +Ova struktura greške je ugovor tokom izvršavanja Ace Data Cloud-a i nije ekvivalentna Anthropic zvaničnom error envelope-u; obrađujte je prema HTTP statusu i `error.code`. ## Zaključak - -Putem ovog dokumenta, već ste saznali kako da koristite Claude Messages API za pozivanje Claude-ovih funkcija za razgovor u Anthropic izvornom formatu. Messages API podržava bogate funkcije kao što su osnovni razgovori, sistemske prompt poruke, strimovani odgovori, razgovori u više rundi, duboko razmišljanje, vizuelno razumevanje, PDF, keširanje promptova i pozivanje alata. Ako imate bilo kakvih pitanja, slobodno kontaktirajte naš tim tehničke podrške. +Kroz ovaj dokument, već ste saznali kako da koristite Claude Messages API za pozivanje Claude-ove funkcije razgovora u Anthropic izvornom formatu. Messages API podržava bogate funkcije kao što su osnovni razgovor, sistemski upiti, strimovani odgovori, višekružni razgovori, duboko razmišljanje, vizuelno razumevanje, PDF, keširanje upita i pozivanje alata. Ako imate bilo kakvih pitanja, slobodno kontaktirajte naš tim tehničke podrške. diff --git a/sv/guides/claude/claude_messages.mdx b/sv/guides/claude/claude_messages.mdx index 88b231de..b76362e1 100644 --- a/sv/guides/claude/claude_messages.mdx +++ b/sv/guides/claude/claude_messages.mdx @@ -3,9 +3,9 @@ title: "Ansökan och användning av Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude är ett mycket kraftfullt AI-konversationssystem som kan generera flytande och naturliga svar på bara några sekunder genom att mata in en prompt. Claude Messages API är Anthropics officiella inbyggda API-format. Till skillnad från det OpenAI-kompatibla formatet (Chat Completion) använder det Anthropics egen struktur för förfrågningar och svar, vilket gör det möjligt att bättre utnyttja Claudes unika funktioner, såsom multimodala innehållsinmatningar, verktygsanrop, fördjupat tänkande (Extended Thinking) och andra avancerade funktioner. +Anthropic Claude är ett mycket kraftfullt AI-konversationssystem som kan generera flytande och naturliga svar på bara några sekunder genom att ange en prompt. Claude Messages API är Anthropics officiella inbyggda API-format. Till skillnad från det OpenAI-kompatibla formatet (Chat Completion) använder det Anthropics egen struktur för förfrågningar och svar, vilket gör det möjligt att bättre utnyttja Claudes unika funktioner, såsom multimodalt innehållsinmatning, verktygsanrop, djupgående tänkande (Extended Thinking) och andra avancerade funktioner. -Detta dokument introducerar främst användningsprocessen för Claude Messages API-operationer. Med hjälp av det kan vi använda samma inbyggda gränssnitt som Anthropic officiellt erbjuder för att anropa Claudes konversationsfunktioner. +Det här dokumentet introducerar huvudsakligen användningsprocessen för Claude Messages API. Med hjälp av det kan vi använda ett inbyggt gränssnitt som är konsekvent med Anthropics officiella för att anropa Claudes konversationsfunktioner. ## Ansökningsprocess @@ -13,32 +13,31 @@ För att använda Claude Messages API går du först till [Ace Data Cloud-konsol ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Om du ännu inte är inloggad eller registrerad omdirigeras du automatiskt till inloggningssidan där du uppmanas att registrera dig och logga in. När det är klart återvänder du automatiskt till den aktuella sidan. +Om du ännu inte har loggat in eller registrerat dig kommer du automatiskt att omdirigeras till inloggningssidan för att registrera och logga in. När detta är klart återgår du automatiskt till den aktuella sidan. -**En API Token kan anropa alla plattformstjänster, utan att du behöver ansöka separat för varje tjänst.** Vid den första ansökan får du gratis kredit för kostnadsfri testning; när krediten är otillräcklig kan du fylla på det gemensamma saldot i [konsolen](https://platform.acedata.cloud/console/coin). +**En API Token kan anropa alla plattformens tjänster, utan att du behöver ansöka separat för varje tjänst.** Vid första ansökan får du en gratis kvot för kostnadsfri testning; om kvoten inte räcker till kan du fylla på det gemensamma saldot i [konsolen](https://platform.acedata.cloud/console/coin). > 📘 Fullständig dokumentation: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Grundläggande användning -Claude Messages API:s förfrågningssökväg är `/v1/messages`, vilket överensstämmer med Anthropics officiella API. Vi behöver åtminstone ange tre obligatoriska parametrar: +Förfrågningssökvägen för Claude Messages API är `/v1/messages`, vilket överensstämmer med Anthropics officiella API. Vi behöver minst ange tre obligatoriska parametrar: -- `model`: Välj Claude-modellen som ska användas. `claude-opus-5-5` erbjuds endast via Messages API, stöder 1 miljon Token kontext, maximalt utdata på 128K Token och har alltid adaptivt tänkande aktiverat. Den senaste flaggskeppsmodellen är `claude-fable-5-1` (1 miljon Token kontext, maximalt utdata på 128K Token); den tidigare `claude-fable-5` behålls fortfarande för kompatibilitet. `claude-sonnet-5-5` har lagts till i den inbyggda Messages-seriens gränssnitt och stöder bildinmatning och adaptivt tänkande; dess officiella referenspriser för indata, utdata och cacheläsning är 2, 10 respektive 0,20 USD per miljon Token. +- `model`: Välj vilken Claude-modell som ska användas. `claude-opus-5-5` tillhandahålls endast via Messages API, stöder 1 miljon Token kontext, högst 128K Token utdata och aktiverar alltid adaptivt tänkande. Den senaste flaggskeppsmodellen är `claude-fable-5-1` (1 miljon Token kontext, högst 128K Token utdata); den tidigare `claude-fable-5` behålls fortfarande för kompatibilitet. `claude-sonnet-5-5` har lagts till i serien av inbyggda Messages-gränssnitt och stöder bildinmatning och adaptivt tänkande; dess officiella referenspriser för indata, utdata och cacheläsning är 2, 10 respektive 0,20 USD per miljon Token. - `messages`: Matrisen med inmatade meddelanden, där varje meddelande innehåller `role` (roll) och `content` (innehåll), och `role` stöder `user` och `assistant`. -- `max_tokens`: Maximalt antal token för utdata, används för att begränsa längden på ett enskilt svar. +- `max_tokens`: Maximalt antal token för utdata, som används för att begränsa längden på ett enskilt svar. Vanliga valfria parametrar: -- `system`: Systemprompt, används för att ange modellens beteende och roll. -- `temperature`: Genereringsslumpmässighet, mellan 0 och 1; ju högre värde, desto mer varierande blir svaren. -- `stream`: Om strömmande svar ska användas; ange `true` för att uppnå en effekt där resultatet returneras tecken för tecken. +- `system`: Systemprompt, som används för att ange modellens beteende och roll. +- `temperature`: Slumpmässighet vid generering, mellan 0 och 1; ju högre värde, desto mer spridda blir svaren. +- `stream`: Om strömmande svar ska användas; sätt till `true` för att uppnå en effekt där svaret returneras tecken för tecken. - `stop_sequences`: Anpassade stoppsekvenser; modellen slutar generera när den stöter på dessa texter. - `top_p`: Parameter för kärnurval, som tillsammans med temperature styr slumpmässigheten i genereringen. -- `top_k`: Sampla endast bland de K alternativ med högst sannolikhet. -- `tools`: Verktygsdefinitioner, används för att låta modellen anropa externa funktioner. +- `top_k`: Sampla endast från de K alternativ med högst sannolikhet. +- `tools`: Verktygsdefinitioner, som används för att låta modellen anropa externa funktioner. - `tool_choice`: Styr hur modellen använder de tillhandahållna verktygen. -- `cache_control`: Skapa automatiskt en cachebrytpunkt vid det sista cachebara innehållsblocket i förfrågan; kan även skrivas på ett specifikt innehållsblock. -- `metadata`: Valfritt objekt för förfrågningsmetadata. `metadata.user_id` är en sträng och kan överföra en anpassad användaridentifierare från anroparen, till exempel `{"user_id":"example-user-001"}`; det rekommenderas att använda en stabil identifierare som inte innehåller personuppgifter. Den ersätter inte `Authorization`-autentisering och behöver inte skrivas in i konversationsinnehållet i `messages`. +- `cache_control`: Skapar automatiskt en cachebrytpunkt vid det sista cachebara innehållsblocket i förfrågan; kan även skrivas på ett specifikt innehållsblock. ### cURL-exempel @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -86,7 +83,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Efter anropet returneras resultatet enligt följande: +Efter anropet ser returresultatet ut enligt följande: ```json { @@ -109,25 +106,25 @@ Efter anropet returneras resultatet enligt följande: } ``` -Förklaring av fälten i returresultatet: +Beskrivning av fälten i returresultatet: + - `id`: Den unika identifieraren för detta meddelande. - `type`: Alltid `message`. - `role`: Alltid `assistant`. -- `content`: En array med svarsinnnehåll, där varje element innehåller `type` (t.ex. `text`) och motsvarande innehåll. -- `model`: Namnet på modellen som behandlar begäran. -- `stop_reason`: Orsaken till stoppet. Stabila värden inkluderar `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (du kan returnera det aktuella assistant-innehållet oförändrat för att fortsätta), `refusal` och `model_context_window_exceeded`. +- `content`: Matris med svarsinnehåll, där varje element innehåller `type` (till exempel `text`) och motsvarande innehåll. +- `model`: Namnet på modellen som behandlar förfrågan. +- `stop_reason`: Orsaken till stoppet. Stabila värden omfattar `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (du kan skicka tillbaka det aktuella assistant-innehållet oförändrat för att fortsätta), `refusal` och `model_context_window_exceeded`. - `stop_sequence`: Om stoppet beror på en anpassad stoppsekvens visas den matchande stoppsekvenstexten. -- `stop_details`: När `stop_reason` är `refusal` kan detta innehålla en avslagskategori och en beskrivning. -- `usage`: Tokenanvändningsstatistik. `input_tokens` är ocachad indata; `cache_creation_input_tokens` och `cache_read_input_tokens` är cache-skrivning respektive cache-läsning; `output_tokens` är det totala antalet utdata-token. Om `output_tokens_details.thinking_tokens` returneras är detta värde en delmängd av `output_tokens`; lägg inte till det igen vid beräkning av total mängd eller kostnad. Denna detalj kan vara `null` eller utelämnas när det saknas en auktoritativ räkning. -- `usage.cache_creation`: Valfria TTL-detaljer för cache-skrivning, inklusive `ephemeral_5m_input_tokens` och `ephemeral_1h_input_tokens`. När objektet finns är summan av de två lika med `cache_creation_input_tokens`; ett fält som är `null` eller utelämnat innebär att den aktuella responsen inte har någon tillgänglig TTL-uppdelning och ska inte tolkas som `0`. -- `usage.cost`: Icke-strömmande svar kan innehålla ett objekt för förbrukade krediter som registrerats av Ace Data Cloud, där `amount` är den faktiska förbrukningen för denna gång, `currency` är måttenheten och `list_amount` är beloppet före rabatt (om tillämpligt). Fable 5.1:s officiella grundpris för cache-läsning är $0.25/miljon token, och grundpriserna för 5-minuters- och 1-timmes-cache-skrivning är $12.50 respektive $20/miljon token; plattformens faktiska pris beräknas enligt planrabatten. +- `stop_details`: När `stop_reason` är `refusal` kan den innehålla avslagskategori och förklaring. +- `usage`: Statistik över tokenanvändning. `input_tokens` är ocachad indata; `cache_creation_input_tokens` och `cache_read_input_tokens` är cache-skrivning respektive -läsning; `output_tokens` är det totala antalet token för utdata. Om `output_tokens_details.thinking_tokens` returneras är detta värde en delmängd av `output_tokens`; lägg inte till det igen när du beräknar totalmängd eller kostnad. Denna detaljinformation kan vara `null` eller utelämnas om det saknas en auktoritativ räkning. +- `usage.cache_creation`: Valfri TTL-detaljinformation för cache-skrivning, som innehåller `ephemeral_5m_input_tokens` och `ephemeral_1h_input_tokens`. När objektet finns är summan av de två lika med `cache_creation_input_tokens`; om fältet är `null` eller utelämnas betyder det att den aktuella responsen inte har någon tillgänglig TTL-uppdelning och får inte tolkas som `0`. +- `usage.cost`: Icke-strömmande svar kan innehålla ett objekt för kvotförbrukning som registreras av Ace Data Cloud, där `amount` är den faktiska förbrukningen denna gång, `currency` är mätenheten och `list_amount` är beloppet före rabatt (om sådant finns). Fable 5.1:s officiella grundpris för cacheläsning är $0,25/miljon Token, och grundpriserna för cache-skrivning på 5 minuter respektive 1 timme är $12,50 och $20/miljon Token; plattformens faktiska priser beräknas utifrån paketets rabatt. ## Systemprompt -Claude Messages API stöder inställning av systempromptar via fältet `system`, som används för att definiera modellens beteende, roll och kontext. +Claude Messages API stöder att ange en systemprompt via fältet `system`, som används för att definiera modellens beteende, roll och kontext. ### Python-exempel - ```python import requests @@ -156,7 +153,7 @@ Genom att ställa in `system`-prompten kan du exakt styra Claudes roll och betee ## Strömmande svar -Detta gränssnitt stöder också strömmande svar. Ställ bara in parametern `stream` till `true` för att få en stegvis retur, vilket är mycket lämpligt för att implementera teckenvis visning på webbsidor. +Detta gränssnitt stöder också strömmande svar. Ställ bara parametern `stream` till `true` för att få en effekt där svar returneras stegvis, vilket är mycket lämpligt för att implementera visning tecken för tecken på webbsidor. ### Python-exempel @@ -186,16 +183,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Strömmande svar returneras i formatet Server-Sent Events (SSE), där varje rad har prefixen `event:` och `data:`. Typer av strömmande händelser inkluderar: +Strömmande svar returneras i formatet Server-Sent Events (SSE), där varje rad har prefixet `event:` och `data:`. Typer av strömmande händelser inkluderar: - `message_start`: Meddelandet börjar och innehåller grundläggande information om meddelandet och modellnamnet. - `content_block_start`: Innehållsblocket börjar. -- `content_block_delta`: Innehållsblockets inkrementella uppdatering, som innehåller den nyligen genererade textdelen. +- `content_block_delta`: Stegvis uppdatering av innehållsblocket, innehåller det nyligen genererade textsegmentet. - `content_block_stop`: Innehållsblocket avslutas. -- `message_delta`: Inkrementell uppdatering på meddelandenivå, som innehåller `stop_reason` och den slutliga `usage`-informationen. Det auktoritativa värdet för `output_tokens_details.thinking_tokens` ska endast läsas från den sista `message_delta.usage`; ackumulera inte över händelser. +- `message_delta`: Stegvis uppdatering på meddelandenivå, innehåller `stop_reason` och slutlig `usage`-information. Det auktoritativa värdet för `output_tokens_details.thinking_tokens` ska endast läsas från den sista `message_delta.usage`, och får inte ackumuleras över händelser. - `message_stop`: Meddelandet avslutas. -Uteffekten är följande: +Utdataeffekten är följande: ``` event: message_start @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Som du kan se innehåller händelsen `content_block_delta` i strömmande svar det stegvis genererade textinnehållet, och du kan få det fullständiga svaret genom att sammanfoga alla `text_delta`. +Som du kan se innehåller händelsen `content_block_delta` i det strömmande svaret textinnehåll som genereras stegvis. Genom att sammanfoga alla `text_delta` kan du få det fullständiga svaret. ### JavaScript-exempel @@ -256,7 +253,7 @@ while (true) { ## Fleromgångsdialog -Om du vill ansluta funktionen för flergångsdialog måste du arrangera meddelanden med rollerna `user` och `assistant` växelvis i arrayen `messages` och skicka med den tidigare dialoghistoriken. +Om du vill ansluta till funktionalitet för flеромgångsdialog behöver du placera meddelanden med rollerna `user` och `assistant` växelvis i arrayen `messages` och skicka med den tidigare dialoghistoriken. ### Python-exempel @@ -286,6 +283,7 @@ print(response.json()) ``` Returresultatet är följande: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ Returresultatet är följande: } ``` -Genom att skicka den fullständiga konversationshistoriken i `messages` kan Claude ge korrekta svar med hjälp av kontexten. +Genom att skicka den fullständiga dialoghistoriken i `messages` kan Claude ge korrekta svar utifrån sammanhanget. -## Modeller för djupgående tänkande +## Modell för djupgående tänkande -Claudes thinking och thinking summary är två olika begrepp: modellen kan utföra intern slutledning, men API:et returnerar inte den ursprungliga tankekedjan. När slutledningsprocessen behöver visas returnerar API:et en bearbetad sammanfattning. +Claudes thinking och thinking summary är två olika begrepp: modellen kan utföra intern slutledning, men API:t returnerar inte den ursprungliga tankekedjan. När slutledningsprocessen behöver visas returnerar API:t i stället en bearbetad sammanfattning. -För närvarande rekommenderas adaptivt tänkande för modeller, och den övergripande slutledningsinsatsen styrs via `output_config.effort`: +Den aktuella modellen rekommenderar att använda adaptive thinking och att styra den övergripande slutledningsinsatsen via `output_config.effort`: ```python import requests @@ -352,27 +350,26 @@ Thinking-blocket i svaret ser ut så här: "signature": "opaque-signature" } ``` - - `display: "summarized"` returnerar en läsbar sammanfattning av tänkandet; det är inte den ursprungliga tankekedjan. -- `display: "omitted"` returnerar `thinking: ""`, men behåller fortfarande den opaque `signature` för att stödja efterföljande konversationer. -- `display: "updates"` är Anthropics beta-läge och kräver `anthropic-beta: thinking-display-updates-2026-08-18`. Den officiella definitionen är att dölja slutledningens brödtext och visa korta statusuppdateringar mellan verktygsanrop. Plattformen vidarebefordrar denna parameter och beta-begärandehuvudet med deras ursprungliga värden och tvingar inte fram omskrivning till `summarized`; det faktiska utdata-innehållet beror på stödet i den valda modellen. -- `thinking`, `output_config`, effort, samplingsparametrar och nya utökade fält vidarebefordras med sina ursprungliga värden. Plattformen upprätthåller inte hårdkodade uppräkningar av värden eller kombinationsbegränsningar per modell, och skriver inte heller automatiskt om thinking-läget; huruvida dessa parametrar accepteras avgörs av den valda modellen, och parameterfel som returneras av modellen skickas vidare till klienten. +- `display: "omitted"` returnerar `thinking: ""`, men behåller fortfarande den opaque `signature` för att stödja efterföljande samtal. +- `display: "updates"` är Anthropics beta-läge och kräver `anthropic-beta: thinking-display-updates-2026-08-18`. Den officiella definitionen är att dölja resonemangstexten och visa korta uppdateringar om framsteg mellan verktygsanrop. Plattformen vidarebefordrar parametern och beta-begärandehuvudet enligt ursprungsvärdena och tvingar inte fram en omskrivning till `summarized`; det faktiska utdatainnehållet beror på stödet hos den valda modellen. +- `thinking`, `output_config`, effort, samplingsparametrar och nya utvidgningsfält vidarebefordras enligt ursprungsvärdena. Plattformen upprätthåller inte hårdkodade värdeuppräkningar eller kombinationsbegränsningar per modell och skriver inte heller automatiskt om thinking-läget; huruvida dessa parametrar accepteras avgörs av den valda modellen, och parameterfel som returneras av modellen skickas tillbaka till klienten. - Standardvärdet för display för Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 och Opus 4.7 är `omitted`; Opus 4.6, Sonnet 4.6 och tidigare modeller som stöder thinking använder som standard `summarized`. -- Display påverkar endast det returnerade innehållet och fördröjningen vid streaming, och stänger inte av slutledning eller minskar debiteringen för thinking-token. -- Huruvida thinking är aktiverat som standard och display-standardvärdet är två separata frågor. Opus 5 och Sonnet 5 har adaptive thinking aktiverat som standard; för Opus 5 är utelämnande av `thinking` likvärdigt med adaptive, och utelämnande av `output_config.effort` likvärdigt med `high`. Opus 4.8, 4.7 och 4.6 kräver uttrycklig aktivering. -- Thinking och den slutliga brödtexten delar på utdata-budgeten `max_tokens`. Om budgeten är för liten kan thinking använda större delen av utrymmet, vilket gör att brödtexten blir tom eller avkortas; öka `max_tokens`, eller använd `low` / `medium` effort för att styra slutledningsinsatsen. -- För modeller som tillåter att thinking stängs av kan `thinking: {"type":"disabled"}` skickas. Nya lägen som `between_tools` samt effort-kombinationer beror på den valda modellen; plattformen avvisar dem inte i förväg baserat på gamla modellregler. -- En fast tänkandebudget kan skickas via `budget_tokens`; nya modeller använder normalt `thinking.type=adaptive` och `output_config.effort`. Huruvida fast budget eller avstängning av tänkande stöds beror på den valda modellens aktuella kapacitet. -- Vid fleromgångskonversationer och verktygsanrop bör det fullständiga thinking-blocket och signature som returneras av assistant skickas tillbaka oförändrade; ändra inte eller generera själv signature. -- Parameter-vidarebefordring innebär inte att varje modell stöder alla funktioner. Anrop över protokoll kräver fortfarande konvertering, och omfattningen av stöd samt fel för innehåll såsom `redacted_thinking` avgörs av den modelltjänst som faktiskt behandlar begäran. +- Display påverkar endast det returnerade innehållet och strömningsfördröjningen, stänger inte av resonemang och minskar inte debiteringen för thinking-token. +- Om thinking är aktiverat som standard och display-standardvärdet är två separata frågor. Opus 5 och Sonnet 5 har adaptive thinking aktiverat som standard; för Opus 5 är utelämnande av `thinking` likvärdigt med adaptive, och utelämnande av `output_config.effort` är likvärdigt med `high`. Opus 4.8, 4.7 och 4.6 kräver uttrycklig aktivering. +- Thinking och den slutliga brödtexten delar på utmatningsbudgeten `max_tokens`. Om budgeten är för liten kan thinking ta upp större delen av utrymmet, vilket gör att brödtexten blir tom eller trunkeras; öka `max_tokens`, eller använd `low` / `medium` effort för att styra resonemangsinsatsen. +- För modeller som tillåter att thinking stängs av kan `thinking: {"type":"disabled"}` skickas. Nya lägen såsom `between_tools` och effort-kombinationer beror på den valda modellen; plattformen avvisar dem inte i förväg baserat på gamla modellregler. +- Fast tänkandebudget kan skickas via `budget_tokens`; nya modeller använder vanligtvis `thinking.type=adaptive` och `output_config.effort`. Huruvida fast budget eller avstängning av thinking stöds beror på den valda modellens aktuella kapacitet. +- Vid flerrundssamtal och verktygsanrop bör det fullständiga thinking-blocket och signature som returneras av assistant skickas tillbaka oförändrade; ändra inte eller skapa själv signature. +- Parameter-vidarebefordran innebär inte att varje modell stöder alla funktioner. Anrop över olika protokoll kräver fortfarande konvertering, och stödomfånget samt fel för innehåll såsom `redacted_thinking` avgörs av den modelltjänst som faktiskt behandlar begäran. -I strömmande begäranden genererar `summarized` `thinking_delta`; `omitted` genererar inte `thinking_delta`, utan behåller endast thinking-blockets livscykel och `signature_delta`. +I strömningsbegäranden ger `summarized` upphov till `thinking_delta`; `omitted` ger inte upphov till `thinking_delta`, utan behåller endast thinking-blockets livscykel och `signature_delta`. ## Visuella modeller -Claude stöder multimodala indata och kan bearbeta text och bilder samtidigt. I Messages API kan visuella funktioner användas genom att ange `content` i array-format och skicka ett bildinnehållsblock. +Claude stöder multimodala indata och kan behandla text och bilder samtidigt. I Messages API kan visuella funktioner användas genom att ange `content` i matrisformat och skicka ett bildinnehållsblock. -### Använda Base64-kodade bilder +### Använd Base64-kodade bilder ```python import base64 @@ -418,7 +415,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### Använda URL-bilder +### Använd URL-bilder ```python import requests @@ -459,6 +456,7 @@ print(response.json()) ``` ### cURL-exempel + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -488,11 +486,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Bildformat som stöds inkluderar: `image/jpeg`, `image/png`, `image/gif` och `image/webp`. +Bildformat som stöds omfattar: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Dokument och PDF -PDF använder innehållsblocket `document` och stöder två stabila källor: Base64 och URL. Base64-källor måste använda `application/pdf`: +PDF använder innehållsblocket `document` och stöder de två stabila källorna Base64 och URL. Base64-källor måste använda `application/pdf`: ```python import base64 @@ -521,7 +519,7 @@ payload = { } ``` -URL-källor skrivs som `{"type":"url","url":"https://example.com/report.pdf"}`. `document` stöder även `text/plain` och `content`-källor som består av text-/image-block; valfria fält inkluderar `title`, `context` och `citations`. Files API:s `file_id`-källa tillhör en separat beta-funktion och ingår inte i detta API:s stabila kontrakt. +URL-källor skrivs som `{"type":"url","url":"https://example.com/report.pdf"}`. `document` stöder även `text/plain` och `content`-källor som består av text-/bildblock; valfria fält omfattar `title`, `context` och `citations`. Files API:s `file_id`-källa tillhör en separat beta-funktion och ingår inte i detta gränssnitts stabila kontrakt. ## Promptcache @@ -536,10 +534,9 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +När exakt positionskontroll krävs kan samma `cache_control` också skrivas på innehållsblocken text, image, document, tool_use, tool_result eller på verktygsdefinitioner. `ttl` stöder `5m` (standard) och `1h`; avgör cache-skrivning och träff genom `usage.cache_creation_input_tokens` och `usage.cache_read_input_tokens`. -När exakt kontroll över placeringen behövs kan samma `cache_control` även skrivas på innehållsblocken text, image, document, tool_use och tool_result eller på verktygsdefinitioner. `ttl` stöder `5m` (standard) och `1h`; använd `usage.cache_creation_input_tokens` och `usage.cache_read_input_tokens` för att avgöra cacheskrivning och cacheträffar. - -När svaret tillhandahåller `usage.cache_creation` gäller att `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Om `cache_creation` är `null` eller utelämnas betyder det att endast den totala mängden cacheskrivning finns tillgänglig, utan en auktoritativ TTL-uppdelning; betrakta då inte någon bucket som ett känt värde på 0, utan fakturering och totaler baseras fortfarande på aggregatfältet. +När svaret tillhandahåller `usage.cache_creation` gäller att `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Om `cache_creation` är `null` eller utelämnas, betyder det att det endast finns en total mängd cache-skrivning och ingen auktoritativ TTL-uppdelning; behandla då inte någon bucket som en känd 0, fakturering och totalmängder baseras fortfarande på aggregate-fältet. Exempel på returnerat resultat: @@ -566,7 +563,7 @@ Exempel på returnerat resultat: ## Verktygsanrop (Tool Use) -Claude Messages API har inbyggt stöd för verktygsanrop, vilket gör att modellen kan anropa dina fördefinierade verktyg/funktioner vid behov. +Claude Messages API har inbyggt stöd för verktygsanrop, vilket gör det möjligt för modellen att vid behov anropa dina fördefinierade verktyg/funktioner. ### Python-exempel @@ -640,7 +637,7 @@ När modellen beslutar att anropa ett verktyg kommer `content` i det returnerade } ``` -Observera att `stop_reason` är `tool_use`, vilket indikerar att modellen behöver anropa verktyget. När du har tagit emot resultatet behöver du köra verktygsfunktionen och skicka tillbaka resultatet till modellen i form av `tool_result`: +Observera att `stop_reason` är `tool_use`, vilket anger att modellen behöver anropa verktyget. Efter att ha tagit emot detta resultat behöver du köra verktygsfunktionen och skicka tillbaka resultatet till modellen i form av `tool_result`: ```python payload = { @@ -688,35 +685,36 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Modellen genererar ett slutligt svar på naturligt språk baserat på resultatet som verktyget returnerar. +Modellen genererar ett slutligt svar på naturligt språk baserat på resultatet som returneras av verktyget. -## Skillnader från Chat Completion API +## Skillnader jämfört med Chat Completion API -Ace Data Cloud erbjuder samtidigt två Claude API-format, med följande huvudsakliga skillnader: +Ace Data Cloud erbjuder samtidigt två Claude API-format, där de huvudsakliga skillnaderna mellan dem är följande: -Messages API:s `usage.input_tokens` representerar endast ocachad indata, medan `cache_read_input_tokens` och `cache_creation_input_tokens` är separata faktureringsbucketar; alla tre beräknas separat enligt respektive pris. -| Funktion | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +Messages API:s `usage.input_tokens` representerar endast ocachat indata, medan `cache_read_input_tokens` och `cache_creation_input_tokens` är separata faktureringsbuckets; alla tre beräknas separat enligt respektive pris. + +| Egenskap | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| Format | Anthropic-nativt format | OpenAI-kompatibelt format | -| Systemprompt | Separat fält `system` | Skickas via `role: "system"` i `messages` | -| Svarsstruktur | Arrayen `content` (stöder flera typer) | Arrayen `choices` (innehåller `message`) | -| Strömmande format | SSE-händelser (flera händelsetyper) | SSE-rader med `data` | -| Djupgående tänkande | Native `thinking` och `output_config.effort` | Modellens standardstrategi och kompatibilitetsparametrar | -| Verktygsanrop | Native `tools` + `input_schema` | OpenAI-kompatibelt `tools`-format | -| Tokenstatistik | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | +| Format | Anthropic-format i original | OpenAI-kompatibelt format | +| Systemprompt | Separat `system`-fält | Överförs via `role: "system"` i `messages` | +| Svarsstruktur | `content`-array (stöder flera typer) | `choices`-array (innehåller `message`) | +| Strömmande format | SSE-händelser (flera händelsetyper) | SSE `data`-rader | +| Djupgående tänkande | Ursprungligt `thinking` och `output_config.effort` | Modellens standardstrategi och kompatibilitetsparametrar | +| Verktygsanrop | Ursprungligt `tools` + `input_schema` | OpenAI-kompatibelt `tools`-format | +| Token-statistik | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Om ditt system redan är integrerat med ett API i OpenAI-format kan du använda Chat Completion API för att växla sömlöst. Om du behöver använda alla Claudes native funktioner rekommenderas Messages API. +Om ditt system redan är anslutet till API:et i OpenAI-format kan du använda Chat Completion API för att byta sömlöst. Om du behöver använda alla Claudes inbyggda funktioner rekommenderas Messages API. ## Felhantering -Felsvar för offentliga gränssnitt använder Ace Data Cloud-plattformens envelope: `error.code` är en stabil felkod, `error.message` är en beskrivning och `trace_id` används för att felsöka begäran. Vanliga HTTP-statusar inkluderar: +Felsvar från offentliga gränssnitt använder Ace Data Cloud-plattformens envelope: `error.code` är en stabil felkod, `error.message` är en beskrivning och `trace_id` används för att felsöka förfrågningar. Vanliga HTTP-statusar inkluderar: -- `400`: Begärandeparametrarna eller protokollinnehållet är ogiltigt. +- `400`: Förfrågningsparametrar eller protokollinnehåll är ogiltiga. - `401`: Auktoriseringstoken är ogiltig, saknas eller har gått ut. - `403`: Åtkomst förbjuden, otillräckligt saldo eller begränsad kvot. -- `404`: API:et eller modellen finns inte. -- `413`: Begärandetexten är för stor. -- `429`: För många begäranden. +- `404`: API eller modell finns inte. +- `413`: Förfrågningskroppen är för stor. +- `429`: För många förfrågningar. - `500` / `503` / `504`: Tjänstfel, tillfälligt otillgänglig eller bearbetningstimeout. ### Exempel på felsvar @@ -731,8 +729,7 @@ Felsvar för offentliga gränssnitt använder Ace Data Cloud-plattformens envelo } ``` -Denna felstruktur är Ace Data Clouds körtidskontrakt och motsvarar inte Anthropics officiella fel-envelope; hantera den enligt HTTP-status och `error.code`. +Denna felstruktur är Ace Data Clouds körtidskontrakt och är inte likvärdig med Anthropics officiella felelvelope; hantera den enligt HTTP-status och `error.code`. ## Slutsats - -Genom detta dokument har du lärt dig hur du använder Claude Messages API för att anropa Claudes konversationsfunktioner i Anthropic-nativt format. Messages API stöder omfattande funktioner såsom grundläggande konversationer, systemprompter, strömmande svar, flervägskonversationer, djupgående tänkande, visuell förståelse, PDF:er, promptcache och verktygsanrop. Om du har några frågor är du välkommen att kontakta vårt tekniska supportteam när som helst. +Genom detta dokument har du redan lärt dig hur du använder Claude Messages API för att anropa Claudes konversationsfunktioner i Anthropics ursprungliga format. Messages API stöder omfattande funktioner såsom grundläggande konversationer, systemprompter, strömmande svar, flerrundskonversationer, djupgående tänkande, visuell förståelse, PDF-filer, promptcachelagring och verktygsanrop. Om du har några frågor är du välkommen att när som helst kontakta vårt tekniska supportteam. diff --git a/uk/guides/claude/claude_messages.mdx b/uk/guides/claude/claude_messages.mdx index 570d2c91..36709a95 100644 --- a/uk/guides/claude/claude_messages.mdx +++ b/uk/guides/claude/claude_messages.mdx @@ -3,42 +3,41 @@ title: "Подання заявки та використання Claude Message description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude — це дуже потужна система AI-діалогів, яка може генерувати плавні й природні відповіді всього за кілька секунд після введення підказки. Claude Messages API — це офіційний нативний формат API Anthropic. На відміну від формату, сумісного з OpenAI (Chat Completion), він використовує власну структуру запитів і відповідей Anthropic, що дає змогу краще використовувати унікальні можливості Claude, такі як мультимодальне введення контенту, виклик інструментів, глибоке мислення (Extended Thinking) та інші розширені функції. +Anthropic Claude — це надзвичайно потужна система ШІ для діалогів, яка лише за кілька секунд може генерувати плавні та природні відповіді після введення підказки. Claude Messages API — це офіційний нативний формат API від Anthropic. На відміну від формату, сумісного з OpenAI (Chat Completion), він використовує власну структуру запитів і відповідей Anthropic, що дає змогу краще використовувати унікальні можливості Claude, як-от мультимодальне введення контенту, виклики інструментів, глибоке мислення (Extended Thinking) та інші розширені функції. -У цьому документі переважно описано процес використання операцій Claude Messages API. За його допомогою ми можемо використовувати нативний інтерфейс, узгоджений з офіційним Anthropic, для виклику функції діалогу Claude. +Цей документ переважно описує процес використання операцій Claude Messages API. За його допомогою ми можемо використовувати нативний інтерфейс, узгоджений з офіційним Anthropic, для виклику функцій діалогу Claude. ## Процес подання заявки -Щоб використовувати Claude Messages API, спочатку отримайте ваш API Token у [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) і збережіть його для подальшого використання. +Щоб використовувати Claude Messages API, спочатку отримайте свій API Token у [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) і збережіть його для подальшого використання. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Якщо ви ще не ввійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу, де буде запропоновано зареєструватися та ввійти. Після завершення ви автоматично повернетеся на поточну сторінку. +Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти. Після завершення ви автоматично повернетеся на поточну сторінку. -**Один API Token дає змогу викликати всі сервіси платформи, не потрібно подавати окрему заявку для кожного сервісу.** Під час першого подання заявки надається безкоштовний ліміт, яким можна безкоштовно скористатися; якщо ліміту недостатньо, ви можете поповнити загальний баланс у [консолі](https://platform.acedata.cloud/console/coin). +**Один API Token дає змогу викликати всі сервіси платформи, немає потреби подавати окрему заявку для кожного сервісу.** Під час першого подання заявки надається безкоштовний ліміт для безкоштовного ознайомлення; коли ліміту недостатньо, ви можете поповнити універсальний баланс у [консолі](https://platform.acedata.cloud/console/coin). > 📘 Повна документація: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Базове використання -Шлях запиту Claude Messages API — `/v1/messages`, що відповідає офіційному API Anthropic. Нам потрібно надати щонайменше три обов’язкові параметри: +Шлях запиту Claude Messages API — `/v1/messages`, що відповідає офіційному API Anthropic. Потрібно надати щонайменше три обов’язкові параметри: -- `model`: вибір моделі Claude для використання. `claude-opus-5-5` надається лише через Messages API, підтримує контекст у 1 мільйон Token, максимальний вихід 128K Token і завжди активує адаптивне мислення. Найновіша флагманська модель — `claude-fable-5-1` (контекст у 1 мільйон Token, максимальний вихід 128K Token); попередня `claude-fable-5` усе ще збережена для сумісності. `claude-sonnet-5-5` додано до нативного інтерфейсу серії Messages, вона підтримує введення зображень і адаптивне мислення; її офіційні довідкові ціни за введення, виведення та читання кешу становлять відповідно 2, 10 і 0,20 долара США за мільйон Token. -- `messages`: масив вхідних повідомлень, де кожне повідомлення містить `role` (роль) і `content` (вміст), а `role` підтримує `user` і `assistant`. +- `model`: вибір моделі Claude для використання. `claude-opus-5-5` надається лише через Messages API, підтримує контекст у 1 мільйон Token, максимальний вивід у 128K Token і завжди вмикає адаптивне мислення. Найновіший флагман — `claude-fable-5-1` (контекст у 1 мільйон Token, максимальний вивід у 128K Token); попередня `claude-fable-5` усе ще зберігається для сумісності. `claude-sonnet-5-5` додано до нативних серійних інтерфейсів Messages, він підтримує введення зображень і адаптивне мислення; його офіційні довідкові ціни на введення, виведення та читання кешу становлять відповідно 2, 10 і 0,20 долара США за мільйон Token. +- `messages`: масив вхідних повідомлень, де кожне повідомлення містить `role` (роль) і `content` (вміст), а `role` підтримує `user` та `assistant`. - `max_tokens`: максимальна кількість вихідних token, що використовується для обмеження довжини однієї відповіді. Поширені необов’язкові параметри: - `system`: системна підказка, що використовується для налаштування поведінки та ролі моделі. - `temperature`: випадковість генерації, від 0 до 1; що більше значення, то більш розгалуженою буде відповідь. -- `stream`: чи використовувати потокову відповідь; встановлення значення `true` дає змогу реалізувати ефект посимвольного повернення. -- `stop_sequences`: користувацькі послідовності зупинки; модель припиняє генерацію, коли зустрічає цей текст. -- `top_p`: параметр ядерної вибірки, що разом із temperature контролює випадковість генерації. +- `stream`: чи використовувати потокову відповідь; встановлення `true` дає змогу реалізувати ефект повернення тексту посимвольно. +- `stop_sequences`: користувацькі послідовності зупинки; модель припинить генерацію, коли зустріне цей текст. +- `top_p`: параметр ядерної вибірки, який разом із temperature контролює випадковість генерації. - `top_k`: вибірка лише з K варіантів із найвищою ймовірністю. -- `tools`: визначення інструментів, що використовуються для виклику моделлю зовнішніх функцій. +- `tools`: визначення інструментів для виклику моделлю зовнішніх функцій. - `tool_choice`: контролює, як модель використовує надані інструменти. -- `cache_control`: автоматично створює контрольну точку кешу в останньому кешованому блоці вмісту запиту; також може бути записаний у конкретному блоці вмісту. -- `metadata`: необов’язковий об’єкт метаданих запиту. `metadata.user_id` є рядком і може передавати користувацький ідентифікатор користувача від сторони, що викликає, наприклад `{"user_id":"example-user-001"}`; рекомендується використовувати стабільний ідентифікатор, що не містить персональної інформації. Він не замінює автентифікацію `Authorization` і його також не потрібно записувати у вміст діалогу `messages`. +- `cache_control`: автоматично створює точку переривання кешу на останньому кешованому блоці контенту запиту; також можна записати в конкретному блоці контенту. ### Приклад cURL @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -86,7 +83,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Після виклику результат повертається таким: +Після виклику результат повертається таким чином: ```json { @@ -109,25 +106,25 @@ print(response.json()) } ``` -Опис полів результату, що повертається: -- `id`：унікальний ідентифікатор цього повідомлення. -- `type`：завжди `message`. -- `role`：завжди `assistant`. -- `content`：масив вмісту відповіді, кожен елемент містить `type` (наприклад, `text`) і відповідний вміст. -- `model`：назва моделі, що обробляє запит. -- `stop_reason`：причина зупинки. Стабільні значення включають `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（можна повернути поточний вміст assistant без змін, щоб продовжити）、`refusal` і `model_context_window_exceeded`. -- `stop_sequence`：якщо зупинка сталася через налаштовану послідовність зупинки, відображається текст послідовності зупинки, що збіглася. -- `stop_details`：коли `stop_reason` має значення `refusal`, може містити категорію та пояснення відмови. -- `usage`：статистика використання token. `input_tokens` — некешований ввід; `cache_creation_input_tokens` і `cache_read_input_tokens` — відповідно запис і читання кешу; `output_tokens` — загальна кількість вихідних token. Якщо повертається `output_tokens_details.thinking_tokens`, це значення є підмножиною `output_tokens`, тому під час обчислення загальної кількості або вартості не додавайте його повторно. За відсутності авторитетного підрахунку ця деталізація може бути `null` або пропущена. -- `usage.cache_creation`：необов’язкові відомості про TTL запису кешу, що містять `ephemeral_5m_input_tokens` і `ephemeral_1h_input_tokens`. Якщо об’єкт існує, сума цих двох значень дорівнює `cache_creation_input_tokens`; поле зі значенням `null` або пропущене означає, що поточна відповідь не має доступного розподілу за TTL, і його не можна тлумачити як `0`. -- `usage.cost`：непотокові відповіді можуть містити об’єкт витрати квоти, записаний Ace Data Cloud, де `amount` — фактична витрата цього разу, `currency` — одиниця вимірювання, а `list_amount` — сума до знижки (за наявності). Офіційна базова ціна читання кешу для Fable 5.1 становить $0.25/млн Token, а базові ціни запису кешу на 5 хвилин і 1 годину становлять відповідно $12.50 і $20/млн Token; фактичні ціни платформи перераховуються відповідно до знижок тарифного плану. +Опис полів результату: -## Системні підказки +- `id`: унікальний ідентифікатор цього повідомлення. +- `type`: завжди `message`. +- `role`: завжди `assistant`. +- `content`: масив вмісту відповіді, де кожен елемент містить `type` (наприклад, `text`) і відповідний вміст. +- `model`: назва моделі, що обробляє запит. +- `stop_reason`: причина зупинки. Стабільні значення включають `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (можна передати поточний вміст assistant без змін, щоб продовжити), `refusal` та `model_context_window_exceeded`. +- `stop_sequence`: якщо зупинка сталася через користувацьку послідовність зупинки, відображається відповідний текст послідовності зупинки. +- `stop_details`: коли `stop_reason` має значення `refusal`, може містити категорію та пояснення відмови. +- `usage`: статистика використання token. `input_tokens` — це некешований ввід; `cache_creation_input_tokens` і `cache_read_input_tokens` — відповідно запис до кешу та читання з кешу; `output_tokens` — загальна кількість вихідних token. Якщо повертається `output_tokens_details.thinking_tokens`, це значення є підмножиною `output_tokens`, тому під час обчислення загальної кількості або вартості не додавайте його повторно. За відсутності авторитетного підрахунку ця деталізація може бути `null` або пропущена. +- `usage.cache_creation`: необов’язкова деталізація TTL запису до кешу, що містить `ephemeral_5m_input_tokens` та `ephemeral_1h_input_tokens`. Коли об’єкт існує, сума цих двох значень дорівнює `cache_creation_input_tokens`; значення поля `null` або його пропуск означає, що в поточній відповіді немає доступного розподілу TTL, і його не можна тлумачити як `0`. +- `usage.cost`: непотокова відповідь може містити об’єкт витрати ліміту, зафіксований Ace Data Cloud, де `amount` — фактичне споживання цього разу, `currency` — одиниця вимірювання, а `list_amount` — сума до знижки (за наявності). Офіційна базова ціна читання кешу Fable 5.1 становить $0.25/мільйон Token, а базові ціни запису до кешу на 5 хвилин і 1 годину становлять відповідно $12.50 та $20/мільйон Token; фактична ціна платформи розраховується відповідно до знижки тарифного плану. -Claude Messages API підтримує встановлення системних підказок через поле `system`, що використовується для визначення поведінки, ролі та контексту моделі. +## Системна підказка -### Приклад Python +Claude Messages API підтримує налаштування системної підказки через поле `system`, що використовується для визначення поведінки, ролі та контексту моделі. +### Приклад Python ```python import requests @@ -154,9 +151,9 @@ print(response.json()) Налаштувавши підказку `system`, можна точно контролювати роль і поведінку Claude. -## Потокові відповіді +## Потокова відповідь -Цей інтерфейс також підтримує потокові відповіді: встановіть параметр `stream` у значення `true`, щоб отримувати результат поступово, що особливо підходить для реалізації посимвольного відображення на вебсторінках. +Цей інтерфейс також підтримує потокові відповіді: встановіть параметр `stream` на `true`, щоб отримувати поступове повернення результату, що дуже підходить для реалізації посимвольного відображення на вебсторінках. ### Приклад Python @@ -186,16 +183,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Потокові відповіді повертаються у форматі Server-Sent Events (SSE), кожен рядок починається з `event:` і `data:`. Типи потокових подій включають: +Потокова відповідь повертається у форматі Server-Sent Events (SSE), де кожен рядок має префікс `event:` і `data:`. Типи потокових подій включають: -- `message_start`：початок повідомлення, містить базову інформацію про повідомлення та назву моделі. -- `content_block_start`：початок блоку вмісту. -- `content_block_delta`：інкрементальне оновлення блоку вмісту, містить новостворений фрагмент тексту. -- `content_block_stop`：завершення блоку вмісту. -- `message_delta`：інкрементальне оновлення на рівні повідомлення, містить `stop_reason` та остаточну інформацію `usage`. Авторитетне значення `output_tokens_details.thinking_tokens` слід зчитувати лише з останнього `message_delta.usage`, не накопичуйте його між подіями. -- `message_stop`：завершення повідомлення. +- `message_start`: початок повідомлення, містить базову інформацію про повідомлення та назву моделі. +- `content_block_start`: початок блоку вмісту. +- `content_block_delta`: інкрементне оновлення блоку вмісту, містить новостворений фрагмент тексту. +- `content_block_stop`: завершення блоку вмісту. +- `message_delta`: інкрементне оновлення на рівні повідомлення, містить `stop_reason` і остаточну інформацію `usage`. Авторитетне значення `output_tokens_details.thinking_tokens` слід зчитувати лише з останнього `message_delta.usage`, не накопичуйте його між подіями. +- `message_stop`: завершення повідомлення. -Ефект виведення такий: +Ефект виводу такий: ``` event: message_start @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Як видно, у потоковій відповіді події `content_block_delta` містять поступово згенерований текстовий вміст; об’єднавши всі `text_delta`, можна отримати повну відповідь. +Як видно, у потоковій відповіді подія `content_block_delta` містить текстовий вміст, що генерується поступово; об’єднавши всі `text_delta`, можна отримати повну відповідь. ### Приклад JavaScript @@ -256,7 +253,7 @@ while (true) { ## Багатораундовий діалог -Якщо ви хочете підключити функцію багатораундового діалогу, потрібно почергово розміщувати повідомлення з ролями `user` і `assistant` у масиві `messages`, передаючи разом із ними попередню історію діалогу. +Якщо ви хочете підключити функцію багатораундового діалогу, потрібно почергово розмістити повідомлення з ролями `user` та `assistant` у масиві `messages` і передати разом усю попередню історію діалогу. ### Приклад Python @@ -286,6 +283,7 @@ print(response.json()) ``` Результат повернення такий: + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,13 +305,13 @@ print(response.json()) } ``` -Передаючи повну історію діалогу в `messages`, Claude може надавати точні відповіді з урахуванням контексту. +Передаючи повну історію діалогу в `messages`, Claude може давати точні відповіді з урахуванням контексту. -## Моделі глибокого мислення +## Модель глибокого мислення -thinking і thinking summary у Claude — це два різні поняття: модель може виконувати внутрішнє міркування, але API не повертає необроблений ланцюжок думок. Коли потрібно показати процес міркування, API повертає оброблений підсумок. +thinking і thinking summary у Claude — це два різні поняття: модель може виконувати внутрішнє міркування, але API не повертає вихідний ланцюжок думок. Коли потрібно показати процес міркування, API повертає оброблений підсумок. -Для поточних моделей рекомендовано використовувати adaptive thinking і керувати загальними витратами на міркування через `output_config.effort`: +Для поточної моделі рекомендується використовувати adaptive thinking і керувати загальними витратами на міркування через `output_config.effort`: ```python import requests @@ -352,27 +350,26 @@ print(response.json()) "signature": "opaque-signature" } ``` - -- `display: "summarized"` повертає читабельний підсумок міркування; це не необроблений ланцюжок думок. -- `display: "omitted"` повертає `thinking: ""`, але все одно зберігає непрозорий `signature` для підтримки наступних діалогів. -- `display: "updates"` — це beta-режим Anthropic, який потребує передачі `anthropic-beta: thinking-display-updates-2026-08-18`. Офіційне визначення — приховувати основний текст міркування та показувати короткі оновлення прогресу між викликами інструментів. Платформа передає цей параметр і beta-заголовок запиту без змін та не примусово переписує його на `summarized`; фактичний вміст виводу залежить від підтримки обраної моделі. -- `thinking`, `output_config`, effort, параметри семплювання та нові поля розширень передаються без змін. Платформа не підтримує жорстко закодований за моделями перелік значень або обмеження комбінацій і не переписує автоматично режими thinking; те, чи приймаються ці параметри, визначається обраною моделлю, а помилки параметрів, що повертає модель, передаються назад клієнту. -- Значенням display за замовчуванням для Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 і Opus 4.7 є `omitted`; моделі Opus 4.6, Sonnet 4.6 і більш ранні моделі з підтримкою thinking за замовчуванням використовують `summarized`. -- Display впливає лише на вміст відповіді та затримку потокової передачі, але не вимикає міркування й не зменшує тарифікацію thinking token. +- `display: "summarized"` повертає читабельний підсумок міркувань; це не оригінальний ланцюжок думок. +- `display: "omitted"` повертає `thinking: ""`, але все одно зберігає непрозорий `signature` для підтримки подальшого діалогу. +- `display: "updates"` — це beta-режим Anthropic, потрібно передати `anthropic-beta: thinking-display-updates-2026-08-18`. Офіційне визначення: приховувати текст міркувань і показувати короткі оновлення прогресу між викликами інструментів. Платформа передає цей параметр і beta-заголовок запиту за початковими значеннями та не примусово переписує їх на `summarized`; фактичний вміст виводу залежить від підтримки вибраної моделі. +- `thinking`, `output_config`, effort, параметри семплювання та нові розширені поля передаються за початковими значеннями. Платформа не підтримує жорстко закодовані за моделями переліки значень чи обмеження комбінацій, а також не переписує автоматично режим thinking; чи приймати ці параметри, визначає вибрана модель, а помилки параметрів, повернуті моделлю, передаються клієнту. +- Значенням за замовчуванням для display у Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 та Opus 4.7 є `omitted`; Opus 4.6, Sonnet 4.6 та раніші моделі, що підтримують thinking, за замовчуванням використовують `summarized`. +- Display впливає лише на повернений вміст і затримку потокової передачі, не вимикає міркування та не зменшує тарифікацію thinking token. - Чи увімкнено thinking за замовчуванням і значення display за замовчуванням — це два незалежні питання. Opus 5 і Sonnet 5 за замовчуванням вмикають adaptive thinking; для Opus 5 пропуск `thinking` еквівалентний adaptive, а пропуск `output_config.effort` еквівалентний `high`. Opus 4.8, 4.7 і 4.6 потребують явного ввімкнення. -- Thinking і фінальний текст спільно використовують вихідний бюджет `max_tokens`. Якщо бюджет надто малий, thinking може зайняти більшу частину ліміту, через що текст буде порожнім або обрізаним; збільште `max_tokens` або використовуйте effort `low` / `medium` для контролю витрат на міркування. -- Для моделей, що дозволяють вимкнути thinking, можна передати `thinking: {"type":"disabled"}`. Нові режими, такі як `between_tools`, а також комбінації effort залежать від обраної моделі; платформа не відхиляє їх заздалегідь на основі старих правил для моделей. -- Фіксований бюджет міркування можна передати через `budget_tokens`; нові моделі зазвичай використовують `thinking.type=adaptive` і `output_config.effort`. Чи підтримується фіксований бюджет або вимкнення thinking, визначається поточними можливостями обраної моделі. -- У багатораундових діалогах і викликах інструментів слід передавати назад повний блок thinking та signature, повернуті assistant, без змін; не змінюйте та не генеруйте signature самостійно. -- Передача параметрів без змін не означає, що кожна модель підтримує всі функції. Виклики між протоколами все одно потребують перетворення, а діапазон підтримки та помилки для такого вмісту, як `redacted_thinking`, визначаються сервісом моделі, який фактично обробляє запит. +- Thinking і фінальний текст спільно використовують вихідний бюджет `max_tokens`. Якщо бюджет замалий, thinking може зайняти більшу частину ліміту, через що текст буде порожнім або обрізаним; збільште `max_tokens` або використовуйте effort `low` / `medium` для контролю вкладення в міркування. +- Для моделей, які дозволяють вимкнути thinking, можна передати `thinking: {"type":"disabled"}`. Нові режими на кшталт `between_tools` і комбінації effort залежать від вибраної моделі; платформа не відхиляє їх заздалегідь на підставі старих правил моделей. +- Фіксований бюджет міркувань можна передати через `budget_tokens`; нові моделі зазвичай використовують `thinking.type=adaptive` і `output_config.effort`. Чи підтримуються фіксований бюджет або вимкнення міркувань, залежить від поточних можливостей вибраної моделі. +- У багатораундових діалогах і під час викликів інструментів слід повертати без змін повний блок thinking і signature, повернуті assistant; не змінюйте й не генеруйте signature самостійно. +- Передавання параметрів не означає, що кожна модель підтримує всі функції. Міжпротокольні виклики все одно потребують перетворення, а діапазон підтримки та помилки для вмісту на кшталт `redacted_thinking` визначаються сервісом моделі, який фактично обробляє запит. -У потокових запитах `summarized` створює `thinking_delta`; `omitted` не створює `thinking_delta`, зберігаючи лише життєвий цикл блоку thinking і `signature_delta`. +У потокових запитах `summarized` генерує `thinking_delta`; `omitted` не генерує `thinking_delta`, зберігаючи лише життєвий цикл блоку thinking і `signature_delta`. ## Візуальні моделі -Claude підтримує мультимодальний ввід і може одночасно обробляти текст і зображення. У Messages API візуальні можливості можна використовувати, встановивши `content` у формат масиву та передавши блок вмісту зображення. +Claude підтримує мультимодальний ввід і може одночасно обробляти текст та зображення. У Messages API візуальні можливості можна використовувати, встановивши `content` у формат масиву та передавши блок вмісту зображення. -### Використання зображень із кодуванням Base64 +### Використання зображень у кодуванні Base64 ```python import base64 @@ -418,7 +415,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### Використання зображень URL +### Використання URL-зображень ```python import requests @@ -459,6 +456,7 @@ print(response.json()) ``` ### Приклад cURL + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -492,7 +490,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ ## Документи та PDF -PDF використовують блок вмісту `document`, підтримуючи два стабільні джерела: Base64 і URL. Джерело Base64 повинно використовувати `application/pdf`: +PDF використовує блок вмісту `document`, підтримуючи два стабільні джерела: Base64 і URL. Джерело Base64 повинно використовувати `application/pdf`: ```python import base64 @@ -521,11 +519,11 @@ payload = { } ``` -URL-джерело записується як `{"type":"url","url":"https://example.com/report.pdf"}`. `document` також підтримує `text/plain` і джерело `content`, що складається з блоків text/image; необов’язкові поля включають `title`, `context` і `citations`. Джерело `file_id` Files API належить до окремої beta-функції та не входить до стабільного контракту цього інтерфейсу. +Джерело URL записується як `{"type":"url","url":"https://example.com/report.pdf"}`. `document` також підтримує `text/plain` і джерело `content`, що складається з блоків text/image; необов’язкові поля включають `title`, `context` і `citations`. Джерело `file_id` Files API належить до окремої beta-функції та не входить до стабільного контракту цього інтерфейсу. -## Кешування промптів +## Кешування підказок -`cache_control` верхнього рівня автоматично розміщує точку кешування на останньому кешованому блоці: +`cache_control` верхнього рівня автоматично розміщує точку розриву кешу на останньому кешованому блоці: ```python payload = { @@ -536,12 +534,11 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` +Коли потрібно точно контролювати розташування, той самий `cache_control` також можна записати в блоках вмісту text, image, document, tool_use, tool_result або у визначенні інструменту. `ttl` підтримує `5m` (за замовчуванням) і `1h`; будь ласка, визначайте запис у кеш і влучання в кеш за допомогою `usage.cache_creation_input_tokens` та `usage.cache_read_input_tokens`. -Коли потрібен точний контроль позиції, той самий `cache_control` також можна записати в блоки вмісту text, image, document, tool_use, tool_result або у визначення інструменту. `ttl` підтримує `5m` (за замовчуванням) і `1h`; визначайте запис у кеш і влучання в кеш за допомогою `usage.cache_creation_input_tokens` та `usage.cache_read_input_tokens`. - -Коли відповідь надає `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Якщо `cache_creation` має значення `null` або пропущено, це означає, що існує лише загальний обсяг запису в кеш без авторитетного розподілу за TTL; у такому разі не вважайте жоден bucket відомим як 0, а для білінгу й загальної кількості все одно орієнтуйтеся на aggregate-поля. +Коли відповідь надає `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Якщо `cache_creation` має значення `null` або пропущено, це означає, що є лише загальний обсяг запису в кеш, без авторитетного розподілу за TTL; у такому разі не вважайте жоден bucket відомим як 0, а для тарифікації та загального обсягу все одно орієнтуйтеся на aggregate-поле. -Приклад результату повернення: +Приклад результату, що повертається: ```json { @@ -564,9 +561,9 @@ payload = { } ``` -## Виклики інструментів (Tool Use) +## Виклик інструментів (Tool Use) -Claude Messages API нативно підтримує функцію виклику інструментів, дозволяючи моделі за потреби викликати заздалегідь визначені вами інструменти/функції. +Claude Messages API нативно підтримує функцію виклику інструментів, дозволяючи моделі за потреби викликати попередньо визначені вами інструменти/функції. ### Приклад Python @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Коли модель вирішує викликати інструмент, `content` у результаті повернення міститиме блок вмісту типу `tool_use`: +Коли модель вирішує викликати інструмент, у результаті, що повертається, `content` міститиме блок вмісту типу `tool_use`: ```json { @@ -640,7 +637,7 @@ print(response.json()) } ``` -Зверніть увагу, що `stop_reason` має значення `tool_use`, що означає, що моделі потрібно викликати інструмент. Після отримання цього результату вам потрібно виконати функцію інструменту та повернути результат моделі у формі `tool_result`: +Зверніть увагу, що `stop_reason` має значення `tool_use`, що означає потребу моделі викликати інструмент. Після отримання цього результату вам потрібно виконати функцію інструменту та повернути результат моделі у формі `tool_result`: ```python payload = { @@ -688,24 +685,25 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Модель згенерує остаточну відповідь природною мовою на основі результату, поверненого інструментом. +Модель на основі результату, поверненого інструментом, згенерує остаточну відповідь природною мовою. ## Відмінності від Chat Completion API -Ace Data Cloud одночасно надає два формати Claude API, їхні основні відмінності такі: +Ace Data Cloud одночасно надає два формати Claude API, основні відмінності між ними такі: + +`usage.input_tokens` у Messages API означає лише некешований ввід, а `cache_read_input_tokens` і `cache_creation_input_tokens` є незалежними тарифікованими bucket; усі три обчислюються окремо за відповідними цінами. -`usage.input_tokens` у Messages API означає лише некешований ввід, а `cache_read_input_tokens` і `cache_creation_input_tokens` є окремими білінговими bucket-ами; усі три обчислюються окремо за відповідними цінами. | Характеристика | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Формат | Нативний формат Anthropic | OpenAI-сумісний формат | | Системний промпт | Окреме поле `system` | Передається через `role: "system"` у `messages` | | Структура відповіді | Масив `content` (підтримує кілька типів) | Масив `choices` (містить `message`) | -| Потоковий формат | SSE-події (кілька типів подій) | SSE-рядки `data` | -| Глибоке мислення | Нативні `thinking` та `output_config.effort` | Стратегія моделі за замовчуванням і сумісні параметри | +| Формат потокової передачі | SSE-події (кілька типів подій) | SSE-рядки `data` | +| Поглиблене міркування | Нативні `thinking` та `output_config.effort` | Стратегія моделі за замовчуванням і параметри сумісності | | Виклик інструментів | Нативні `tools` + `input_schema` | OpenAI-сумісний формат `tools` | | Статистика Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Якщо ваша система вже інтегрована з API формату OpenAI, ви можете використовувати Chat Completion API для безшовного переходу. Якщо вам потрібно використовувати всі нативні можливості Claude, рекомендується використовувати Messages API. +Якщо ваша система вже інтегрована з API у форматі OpenAI, ви можете використовувати Chat Completion API для безшовного переходу. Якщо вам потрібно використовувати всі нативні можливості Claude, рекомендується використовувати Messages API. ## Обробка помилок @@ -715,7 +713,7 @@ Ace Data Cloud одночасно надає два формати Claude API, - `401`: токен авторизації недійсний, відсутній або прострочений. - `403`: доступ заборонено, недостатньо балансу або обмежено квоту. - `404`: API або модель не існує. -- `413`: тіло запиту завелике. +- `413`: тіло запиту надто велике. - `429`: забагато запитів. - `500` / `503` / `504`: помилка сервісу, тимчасова недоступність або тайм-аут обробки. @@ -731,8 +729,7 @@ Ace Data Cloud одночасно надає два формати Claude API, } ``` -Ця структура помилки є контрактом часу виконання Ace Data Cloud і не є еквівалентною офіційному error envelope Anthropic; обробляйте її відповідно до HTTP-статусу та `error.code`. +Ця структура помилки є контрактом часу виконання Ace Data Cloud і не тотожна офіційному error envelope Anthropic; будь ласка, обробляйте її відповідно до HTTP-статусу та `error.code`. ## Висновок - -Завдяки цьому документу ви вже дізналися, як використовувати Claude Messages API для виклику функцій діалогу Claude у нативному форматі Anthropic. Messages API підтримує багаті можливості, такі як базовий діалог, системні промпти, потокові відповіді, багатораундові діалоги, глибоке мислення, візуальне розуміння, PDF, кешування промптів і виклик інструментів. Якщо у вас виникнуть будь-які запитання, будь ласка, звертайтеся до нашої команди технічної підтримки у будь-який час. +За допомогою цього документа ви вже дізналися, як використовувати Claude Messages API для виклику діалогових можливостей Claude у власному форматі Anthropic. Messages API підтримує такі багаті функції, як базові діалоги, системні підказки, потокові відповіді, багатораундові діалоги, глибоке мислення, візуальне розуміння, PDF, кешування підказок і виклик інструментів. Якщо у вас виникнуть будь-які запитання, будь ласка, не соромтеся звертатися до нашої команди технічної підтримки. diff --git a/zh-Hans/guides/claude/claude_messages.mdx b/zh-Hans/guides/claude/claude_messages.mdx index 38bb3833..ad047217 100644 --- a/zh-Hans/guides/claude/claude_messages.mdx +++ b/zh-Hans/guides/claude/claude_messages.mdx @@ -38,7 +38,6 @@ Claude Messages API 的请求路径为 `/v1/messages`，与 Anthropic 官方 API - `tools`：工具定义，用于让模型调用外部函数。 - `tool_choice`：控制模型如何使用提供的工具。 - `cache_control`：在请求的最后一个可缓存内容块处自动创建缓存断点；也可写在具体内容块上。 -- `metadata`：可选的请求元数据对象。`metadata.user_id` 为字符串，可传递调用方自定义的用户标识，例如 `{"user_id":"example-user-001"}`；建议使用不含个人信息的稳定标识。它不替代 `Authorization` 鉴权，也不需要写进 `messages` 对话内容。 ### cURL 示例 @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] diff --git a/zh-Hant/guides/claude/claude_messages.mdx b/zh-Hant/guides/claude/claude_messages.mdx index 353ec932..f058f3e5 100644 --- a/zh-Hant/guides/claude/claude_messages.mdx +++ b/zh-Hant/guides/claude/claude_messages.mdx @@ -24,7 +24,7 @@ Anthropic Claude 是一款非常強大的 AI 對話系統，只要輸入提示 Claude Messages API 的請求路徑為 `/v1/messages`，與 Anthropic 官方 API 保持一致。我們至少需要提供三個必填參數： - `model`：選擇使用的 Claude 模型。`claude-opus-5-5` 僅透過 Messages API 提供，支援 100 萬 Token 上下文、最大輸出 128K Token，並始終啟用自適應思考。最新旗艦為 `claude-fable-5-1`（100 萬 Token 上下文、最大輸出 128K Token）；原 `claude-fable-5` 仍相容保留。 `claude-sonnet-5-5` 已加入原生 Messages 系列介面，支援圖像輸入和自適應思考；其輸入、輸出和快取讀取官方參考價分別為每百萬 Token 2、10 和 0.20 美元。 -- `messages`：輸入的訊息陣列，每條訊息包含 `role`（角色）和 `content`（內容），其中 `role` 支援 `user` 和 `assistant`。 +- `messages`：輸入的訊息陣列，每則訊息包含 `role`（角色）和 `content`（內容），其中 `role` 支援 `user` 和 `assistant`。 - `max_tokens`：最大輸出 token 數，用於限制單次回覆的長度。 常用可選參數： @@ -38,7 +38,6 @@ Claude Messages API 的請求路徑為 `/v1/messages`，與 Anthropic 官方 API - `tools`：工具定義，用於讓模型呼叫外部函式。 - `tool_choice`：控制模型如何使用提供的工具。 - `cache_control`：在請求的最後一個可快取內容區塊處自動建立快取斷點；也可寫在具體內容區塊上。 -- `metadata`：可選的請求中繼資料物件。`metadata.user_id` 為字串，可傳遞呼叫方自訂的使用者識別，例如 `{"user_id":"example-user-001"}`；建議使用不含個人資訊的穩定識別。它不替代 `Authorization` 鑑權，也不需要寫進 `messages` 對話內容。 ### cURL 範例 @@ -50,7 +49,6 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -76,7 +74,6 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, - "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -110,24 +107,24 @@ print(response.json()) ``` 返回結果欄位說明： + - `id`：本次訊息的唯一識別碼。 - `type`：始終為 `message`。 - `role`：始終為 `assistant`。 - `content`：回覆內容陣列，每個元素包含 `type`（如 `text`）和對應的內容。 - `model`：處理請求的模型名稱。 -- `stop_reason`：停止原因。固定取值包括 `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（可將目前 assistant 內容原樣回傳以繼續）、`refusal` 和 `model_context_window_exceeded`。 +- `stop_reason`：停止原因。穩定取值包括 `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（可將目前 assistant 內容原樣回傳以繼續）、`refusal` 和 `model_context_window_exceeded`。 - `stop_sequence`：如果因自訂停止序列而停止，顯示符合的停止序列文字。 - `stop_details`：當 `stop_reason` 為 `refusal` 時，可能包含拒絕類別和說明。 -- `usage`：Token 使用統計。`input_tokens` 是未快取輸入；`cache_creation_input_tokens` 和 `cache_read_input_tokens` 分別是快取寫入與讀取；`output_tokens` 是全部輸出 Token 數。若回傳 `output_tokens_details.thinking_tokens`，該值是 `output_tokens` 的子集，計算總量或費用時不要再次相加。該明細沒有權威計數時可能為 `null` 或省略。 +- `usage`：token 使用統計。`input_tokens` 是未快取輸入；`cache_creation_input_tokens` 和 `cache_read_input_tokens` 分別是快取寫入與讀取；`output_tokens` 是全部輸出 token 數。若返回 `output_tokens_details.thinking_tokens`，該值是 `output_tokens` 的子集，計算總量或費用時不要再次相加。該明細沒有權威計數時可能為 `null` 或省略。 - `usage.cache_creation`：可選的快取寫入 TTL 明細，包含 `ephemeral_5m_input_tokens` 與 `ephemeral_1h_input_tokens`。物件存在時，兩項之和等於 `cache_creation_input_tokens`；欄位為 `null` 或省略表示目前回應沒有可用的 TTL 拆分，不能按 `0` 解讀。 -- `usage.cost`：非串流回應可能包含 Ace Data Cloud 記錄的額度消耗物件，其中 `amount` 是本次實際消耗、`currency` 是計量單位，`list_amount` 是折扣前金額（如有）。Fable 5.1 的官方快取讀取基價為 $0.25/百萬 Token，5 分鐘與 1 小時快取寫入基價分別為 $12.50 和 $20/百萬 Token；平台實際價格依方案折扣換算。 +- `usage.cost`：非串流回應可能包含 Ace Data Cloud 記錄的額度消耗物件，其中 `amount` 是本次實際消耗、`currency` 是計量單位，`list_amount` 是折扣前金額（如有）。Fable 5.1 的官方快取讀取基價為 $0.25/百萬 Token，5 分鐘與 1 小時快取寫入基價分別為 $12.50 和 $20/百萬 Token；平台實際價格按方案折扣換算。 ## 系統提示詞 Claude Messages API 支援透過 `system` 欄位設定系統提示詞，用於定義模型的行為、角色和上下文。 ### Python 範例 - ```python import requests @@ -156,7 +153,7 @@ print(response.json()) ## 串流回應 -該介面也支援串流回應，將 `stream` 參數設為 `true` 即可獲得逐步回傳的效果，非常適合在網頁中實現逐字顯示。 +該介面也支援串流回應，將 `stream` 參數設為 `true` 即可獲得逐步返回的效果，非常適合在網頁中實現逐字顯示。 ### Python 範例 @@ -186,11 +183,11 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -串流回應以 Server-Sent Events (SSE) 格式回傳，每行以 `event:` 和 `data:` 為前綴。串流事件類型包括： +串流回應以 Server-Sent Events (SSE) 格式返回，每行以 `event:` 和 `data:` 為前綴。串流事件類型包括： - `message_start`：訊息開始，包含訊息的基本資訊和模型名稱。 - `content_block_start`：內容區塊開始。 -- `content_block_delta`：內容區塊增量更新，包含新產生的文字片段。 +- `content_block_delta`：內容區塊增量更新，包含新生成的文字片段。 - `content_block_stop`：內容區塊結束。 - `message_delta`：訊息層級的增量更新，包含 `stop_reason` 和最終的 `usage` 資訊。`output_tokens_details.thinking_tokens` 的權威值只應從最後一個 `message_delta.usage` 讀取，不要跨事件累加。 - `message_stop`：訊息結束。 @@ -223,7 +220,7 @@ event: message_stop data: {"type":"message_stop"} ``` -可以看到，串流回應中 `content_block_delta` 事件包含了逐步產生的文字內容，透過拼接所有 `text_delta` 即可獲得完整回覆。 +可以看到，串流回應中 `content_block_delta` 事件包含了逐步生成的文字內容，透過拼接所有 `text_delta` 即可獲得完整回覆。 ### JavaScript 範例 @@ -256,7 +253,7 @@ while (true) { ## 多輪對話 -如果您想要串接多輪對話功能，需要在 `messages` 陣列中交替排列 `user` 和 `assistant` 角色的訊息，將先前的對話歷史一併傳入。 +如果您想要串接多輪對話功能，需要在 `messages` 陣列中交替排列 `user` 和 `assistant` 角色的訊息，將之前的對話歷史一併傳入。 ### Python 範例 @@ -286,6 +283,7 @@ print(response.json()) ``` 回傳結果如下： + ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -311,7 +309,7 @@ print(response.json()) ## 深度思考模型 -Claude 的 thinking 與 thinking summary 是兩個不同概念：模型可以進行內部推理，但 API 不會返回原始思維鏈。需要展示推理過程時，API 返回的是經過處理的摘要。 +Claude 的 thinking 與 thinking summary 是兩個不同概念：模型可以進行內部推理，但 API 不會回傳原始思維鏈。需要展示推理過程時，API 回傳的是經過處理的摘要。 目前模型建議使用 adaptive thinking，並透過 `output_config.effort` 控制整體推理投入： @@ -343,7 +341,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -回應中的 thinking 區塊形式如下： +回應中的 thinking 區塊形如： ```json { @@ -352,21 +350,20 @@ print(response.json()) "signature": "opaque-signature" } ``` - -- `display: "summarized"` 返回可讀的思考摘要；它不是原始思維鏈。 -- `display: "omitted"` 返回 `thinking: ""`，但仍保留 opaque `signature` 以支援後續對話。 -- `display: "updates"` 是 Anthropic 的 beta 模式，需攜帶 `anthropic-beta: thinking-display-updates-2026-08-18`。官方定義是隱藏推理正文、顯示工具呼叫之間的簡短進度更新。平台會依原值傳遞該參數和 beta 請求標頭，不會強制改寫為 `summarized`；實際輸出內容取決於所選模型的支援情況。 -- `thinking`、`output_config`、effort、取樣參數及新增擴充欄位會依原值傳遞。平台不維護依模型硬編碼的取值列舉、組合限制，也不會自動改寫 thinking 模式；是否接受這些參數由所選模型判斷，模型返回的參數錯誤會傳回用戶端。 +- `display: "summarized"` 回傳可讀的思考摘要；它不是原始思維鏈。 +- `display: "omitted"` 回傳 `thinking: ""`，但仍保留 opaque `signature` 以支援後續對話。 +- `display: "updates"` 是 Anthropic 的 beta 模式，需攜帶 `anthropic-beta: thinking-display-updates-2026-08-18`。官方定義是隱藏推理正文、顯示工具呼叫之間的簡短進度更新。平台按原值傳遞該參數和 beta 請求標頭，不會強制改寫為 `summarized`；實際輸出內容取決於所選模型的支援情況。 +- `thinking`、`output_config`、effort、取樣參數及新增擴充欄位按原值傳遞。平台不維護按模型硬編碼的取值列舉、組合限制，也不自動改寫 thinking 模式；是否接受這些參數由所選模型判斷，模型回傳的參數錯誤會傳回用戶端。 - Fable 5.1、Fable 5、Opus 5、Sonnet 5、Opus 4.8 和 Opus 4.7 的 display 預設值為 `omitted`；Opus 4.6、Sonnet 4.6 及更早支援 thinking 的模型預設使用 `summarized`。 -- Display 只影響返回內容和串流延遲，不會關閉推理，也不會減少 thinking token 的計費。 +- Display 只影響回傳內容和串流延遲，不關閉推理，也不減少 thinking token 的計費。 - 是否預設啟用 thinking 與 display 預設值是兩個獨立問題。Opus 5、Sonnet 5 預設啟用 adaptive thinking；對 Opus 5，省略 `thinking` 等同於 adaptive，省略 `output_config.effort` 等同於 `high`。Opus 4.8、4.7 和 4.6 需要明確啟用。 - Thinking 與最終正文共同占用 `max_tokens` 輸出預算。預算過小時，thinking 可能占用大部分額度，使正文為空或被截斷；請提高 `max_tokens`，或使用 `low` / `medium` effort 控制推理投入。 -- 對允許關閉 thinking 的模型，可傳入 `thinking: {"type":"disabled"}`。`between_tools` 等新增模式以及 effort 組合取決於所選模型；平台不會依據舊的型號規則提前拒絕。 +- 對允許關閉 thinking 的模型，可傳入 `thinking: {"type":"disabled"}`。`between_tools` 等新增模式以及 effort 組合取決於所選模型；平台不依據舊的型號規則提前拒絕。 - 固定思考預算可透過 `budget_tokens` 傳遞；新模型通常使用 `thinking.type=adaptive` 和 `output_config.effort`。是否支援固定預算或關閉思考，以所選模型的目前能力為準。 -- 多輪對話和工具呼叫時，應將 assistant 返回的完整 thinking 區塊及 signature 原樣傳回；不要修改或自行產生 signature。 -- 參數透傳不代表每個模型都支援所有功能。跨協議呼叫仍需轉換，`redacted_thinking` 等內容的支援範圍和錯誤由實際處理請求的模型服務決定。 +- 多輪對話和工具呼叫時，應將 assistant 回傳的完整 thinking 區塊及 signature 原樣傳回；不要修改或自行產生 signature。 +- 參數透傳不代表每個模型都支援所有功能。跨協定呼叫仍需轉換，`redacted_thinking` 等內容的支援範圍和錯誤由實際處理請求的模型服務決定。 -串流請求中，`summarized` 會產生 `thinking_delta`；`omitted` 不會產生 `thinking_delta`，只保留 thinking 區塊生命週期和 `signature_delta`。 +串流請求中，`summarized` 會產生 `thinking_delta`；`omitted` 不產生 `thinking_delta`，只保留 thinking 區塊生命週期和 `signature_delta`。 ## 視覺模型 @@ -459,6 +456,7 @@ print(response.json()) ``` ### cURL 範例 + ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -536,12 +534,11 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` - 需要精確控制位置時，也可把同樣的 `cache_control` 寫在 text、image、document、tool_use、tool_result 內容區塊或工具定義上。`ttl` 支援 `5m`（預設）與 `1h`；請透過 `usage.cache_creation_input_tokens` 和 `usage.cache_read_input_tokens` 判斷快取寫入與命中。 當回應提供 `usage.cache_creation` 時，`ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`。若 `cache_creation` 為 `null` 或省略，表示只有快取寫入總量、沒有權威 TTL 拆分；此時不要將任一 bucket 當作已知的 0，計費和總量仍以 aggregate 欄位為準。 -回傳結果範例： +傳回結果範例： ```json { @@ -609,7 +606,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -當模型決定呼叫工具時，回傳結果中 `content` 會包含 `tool_use` 類型的內容區塊： +當模型決定呼叫工具時，傳回結果中的 `content` 會包含 `tool_use` 類型的內容區塊： ```json { @@ -640,7 +637,7 @@ print(response.json()) } ``` -注意 `stop_reason` 為 `tool_use`，表示模型需要呼叫工具。收到該結果後，您需要執行工具函式並將結果以 `tool_result` 的形式回傳給模型： +請注意 `stop_reason` 為 `tool_use`，表示模型需要呼叫工具。收到該結果後，您需要執行工具函式並將結果以 `tool_result` 的形式傳回給模型： ```python payload = { @@ -688,17 +685,18 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -模型會基於工具回傳的結果，生成最終的自然語言回覆。 +模型會基於工具傳回的結果，生成最終的自然語言回覆。 -## 與 Chat Completion API 的區別 +## 與 Chat Completion API 的差異 -Ace Data Cloud 同時提供兩種 Claude API 格式，兩者的主要區別如下： +Ace Data Cloud 同時提供兩種 Claude API 格式，兩者的主要差異如下： Messages API 的 `usage.input_tokens` 僅表示未快取輸入，`cache_read_input_tokens` 與 `cache_creation_input_tokens` 是獨立計費分桶；三者會分別按對應價格計算。 + | 特性 | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | 格式 | Anthropic 原生格式 | OpenAI 相容格式 | -| 系統提示詞 | 獨立的 `system` 欄位 | 透過 `messages` 中的 `role: "system"` 傳遞 | +| 系統提示詞 | 獨立的 `system` 欄位 | 透過 `messages` 中 `role: "system"` 傳遞 | | 回應結構 | `content` 陣列（支援多種類型） | `choices` 陣列（包含 `message`） | | 串流格式 | SSE 事件（多種事件類型） | SSE `data` 行 | | 深度思考 | 原生 `thinking` 與 `output_config.effort` | 模型預設策略與相容參數 | @@ -715,9 +713,9 @@ Messages API 的 `usage.input_tokens` 僅表示未快取輸入，`cache_read_inp - `401`：授權權杖無效、缺失或過期。 - `403`：禁止存取、餘額不足或配額受限。 - `404`：API 或模型不存在。 -- `413`：請求本文過大。 +- `413`：請求主體過大。 - `429`：請求過多。 -- `500` / `503` / `504`：服務錯誤、暫時不可用或處理逾時。 +- `500` / `503` / `504`：服務錯誤、暫時無法使用或處理逾時。 ### 錯誤回應範例 @@ -734,5 +732,4 @@ Messages API 的 `usage.input_tokens` 僅表示未快取輸入，`cache_read_inp 該錯誤結構是 Ace Data Cloud 的執行階段契約，不等同於 Anthropic 官方錯誤 envelope；請依 HTTP 狀態與 `error.code` 處理。 ## 結論 - 透過本文檔，您已經了解如何使用 Claude Messages API 以 Anthropic 原生格式呼叫 Claude 的對話功能。Messages API 支援基本對話、系統提示詞、串流回應、多輪對話、深度思考、視覺理解、PDF、提示快取和工具呼叫等豐富功能。如有任何問題，請隨時聯絡我們的技術支援團隊。