API Claude Messages | Tài liệu 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 tương thích Claude Messages nguyên bản. Điểm cuối dùng cấu trúc yêu cầu và phản hồi Anthropic Messages, gồm lời gọi công cụ và sự kiện Anthropic SSE.

Claude Sonnet 4.6 (claude-sonnet-4-6) được nhà cung cấp thượng nguồn hỗ trợ nhưng hiện chưa công bố trên API Hop. Đây không phải lựa chọn tích hợp mặc định đang hoạt động. Trước khi gọi bất kỳ mô hình nào, xác nhận quyền truy cập bằng phản hồi GET https://api.apihop.ai/v1/models của chính bạn.

text

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

Xác thực

Mọi yêu cầu cần khóa API API Hop. SDK Anthropic, Claude Code và máy khách tương thích thường dùng x-api-key; máy khách HTTP thông thường cũng có thể dùng xác thực Bearer Token.

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

Thân yêu cầu

modelstringbắt buộcMặc định: claude-sonnet-5-5

ID mô hình Claude được hỗ trợ.

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

Dùng GET https://api.apihop.ai/v1/models để biết mô hình hiện khả dụng với khóa API của bạn.

max_tokensintegerbắt buộc

Số token đầu ra tối đa, là số nguyên dương an toàn. Ngân sách này gồm token đầu ra suy nghĩ và văn bản cuối cùng. Giá trị thiếu, bằng không, âm, phân số, chuỗi hoặc số nguyên không an toàn trả HTTP 400 với invalid_request_error trước khi tạo nội dung hoặc tính phí. Mô hình có thể áp dụng mức tối đa thấp hơn.

Với mô hình tạo suy nghĩ, ngân sách nhỏ như 128 có thể chỉ tạo khối suy nghĩ trước khi kết thúc bằng stop_reason: "max_tokens", không có văn bản đầu ra. Đặt ngân sách rõ ràng cho tác vụ và mô hình được chọn, chừa chỗ cho suy nghĩ và câu trả lời cuối cùng. Giá trị trong ví dụ là hạn mức có thể chỉnh sửa, không phải mặc định thượng nguồn hay giới hạn mô hình; hạn mức lớn hơn có thể tăng lượng đầu ra và chi phí.

messagesobject[]bắt buộc

Tin nhắn hội thoại. Mỗi tin nhắn chứa role và content.

role hỗ trợ user và assistant. content có thể là chuỗi hoặc mảng khối nội dung.

systemstring | object[]

Prompt hệ thống. Anthropic Messages dùng trường system cấp cao nhất thay cho vai trò system trong messages.

streambooleanMặc định: false

Có trả sự kiện Anthropic SSE hay không.

temperaturenumber

Nhiệt độ lấy mẫu. Giá trị được chấp nhận và tác dụng thay đổi theo mô hình được chọn.

top_pnumber

Tham số lấy mẫu nucleus. Việc chấp nhận không bảo đảm thay đổi hành vi tạo nội dung.

top_kinteger

Tham số lấy mẫu top-k. Hỗ trợ phụ thuộc mô hình được chọn.

stop_sequencesstring[]

Chuỗi dừng.

Yêu cầu có chuỗi dừng không rỗng tránh dịch vụ mô hình đã biết là không hỗ trợ chúng; nếu không có dịch vụ tương thích, yêu cầu trả 400 trước khi tạo nội dung hoặc tính phí.

toolsobject[]

Định nghĩa công cụ Anthropic. Công cụ hàm thường gồm name, description và input_schema.

tool_choiceobject

Chính sách chọn công cụ, như { "type": "auto" } hoặc { "type": "tool", "name": "..." }.

thinkingobject

Cấu hình suy nghĩ Anthropic nguyên bản, tùy hỗ trợ của mô hình và nhà cung cấp được chọn. Claude 4.5 dùng { "type": "enabled", "budget_tokens": 1024 }; Claude Sonnet/Opus 4.6 cũng hỗ trợ suy nghĩ thích ứng. Không áp dụng ngân sách thủ công cho mọi phiên bản mô hình. Khi tiếp tục sau công cụ, trả nguyên vẹn toàn bộ nội dung trợ lý đúng thứ tự, gồm thinking, signature, redacted_thinking và tool_use. Giữ nhất quán cấu hình suy nghĩ và tiêu đề anthropic-beta cần thiết trong suốt vòng gọi công cụ. Với SSE, nối các mảnh signature_delta.signature của cùng khối nội dung; tóm tắt suy nghĩ rỗng không có nghĩa được bỏ chữ ký. Từ chối truy cập tài khoản nhà cung cấp là lỗi thượng nguồn, không phải bằng chứng chữ ký không hợp lệ. Từ chối truy cập tài khoản Bedrock được nhận diện trả HTTP 502 với api_error; lỗi xác thực dữ liệu máy khách thông thường giữ HTTP 400. Nghiệm thu vẫn cần tài khoản thượng nguồn đã bật.

metadataobject

Siêu dữ liệu yêu cầu.

Lưu đệm prompt

Thêm cache_control: { "type": "ephemeral" } vào khối system hoặc nội dung tin nhắn. Thống kê lưu đệm có thể gồm cache_creation_input_tokens, cache_read_input_tokens và nhóm tạo được hỗ trợ trong 5 phút hoặc 1 giờ. TTL 1 giờ cũng yêu cầu tiêu đề anthropic-beta tương ứng.

Ví dụ yêu cầu

Không truyền luồng

json

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

Truyền luồng

json

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

Phản hồi

Phản hồi không truyền luồng giữ cấu trúc Anthropic Message.

idstring

ID phản hồi, như msg_....

typestring

Loại đối tượng, thường là message.

rolestring

Thường là assistant.

modelstring

Mô hình Claude thực tế được dùng.

contentobject[]

Khối nội dung đầu ra nguyên bản, gồm text, tool_use và thinking khi được dùng.

stop_reasonstring

Lý do dừng, như end_turn, max_tokens, stop_sequence hoặc tool_use.

usageobject

Lượng token sử dụng, gồm input_tokens và output_tokens. Trường token lưu đệm được đưa vào khi có.

Ví dụ thành công

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
  }
}

Phản hồi truyền luồng

Khi stream: true, điểm cuối trả sự kiện Anthropic SSE. Sự kiện phổ biến gồm:

message_start
content_block_start
content_block_delta
content_block_stop
ping
message_delta
message_stop

Phản hồi lỗi

Xem Mã lỗi và khắc phục để có tham chiếu mã đầy đủ, khác biệt giao thức và bước chẩn đoán.

Phản hồi lỗi dùng cấu trúc kiểu Anthropic:

json

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