# شرح حقول Response Body

شرح حقول جسم الاستجابة لواجهة Claude API `/v1/messages`.

## الحقول الرئيسية

| الحقل | النوع | الشرح |
|------|------|------|
| **model** | string | اسم النموذج المستخدم فعليًا، مثل `claude-opus-4-6` |
| **id** | string | المعرّف الفريد لهذه الاستجابة، مثل `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
| **type** | string | قيمة ثابتة `"message"` |
| **role** | string | قيمة ثابتة `"assistant"` |
| **content** | array | مصفوفة كتل المحتوى الناتجة عن النموذج، تتضمن النصوص واستدعاءات الأدوات وعملية التفكير وغيرها |
| **stop_reason** | string | سبب التوقف: `"end_turn"` (انتهاء طبيعي)، `"tool_use"` (يلزم تنفيذ أداة)، `"max_tokens"` (بلوغ الحد الأقصى للتوكنات) |
| **stop_sequence** | string/null | التسلسل الذي أدى إلى التوقف، عادةً `null` |
| **usage** | object | إحصائيات استهلاك التوكنات (انظر التفاصيل أدناه) |

## أنواع كتل content

| النوع | الشرح |
|------|------|
| **text** | الرد النصي للنموذج، يحتوي على حقل `text` |
| **tool_use** | طلب استدعاء أداة، يحتوي على `name` (اسم الأداة)، `input` (المعاملات)، `id` (معرّف الاستدعاء، يُستخدم لمطابقة tool_result) |
| **thinking** | محتوى التفكير الموسّع (يظهر فقط عند تفعيل وضع thinking)، يحتوي على حقل `thinking` |

## تفصيل حقل usage

| الحقل | الشرح |
|------|------|
| **input_tokens** | عدد توكنات الإدخال التي لم تصب ذاكرة التخزين المؤقت (تُحاسب بالسعر الكامل) |
| **cache_creation_input_tokens** | عدد التوكنات المُنشأة حديثًا في ذاكرة التخزين المؤقت (كتابة الذاكرة المؤقتة، تكلفتها أعلى من الإدخال العادي) |
| **cache_read_input_tokens** | عدد التوكنات المقروءة من ذاكرة التخزين المؤقت (قراءة الذاكرة المؤقتة، تكلفتها أقل بكثير من الإدخال العادي) |
| **output_tokens** | عدد توكنات مخرجات النموذج |
| **service_tier** | مستوى الخدمة، مثل `"standard"` |
| **inference_geo** | منطقة الاستدلال، مثل `"not_available"` تعني عدم توفر معلومات المنطقة |

## الحقول الفرعية لـ cache_creation

| الحقل | الشرح |
|------|------|
| **ephemeral_5m_input_tokens** | عدد توكنات إنشاء الذاكرة المؤقتة قصيرة المدى بمدة TTL تبلغ 5 دقائق |
| **ephemeral_1h_input_tokens** | عدد توكنات إنشاء الذاكرة المؤقتة طويلة المدى بمدة TTL تبلغ ساعة واحدة |

> **حول تسعير الذاكرة المؤقتة**: سعر الوحدة لـ `cache_read_input_tokens` أقل بكثير من `input_tokens`، بينما سعر الوحدة لـ `cache_creation_input_tokens` أعلى قليلًا من الإدخال العادي. لذلك، الحفاظ على معدل إصابة مرتفع لذاكرة التخزين المؤقت في المحادثات المستمرة يمكن أن يخفض التكاليف بشكل ملحوظ. يمكنك مراقبة هذه النسبة بصريًا من خلال مؤشر "معدل الإصابة" في cc-viewer.

## معاني stop_reason

- **end_turn**: أكمل النموذج الرد بشكل طبيعي
- **tool_use**: يحتاج النموذج إلى استدعاء أداة، وستتضمن content كتلة `tool_use`. يجب إضافة `tool_result` إلى messages في الطلب التالي لمتابعة المحادثة
- **max_tokens**: تم الاقتطاع بسبب بلوغ حد `max_tokens`، وقد يكون الرد غير مكتمل
