I. Tổng quan
Jizhi API cung cấp khả năng truy cập chuyển tiếp tương thích với Anthropic Messages API (/v1/messages) cho các nhà phát triển. Bạn chỉ cần gửi yêu cầu tới 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 - API Key" để sử dụng trực tiếp các mô hình thuộc dòng Claude mà không cần thay đổi mã nguồn hiện có.
Các mô hình đang mở dựa trên bảng mô hình (ví dụ: claude-sonnet-5, claude-opus-5, claude-sonnet-4-6, claude-opus-4-8, v.v.), danh sách đầy đủ và đơn giá có thể được truy vấn bất cứ lúc nào qua GET /v1/models.
II. Địa chỉ giao diện (API Endpoint)
| 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 /v1/messages của Anthropic |
| 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 đúng như bảng trên.
III. Phương thức xác thực
Tạo khóa tại "Trung tâm người dùng → API Key", định dạng sk-xxxxxxxx. Khi gọi API, bạn có thể truyền qua một trong hai 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 các 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.
IV. Bắt đầu nhanh (curl)
4.1 Hội thoại không truyền tải (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 Hội thoại có system prompt và đa lượt
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 để truyền khóa."},
{"role": "user", "content": "Hãy đưa ra một ví dụ về yêu cầu streaming."}
],
"metadata": {"request_id": "demo-001"}
}'metadata.request_id sẽ được ghi vào nhật ký sử dụng, giúp đố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 | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| model | string | Có | Mô hình slug, 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 hội thoại, phần tử là {role, content}, role nhận giá trị user / assistant |
| system | string | Không | System prompt |
| temperature | number | Không | Độ nhiễu (sampling temperature), mặc định 1.0, phạm vi 0~1 |
| top_p | number | Không | Lấy mẫu hạt nhân (top_p), mặc định 0.999 |
| stream | bool | Không | Có trả về theo kiểu stream 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 để đối soát |
VI. Cấu trúc phản hồi
Yêu cầu không stream trả về cấu trúc Anthropic Messages 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 tin nhắn duy nhất |
| 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ố lượng token đầu vào (căn cứ tính phí) |
| usage.output_tokens | Số lượng token đầu ra (căn cứ tính phí) |
| usage.cache_read_input_tokens | Số token đầu vào đọc từ bộ nhớ đệm |
| usage.cache_creation_input_tokens | Số token được ghi vào bộ nhớ đệm |
VII. Đầu ra luồng (Streaming)
Sau khi thêm "stream": true vào body, máy chủ sẽ trả về từng phần qua SSE (Server-Sent Events), các loại sự kiện giống 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à dòng trống; khi nhận được message_stop có nghĩa là luồng đã kết thúc. Việc tính phí dựa trên usage tổng của toàn bộ yêu cầu tại máy chủ, không liên quan đến việc có stream hay không.
VIII. Các mã lỗi thường gặp
| Mã trạng thái HTTP | Ý nghĩa | Đề xuất 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 body yêu cầu theo message phản hồi |
| 401 | Thiếu hoặc API Key không hợp lệ | Kiểm tra header Authorization / x-api-key |
| 403 | Khóa đã bị vô hiệu hóa, hết số dư hoặc không được cấp quyền dùng mô hình này | Nạp tiền, kiểm tra trạng thái khóa hoặc điều chỉnh quyền hạn khóa |
| 404 | Mô hình được yêu cầu không tồn tại | Xem các mô hình khả dụng qua GET /v1/models |
| 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 hệ thống nội bộ | Thử lại sau; nếu lỗi kéo dài hãy liên hệ CSKH |
Body phản hồi lỗi có cấu trúc chung: {"code": mã_lỗi, "message": "mô_tả_lỗi", "data": null}.
IX. Sử dụng và số dư
- Mỗi lần gọi sẽ được trừ phí thời gian thực dựa trên [số lượng token] × [đơn giá mô hình] × [hệ số tuyến đường], đơn giá và tuyến đường xem tại
GET /v1/models. - Sau khi đăng nhập, kiểm tra lịch sử gọi (mô hình, token, phí, trạng thái) trong "Trung tâm người dùng → API Usage".
- Khi số dư không đủ, yêu cầu sẽ trả về 403, sẽ khôi phục ngay lập tức sau khi nạp tiền.
Giải thích Base URL: Hệ thống chúng tôi chấp nhận cả /v1beta/models/... và /v1beta/v1beta/models/... (cũng như /v1/... và /v1/v1/...), vì vậy client có tự điền /v1 hay /v1beta hay không cũng không ảnh hưởng: Base URL điền tên miền gốc hoặc địa chỉ kèm /v1beta đều dùng được. ID mô hình vui lòng tra cứu và sao chép tại "ID Mô hình" ở góc trên bên phải trang "Token" trong bảng điều khiển.