Văn bản
Tạo Tin nhắn
Tạo tin nhắn bằng định dạng Anthropic Messages API
Tổng quan
Endpoint này chấp nhận định dạng Anthropic Messages gốc, vì vậy các SDK của Anthropic và các công cụ được xây dựng dựa trên chúng đều hoạt động với URL cơ sở của TokenLab. Nó hoạt động với các mô hình có accepted_request_formats liệt kê anthropic_messages: các mô hình Claude và một số mô hình khác.
messages chứa các lượt hội thoại của user (người dùng) và assistant (trợ lý). Hãy đặt các hướng dẫn hệ thống vào trường system ở cấp cao nhất. max_tokens là bắt buộc. Đối với các tin nhắn kiểu OpenAI với các vai trò như system hoặc tool, hãy sử dụng Chat Completions.
URL cơ sở cho Anthropic SDK: https://api.tokenlab.sh (không có hậu tố /v1)
Tiêu đề Yêu cầu (Request Headers)
Khóa API TokenLab của bạn. Gửi x-api-key hoặc Authorization: Bearer <API_KEY>. Nếu bạn gửi cả hai với các giá trị khác nhau, TokenLab sẽ sử dụng x-api-key.
Phiên bản API Anthropic. Các SDK của Anthropic sẽ tự động gửi tiêu đề này; hãy sử dụng 2023-06-01 khi bạn gọi trực tiếp API.
Tên các tính năng beta của Anthropic, được phân tách bằng dấu phẩy. TokenLab sẽ chuyển tiếp tiêu đề này, và việc một tính năng beta có hoạt động hay không phụ thuộc vào mô hình. Nội dung tham chiếu đến file_id cần có files-api-2025-04-14.
Nội dung Yêu cầu (Request Body)
Các tham số tùy chọn được hỗ trợ, giá trị chấp nhận và giá trị mặc định phụ thuộc vào mô hình được chọn. Hãy kiểm tra chi tiết mô hình trước khi thiết lập các tùy chọn lấy mẫu (sampling), suy luận (reasoning) hoặc công cụ (tool).
ID của mô hình hỗ trợ định dạng anthropic_messages. Kiểm tra chi tiết mô hình để biết các khả năng hiện tại.
Mảng các đối tượng tin nhắn với role (user hoặc assistant) và content. Tối đa 100.000 tin nhắn.
content có thể là một chuỗi văn bản thuần túy hoặc một mảng các khối nội dung. Để gửi hình ảnh, hãy sử dụng các khối nội dung có cấu trúc thay vì đặt URL hình ảnh hoặc chuỗi Base64 trực tiếp vào văn bản thuần túy. Các khối gốc khác, chẳng hạn như tool_use, tool_result, thinking và document, được chấp nhận cho các mô hình hỗ trợ chúng.
Ví dụ về các khối nội dung:
- khối văn bản:
{ "type": "text", "text": "Mô tả hình ảnh này" } - khối hình ảnh qua URL:
{ "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } } - khối hình ảnh qua Base64:
{ "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
Số lượng token tối đa để tạo. Bắt buộc: TokenLab không thêm giá trị mặc định. Mức tối đa có thể sử dụng phụ thuộc vào mô hình; xem max_output_tokens trong chi tiết mô hình. Một giá trị lớn sẽ làm tăng số dư mà TokenLab giữ lại từ tài khoản của bạn trong khi yêu cầu đang chạy, và nếu số dư không đủ để giữ chỗ, hệ thống sẽ trả về lỗi 402.
System prompt dưới dạng chuỗi hoặc mảng các khối nội dung văn bản, tách biệt với mảng messages.
Nhiệt độ lấy mẫu (Sampling temperature). Khả năng hỗ trợ, giá trị cho phép và giá trị mặc định phụ thuộc vào mô hình được chọn; hãy bỏ qua trường này để sử dụng giá trị mặc định của mô hình.
falseTrả về phản hồi dưới dạng luồng các sự kiện do máy chủ gửi (server-sent events). Xem Streaming.
Cấu hình suy luận (thinking) gốc, ví dụ {"type":"enabled","budget_tokens":10000}. Các chế độ, ngân sách và sự kết hợp với các tham số khác được hỗ trợ phụ thuộc vào mô hình được chọn. Đối với một mô hình được biết là từ chối ngân sách thủ công, TokenLab sẽ chạy {"type":"enabled"} dưới dạng suy luận thích ứng và bỏ qua budget_tokens.
Các công cụ khả dụng cho mô hình. Khả năng hỗ trợ phụ thuộc vào mô hình được chọn.
Đối tượng lựa chọn công cụ gốc, ví dụ {"type":"auto"}. Các loại được hỗ trợ phụ thuộc vào mô hình được chọn.
Đánh dấu bộ nhớ đệm prompt (prompt-caching), ví dụ {"type":"ephemeral"}; thêm "ttl": "1h" cho bộ nhớ đệm một giờ. Ở cấp cao nhất, nó sẽ bật tính năng lưu bộ nhớ đệm tự động. Bạn cũng có thể thiết lập nó trên các khối system, tools và các khối nội dung. Khả năng hỗ trợ phụ thuộc vào mô hình; các mô hình hỗ trợ tính năng này sẽ liệt kê prompt-cache trong phần capabilities.
Tham số lấy mẫu Nucleus. Sử dụng temperature hoặc top_p, không sử dụng cả hai. Khả năng hỗ trợ phụ thuộc vào mô hình được chọn.
Chỉ lấy mẫu từ K tùy chọn hàng đầu cho mỗi token. Khả năng hỗ trợ phụ thuộc vào mô hình được chọn.
Các chuỗi dừng tùy chỉnh sẽ khiến mô hình ngừng tạo nội dung. Tối đa 8.191 mục.
Metadata của yêu cầu theo định dạng Anthropic. user_id là một định danh ẩn danh cho người dùng cuối của bạn.
Chỉ auto và standard_only có hiệu lực. TokenLab chỉ tính giá cho tầng tiêu chuẩn và bỏ qua bất kỳ giá trị nào khác.
Phản hồi (Response)
Định danh tin nhắn duy nhất.
Luôn là message.
Luôn là assistant.
Mảng các khối nội dung, chẳng hạn như text, thinking hoặc tool_use.
Mô hình đã tạo ra phản hồi.
Lý do quá trình tạo dừng lại, chẳng hạn như end_turn, max_tokens, stop_sequence hoặc tool_use. Một mô hình có thể trả về các giá trị khác, ví dụ refusal.
Chuỗi dừng đã kết thúc quá trình tạo, hoặc null.
Mức sử dụng token với input_tokens và output_tokens. Khi mô hình báo cáo các token trong bộ nhớ đệm prompt, usage cũng sẽ có cache_creation_input_tokens và cache_read_input_tokens.
Mọi phản hồi đều mang ID yêu cầu trong các tiêu đề request-id và X-Request-ID. Hãy trích dẫn ID này khi bạn liên hệ với bộ phận hỗ trợ.
Yêu cầu
curl -X POST "https://api.tokenlab.sh/v1/messages" \
-H "x-api-key: sk-your-api-key" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"system": "You are a helpful assistant.",
"messages": [
{"role": "user", "content": "Hello, Claude!"}
]
}'Phản hồi
{
"id": "msg_abc123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello! How can I help you today?"
}
],
"model": "claude-sonnet-5",
"stop_reason": "end_turn",
"usage": {
"input_tokens": 15,
"output_tokens": 10
}
}Ví dụ về Đầu vào Hình ảnh (Vision Input)
Đối với các mô hình Claude có hỗ trợ thị giác, hãy đặt hình ảnh vào bên trong messages[].content dưới dạng các khối hình ảnh có cấu trúc.
{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Vui lòng mô tả hình ảnh này."
},
{
"type": "image",
"source": {
"type": "url",
"url": "https://example.com/demo.jpg"
}
}
]
}
]
}{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Vui lòng mô tả hình ảnh này."
},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRgABAQ..."
}
}
]
}
]
}Ví dụ về Suy luận Mở rộng (Extended Thinking)
Sử dụng mô hình có khả năng reasoning. Điều chỉnh max_tokens và budget_tokens theo giới hạn của mô hình; một số mô hình cần cấu hình suy luận khác.
from anthropic import Anthropic
client = Anthropic(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh"
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=16000,
thinking={
"type": "enabled",
"budget_tokens": 10000
},
messages=[{"role": "user", "content": "Giải bài toán này..."}]
)
for block in message.content:
if block.type == "thinking":
print(f"Thinking: {block.thinking}")
elif block.type == "text":
print(f"Response: {block.text}")Streaming
Thiết lập "stream": true để nhận các sự kiện do máy chủ Anthropic gửi: message_start, content_block_start, content_block_delta, content_block_stop, message_delta và message_stop. Mức sử dụng token sẽ đến trong message_start và message_delta.
from anthropic import Anthropic
client = Anthropic(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh"
)
with client.messages.stream(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Kể cho tôi một câu chuyện"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)- Trong khi mô hình đang hoạt động, luồng có thể mang các dòng bình luận SSE như
: keep-alive. Các SDK sẽ bỏ qua chúng. - Trạng thái HTTP có thể đã là
200khi xảy ra lỗi. Một lỗi sau khi luồng đã bắt đầu sẽ đến dưới dạng sự kiệnevent: errorvới cùng nội dung lỗi như bên dưới.
Lỗi
Các lỗi sử dụng định dạng lỗi của Anthropic. request_id là ID yêu cầu của TokenLab. Một số lỗi thêm các trường như code và hint.
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
},
"request_id": "req_01JEXAMPLE"
}| Trạng thái | error.type | Nguyên nhân phổ biến |
|---|---|---|
| 400 | invalid_request_error | Thiếu hoặc sai trường, mô hình không xác định, hoặc mô hình không chấp nhận định dạng Messages |
| 401 | authentication_error | Khóa API bị thiếu hoặc không hợp lệ |
| 402 | billing_error | Số dư không đủ để thực hiện yêu cầu (error.code là insufficient_balance). Khóa API đạt giới hạn chi tiêu cũng nhận lỗi 402, với error.code là quota_exceeded và error.type là rate_limit_error |
| 403 | permission_error | Khóa API không thể sử dụng mô hình được yêu cầu, hoặc tài khoản bị tạm ngưng hoặc hạn chế |
| 409 | conflict_error | Thử lại với cùng một Idempotency-Key. Xem Thử lại an toàn với khóa idempotency |
| 413 | request_too_large | Đầu vào yêu cầu quá lớn |
| 429 | rate_limit_error | Quá nhiều yêu cầu |
| 500, 502, 503 | api_error hoặc overloaded_error | Yêu cầu không thể hoàn thành, hoặc không có lộ trình khả dụng cho nó vào lúc này. Hãy thử lại sau |
| 504 | timeout_error | Yêu cầu đã hết thời gian chờ |
Các giao diện liên quan
- Đếm token tin nhắn: ước tính các token đầu vào của một yêu cầu trước khi bạn gửi nó.
- Message Batches chạy nhiều yêu cầu Messages không đồng bộ: tạo, liệt kê, truy xuất, hủy, lấy kết quả và xóa.
Xác thực
BearerAuth Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.
Vị trí: header
Header
Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.
Giá trị hợp lệ
- "auto"
- "verified"
- "official"
Khóa tùy chọn giúp ngăn chặn việc chạy lần thứ hai cho cùng một yêu cầu. Hãy gửi một giá trị duy nhất mới, chẳng hạn như UUID, cho mỗi yêu cầu và giữ nguyên giá trị đó cho các lần thử lại sau khi hết thời gian chờ. Thử lại với cùng một khóa sẽ không chạy lại: hệ thống sẽ trả về 409 kèm idempotency_replay_unavailable, hoặc thường là idempotency_conflict khi phần thân yêu cầu bị thay đổi. Ngoại lệ: khi kết quả không phải streaming hoàn tất sau khi client ngắt kết nối, việc thử lại với cùng khóa và phần thân trong vòng 24 giờ sẽ trả về kết quả đó (tối đa 1 MB) cùng header Idempotent-Replayed: true và không tính phí lần hai. Khóa dài hơn 255 ký tự sẽ bị bỏ qua và yêu cầu đó sẽ không có bảo vệ idempotency. Xem Thử lại an toàn với khóa idempotency.
1 <= length <= 255Nội dung yêu cầu
application/json
Phản hồi
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json