Hướng dẫn kết nối Claude API: Giao diện gốc Anthropic và cấu hình khóa
Gọi các mô hình Anthropic Claude thông qua gateway của Jizhi Era: bao gồm địa chỉ giao diện, cách xác thực, ví dụ curl, trường yêu cầu/phản hồi, SSE streaming và các mã lỗi thường gặp.
I. Tổng quan
Jizhi Era cung cấp dịch vụ trung chuyển tương thích với Anthropic Messages API (/v1/messages) dành cho các nhà phát triển. Bạn chỉ cần gửi yêu cầu đến cổng (gateway) của chúng tôi và thay thế khóa xác thực bằng khóa sk- được tạo trong "Trung tâm người dùng - Khóa API" là có thể sử dụng trực tiếp các mô hình dòng Claude mà không cần thay đổi mã nguồn hiện có.
Các mô hình hiện đang mở dựa trên bảng danh sách mô hình (ví dụ: claude-sonnet-5, claude-opus-5, claude-sonnet-4-6, claude-opus-4-8, v.v.). Bạn có thể truy vấn danh sách đầy đủ và đơn giá bất kỳ lúc nào thông qua GET /v1/models.
II. Địa chỉ giao diện
| Phương thức | Đường dẫn | Mô tả |
|---|---|---|
| POST | /v1/messages | Cổng chuyển tiếp, nội dung yêu cầu là payload của Anthropic /v1/messages |
| GET | /v1/models | Danh sách mô hình và đơn giá (không cần xác thực) |
Địa chỉ gateway: https://www.relay-api.com. Vui lòng điền đường dẫn yêu cầu theo bảng trên.
III. Phương thức xác thực
Tạo khóa trong "Trung tâm người dùng → Khóa API", định dạng sk-xxxxxxxx. Khi gọi API, hãy đính kèm khóa theo một trong các cách sau:
- Header Authorization:
Authorization: Bearer sk-khóa_của_bạn(Khuyên dùng, tương thích với hầu hết SDK) - Header x-api-key:
x-api-key: sk-khóa_của_bạn
Nếu khóa không hợp lệ, bị vô hiệu hóa hoặc không đủ số dư, hệ thống sẽ trả về mã 401 / 403. Vui lòng kiểm tra trạng thái khóa và số dư tài khoản của bạn.
IV. Bắt đầu nhanh (curl)
4.1 Trò chuyện không truyền phát (Non-streaming)
curl -X POST https://www.relay-api.com/v1/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-khóa_của_bạn" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hãy giới thiệu về bản thân bạn trong một câu"}
]
}'4.2 Sử dụng system prompt và trò chuyện đa vòng
curl -X POST https://www.relay-api.com/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: sk-khóa_của_bạn" \
-d '{
"model": "claude-opus-5",
"max_tokens": 2048,
"system": "Bạn là một kỹ sư tài liệu kỹ thuật nghiêm túc.",
"messages": [
{"role": "user", "content": "Header xác thực của Claude Messages API là gì?"},
{"role": "assistant", "content": "Sử dụng x-api-key hoặc Authorization: Bearer để mang theo khóa bí mật."},
{"role": "user", "content": "Hãy cho tôi một ví dụ khác về yêu cầu dạng stream."}
],
"metadata": {"request_id": "demo-001"}
}'metadata.request_id sẽ được ghi vào nhật ký sử dụng, giúp bạn dễ dàng đối soát trong "Trung tâm người dùng → Chi tiết sử dụng".
V. Tham số yêu cầu
| Trường | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
| model | string | Có | Slug mô hình, ví dụ: claude-sonnet-5 |
| max_tokens | int | Có | Số lượng token đầu ra tối đa, khuyến nghị 1~64000 |
| messages | array | Có | Tin nhắn trò chuyện, phần tử là {role, content}, role nhận giá trị user / assistant |
| system | string | Không | System prompt |
| temperature | number | Không | Nhiệt độ lấy mẫu, mặc định 1.0, phạm vi 0~1 |
| top_p | number | Không | Lấy mẫu nhân, mặc định 0.999 |
| stream | bool | Không | Có truyền phát (streaming) hay không, mặc định false |
| stop_sequences | array | Không | Chuỗi dừng |
| metadata.request_id | string | Không | ID yêu cầu tùy chỉnh, dùng để đối soát |
VI. Cấu trúc phản hồi
Yêu cầu không truyền phát trả về cấu trúc Anthropic Messages tiêu chuẩn:
{
"id": "msg_01ABCDEFG",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5",
"content": [
{"type": "text", "text": "Xin chào! Tôi là Claude."}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 12,
"output_tokens": 18,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0
}
}| Trường | Mô tả |
|---|---|
| id | ID duy nhất của tin nhắn |
| content[].type | Loại khối nội dung, text / thinking, v.v. |
| content[].text | Nội dung văn bản |
| stop_reason | Lý do dừng: end_turn / max_tokens / stop_sequence |
| usage.input_tokens | Số token đầu vào (căn cứ tính phí) |
| usage.output_tokens | Số token đầu ra (căn cứ tính phí) |
| usage.cache_read_input_tokens | Số token đầu vào đọc từ bộ nhớ đệm (tính phí đọc cache) |
| usage.cache_creation_input_tokens | Số token được ghi vào bộ nhớ đệm (tính phí ghi cache) |
VII. Đầu ra truyền phát (Streaming)
Sau khi thêm "stream": true vào body, máy chủ sẽ trả về theo từng phần qua SSE (Server-Sent Events), loại sự kiện giống hệt với Anthropic:
event: message_start
data: {"type": "message_start", "message": {"id": "msg_...", "model": "claude-sonnet-5"}}
event: content_block_delta
data: {"type": "content_block_delta", "delta": {"type": "text_delta", "text": "Xin chào"}}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 18}}
event: message_stop
data: {"type": "message_stop"}Client cần phân tích JSON theo dòng data:, bỏ qua dòng event: và các dòng trống; nhận được message_stop nghĩa là luồng kết thúc. Việc tính phí được máy chủ quyết định theo tổng số usage của cả yêu cầu, không phụ thuộc vào việc truyền phát.
VIII. Mã lỗi thường gặp
| Mã trạng thái HTTP | Ý nghĩa | Khuyến nghị xử lý |
|---|---|---|
| 400 | Tham số yêu cầu không hợp lệ (thiếu model/max_tokens, mô hình chưa được kích hoạt, v.v.) | Sửa nội dung yêu cầu theo thông báo phản hồi |
| 401 | Chưa cung cấp hoặc khóa API không hợp lệ | Kiểm tra header Authorization / x-api-key |
| 403 | Khóa bị vô hiệu hóa, không đủ số dư hoặc khóa không được cấp quyền cho mô hình/tuyến đường này | Nạp tiền, kiểm tra trạng thái khóa hoặc điều chỉnh phân quyền khóa |
| 404 | Mô hình được yêu cầu không tồn tại | Sử dụng GET /v1/models để xem các mô hình khả dụng |
| 429 | Yêu cầu quá thường xuyên hoặc bị giới hạn lưu lượng | Thử lại sau (exponential backoff) |
| 500 | Lỗi nội bộ máy chủ | Thử lại sau; nếu tiếp tục lỗi vui lòng liên hệ CSKH |
Cấu trúc phản hồi lỗi thống nhất là {"code": mã_trạng_thái, "message": "Mô tả lỗi", "data": null}.
IX. Sử dụng và số dư
- Mỗi lượt gọi được trừ phí theo thời gian thực dựa trên: số lượng token × đơn giá mô hình × hệ số tuyến đường. Xem đơn giá và tuyến đường tại
GET /v1/models. - Sau khi đăng nhập, hãy truy cập "Trung tâm người dùng → Sử dụng API" để xem nhật ký cuộc gọi (mô hình, token, chi phí, trạng thái).
- Nếu không đủ số dư, yêu cầu sẽ trả về mã 403, dịch vụ sẽ khôi phục ngay sau khi nạp tiền.