واجهة Claude Messages | وثائق API

# Claude Messages

Native Claude Messages-compatible API. This endpoint uses Anthropic Messages request and response shapes, including tool calls and Anthropic SSE events.

POST https://api.apihop.ai/anthropic/v1/messages

Native Claude Messages-compatible API. This endpoint uses Anthropic Messages request and response shapes, including tool calls and Anthropic SSE events.

Claude Sonnet 4.6 (`claude-sonnet-4-6`) is supported by the upstream supplier but is not currently published on API Hop. It is not an active integration default. Before calling any model, confirm access with your own `GET https://api.apihop.ai/v1/models` response.

```text
POST https://api.apihop.ai/anthropic/v1/messages
```

## Authentication

All requests require a API Hop API Key. Anthropic SDKs, Claude Code, and compatible clients usually use `x-api-key`; plain HTTP clients may also use Bearer Token authentication.

```http
x-api-key: YOUR_APIHOP_API_KEY
anthropic-version: 2023-06-01
```

```http
Authorization: Bearer YOUR_APIHOP_API_KEY
anthropic-version: 2023-06-01
```

## Body

### `model` (string, required, Default: claude-sonnet-5-5)

Supported Claude model IDs.

- `claude-fable-5`
- `claude-fable-5-1`
- `claude-opus-4-6`
- `claude-opus-4-7`
- `claude-opus-4-8`
- `claude-opus-5`
- `claude-opus-5-5`
- `claude-sonnet-5`
- `claude-sonnet-5-5`

Use `GET https://api.apihop.ai/v1/models` for the models currently available to your API Key.

### `max_tokens` (integer, required)

Maximum number of output tokens, as a positive safe integer. This budget includes both thinking and final text output tokens. Missing, zero, negative, fractional, string, or unsafe-integer values return HTTP `400` with `invalid_request_error` before generation or billing. The model may impose a lower maximum.

For models that produce thinking, a small budget such as `128` may yield only thinking blocks before ending with `stop_reason: "max_tokens"`, without text output. Set an explicit budget for the task and the selected model, allowing room for thinking and the final answer. The values in the examples are editable allowances, not upstream defaults or model limits; larger allowances may increase output usage and cost.

### `messages` (object[], required)

Conversation messages. Each message contains `role` and `content`.

`role` supports `user` and `assistant`. `content` may be a string or an array of content blocks.

### `system` (string | object[])

System prompt. Anthropic Messages uses a top-level `system` field instead of a `system` role in `messages`.

### `stream` (boolean, Default: false)

Whether to return Anthropic SSE events.

### `temperature` (number)

Sampling temperature. Accepted values and effects vary by the selected model.

### `top_p` (number)

Nucleus sampling parameter. Acceptance does not guarantee that it changes generation behavior.

### `top_k` (integer)

Top-k sampling parameter. Support depends on the selected model.

### `stop_sequences` (string[])

Stop sequences.

Requests with nonempty stop sequences avoid model services known not to support them; if no compatible service is available, the request returns `400` before generation or billing.

### `tools` (object[])

Anthropic tool definitions. Function tools usually include `name`, `description`, and `input_schema`.

### `tool_choice` (object)

Tool selection policy, such as `{ "type": "auto" }` or `{ "type": "tool", "name": "..." }`.

### `thinking` (object)

Native Anthropic thinking configuration, subject to the selected model and provider's support. Claude 4.5 uses `{ "type": "enabled", "budget_tokens": 1024 }`; Claude Sonnet/Opus 4.6 also support adaptive thinking. Do not apply a manual budget to every model version. In tool continuations, return the complete ordered assistant content, including `thinking`, `signature`, `redacted_thinking` and `tool_use`, unchanged. Keep the thinking configuration and required `anthropic-beta` headers consistent through the tool round trip. For SSE, concatenate `signature_delta.signature` fragments for the same content block; an empty thinking summary does not mean its signature can be discarded. A provider account access rejection is an upstream failure, not evidence of an invalid signature. Recognized Bedrock account access rejections return HTTP 502 with `api_error`; ordinary client validation errors retain HTTP 400. Acceptance still requires an enabled upstream account.

### `metadata` (object)

Request metadata.

### Prompt Caching

Add `cache_control: { "type": "ephemeral" }` to a `system` or message content block. Cache usage may include `cache_creation_input_tokens`, `cache_read_input_tokens`, and supported 5-minute or 1-hour creation buckets. A 1-hour TTL also requires the corresponding `anthropic-beta` header.

## Request Examples

### Non-Streaming

```json
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself in one sentence."
    }
  ],
  "stream": false
}
```

### Streaming

```json
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Reply exactly OK."
    }
  ],
  "stream": true
}
```

## Response

Non-streaming responses keep the Anthropic Message shape.

### `id` (string)

Response ID, such as `msg_...`.

### `type` (string)

Object type, usually `message`.

### `role` (string)

Usually `assistant`.

### `model` (string)

Actual Claude model used.

### `content` (object[])

Native output content blocks, including `text`, `tool_use`, and `thinking` when used.

### `stop_reason` (string)

Stop reason, such as `end_turn`, `max_tokens`, `stop_sequence`, or `tool_use`.

### `usage` (object)

Token usage, including `input_tokens` and `output_tokens`. Cache token fields are included when present.

### Success Example

```json
{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "Hello, I am Claude and can help with writing, coding, and analysis tasks."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "output_tokens": 24
  }
}
```

## Streaming Response

When `stream: true`, the endpoint returns Anthropic SSE events. Common events include:

- `message_start`
- `content_block_start`
- `content_block_delta`
- `content_block_stop`
- `ping`
- `message_delta`
- `message_stop`

## Error Response

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for the full code reference, protocol differences, and diagnostic steps.

Error responses use the Anthropic-style shape:

```json
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid credentials or API key has expired."
  }
}
```

واجهة API أصلية متوافقة مع Claude Messages. تستخدم نقطة النهاية هذه تنسيقات طلبات Anthropic Messages واستجاباتها، بما فيها استدعاءات الأدوات وأحداث Anthropic SSE.

يدعم المزود Claude Sonnet 4.6 (claude-sonnet-4-6)، لكنه غير منشور حاليا على API Hop. وليس خيار تكامل افتراضيا نشطا. قبل استدعاء أي نموذج، أكد الوصول من خلال استجابة GET https://api.apihop.ai/v1/models الخاصة بك.

text

POST https://api.apihop.ai/anthropic/v1/messages

المصادقة

تتطلب جميع الطلبات مفتاح API من API Hop. تستخدم حزم Anthropic SDK وClaude Code والعملاء المتوافقون عادةً x-api-key؛ ويمكن لعملاء HTTP العاديين استخدام المصادقة برمز Bearer أيضًا.

http

x-api-key: YOUR_APIHOP_API_KEY
anthropic-version: 2023-06-01

http

Authorization: Bearer YOUR_APIHOP_API_KEY
anthropic-version: 2023-06-01

نص الطلب

modelstringمطلوبالقيمة الافتراضية: claude-sonnet-5-5

معرّفات نماذج Claude المدعومة.

claude-fable-5
claude-fable-5-1
claude-opus-4-6
claude-opus-4-7
claude-opus-4-8
claude-opus-5
claude-opus-5-5
claude-sonnet-5
claude-sonnet-5-5

استخدم GET https://api.apihop.ai/v1/models لمعرفة النماذج المتاحة حاليًا لمفتاح API الخاص بك.

max_tokensintegerمطلوب

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

في النماذج التي تنتج محتوى تفكير، قد تسفر ميزانية صغيرة مثل 128 عن كتل تفكير فقط قبل الانتهاء بحالة stop_reason: "max_tokens"، دون إخراج نصي. حدد ميزانية صريحة تناسب المهمة والنموذج المختار، مع إتاحة مساحة للتفكير والإجابة النهائية. القيم في الأمثلة مخصصات قابلة للتعديل، وليست القيم الافتراضية لدى المزوّد أو حدود النموذج؛ وقد تزيد المخصصات الأكبر استخدام الإخراج وتكلفته.

messagesobject[]مطلوب

رسائل المحادثة. تحتوي كل رسالة على role وcontent.

يدعم role القيمتين user وassistant. ويمكن أن يكون content سلسلة نصية أو مصفوفة من كتل المحتوى.

systemstring | object[]

تعليمة النظام. تستخدم Anthropic Messages حقل system على المستوى الأعلى بدلًا من دور system داخل messages.

streambooleanالقيمة الافتراضية: false

ما إذا كانت الاستجابة تعيد أحداث Anthropic SSE.

temperaturenumber

درجة حرارة أخذ العينات. تختلف القيم المقبولة وتأثيراتها باختلاف النموذج المختار.

top_pnumber

معامل أخذ العينات النووية. قبول المعامل لا يضمن تغييره لسلوك التوليد.

top_kinteger

معامل أخذ العينات Top-k. يعتمد دعمه على النموذج المختار.

stop_sequencesstring[]

تسلسلات الإيقاف.

تتجنب الطلبات ذات تسلسلات الإيقاف غير الفارغة خدمات النماذج المعروف أنها لا تدعمها؛ وإذا لم تتوفر خدمة متوافقة، يعيد الطلب 400 قبل التوليد أو الفوترة.

toolsobject[]

تعريفات أدوات Anthropic. تتضمن أدوات الدوال عادةً name وdescription وinput_schema.

tool_choiceobject

سياسة اختيار الأدوات، مثل { "type": "auto" } أو { "type": "tool", "name": "..." }.

thinkingobject

إعداد التفكير الأصلي في Anthropic، وفقًا لدعم النموذج والمزوّد المختارين. يستخدم Claude 4.5 الإعداد { "type": "enabled", "budget_tokens": 1024 }؛ ويدعم Claude Sonnet/Opus 4.6 التفكير التكيفي أيضًا. لا تطبق ميزانية يدوية على كل إصدار من النماذج. عند متابعة استدعاءات الأدوات، أعد محتوى المساعد كاملًا بترتيبه دون تغيير، بما فيه thinking وsignature وredacted_thinking وtool_use. حافظ على اتساق إعداد التفكير وترويسات anthropic-beta المطلوبة طوال دورة الأداة. في SSE، صِل أجزاء signature_delta.signature الخاصة بكتلة المحتوى نفسها؛ فملخص التفكير الفارغ لا يعني جواز حذف توقيعه. رفض الوصول لحساب المزوّد إخفاق لدى المزوّد، وليس دليلًا على توقيع غير صالح. تعيد حالات رفض الوصول المعروفة لحسابات Bedrock الرمز HTTP 502 مع api_error؛ بينما تحتفظ أخطاء التحقق العادية من طلب العميل بالرمز HTTP 400. ويظل القبول مشروطًا بوجود حساب مفعّل لدى المزوّد.

metadataobject

البيانات الوصفية للطلب.

التخزين المؤقت للتعليمات

أضف cache_control: { "type": "ephemeral" } إلى كتلة محتوى system أو رسالة. قد يشمل استخدام التخزين المؤقت cache_creation_input_tokens وcache_read_input_tokens وفئات الإنشاء المدعومة لمدة 5 دقائق أو 1 ساعة. وتتطلب مدة صلاحية قدرها 1 ساعة ترويسة anthropic-beta المقابلة أيضًا.

أمثلة الطلبات

دون تدفق

json

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself in one sentence."
    }
  ],
  "stream": false
}

التدفق

json

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Reply exactly OK."
    }
  ],
  "stream": true
}

الاستجابة

تحتفظ الاستجابات غير المتدفقة بتنسيق Anthropic Message.

idstring

معرّف الاستجابة، مثل msg_....

typestring

نوع الكائن، ويكون عادةً message.

rolestring

عادةً assistant.

modelstring

نموذج Claude المستخدم فعليًا.

contentobject[]

كتل محتوى الإخراج الأصلية، ومنها text وtool_use وthinking عند استخدامها.

stop_reasonstring

سبب الإيقاف، مثل end_turn أو max_tokens أو stop_sequence أو tool_use.

usageobject

استخدام الرموز، بما فيه input_tokens وoutput_tokens. تُدرج حقول رموز التخزين المؤقت عند وجودها.

مثال على النجاح

json

{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "Hello, I am Claude and can help with writing, coding, and analysis tasks."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "output_tokens": 24
  }
}

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

عند ضبط stream: true، تعيد نقطة النهاية أحداث Anthropic SSE. تشمل الأحداث الشائعة:

message_start
content_block_start
content_block_delta
content_block_stop
ping
message_delta
message_stop

استجابة الخطأ

راجع رموز الأخطاء واستكشاف المشكلات للاطلاع على مرجع الرموز الكامل والفروق بين البروتوكولات وخطوات التشخيص.

تستخدم استجابات الأخطاء تنسيق Anthropic:

json

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid credentials or API key has expired."
  }
}