TokenLab

Văn bản

Tạo Tin nhắn

Tạo tin nhắn bằng định dạng Anthropic Messages API

POST
/v1/messages

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)

x-api-keystringheader

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.

anthropic-versionstringheader

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.

anthropic-betastringheader

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).

modelstringbắt buộc

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.

messagesarraybắt buộc

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..." } }
max_tokensintegerbắt buộc

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.

systemstring | array

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.

temperaturenumber

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.

streambooleanmặc định: false

Trả 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.

thinkingobject

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.

toolsarray

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.

tool_choiceobject

Đố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.

cache_controlobject

Đá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.

top_pnumber

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.

top_kinteger

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.

stop_sequencesarray

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.

metadataobject

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.

service_tierstring

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)

idstring

Định danh tin nhắn duy nhất.

typestring

Luôn là message.

rolestring

Luôn là assistant.

contentarray

Mảng các khối nội dung, chẳng hạn như text, thinking hoặc tool_use.

modelstring

Mô hình đã tạo ra phản hồi.

stop_reasonstring

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.

stop_sequencestring | null

Chuỗi dừng đã kết thúc quá trình tạo, hoặc null.

usageobject

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

Response
{
  "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à 200 khi xảy ra lỗi. Một lỗi sau khi luồng đã bắt đầu sẽ đến dưới dạng sự kiện event: error vớ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áierror.typeNguyên nhân phổ biến
400invalid_request_errorThiế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
401authentication_errorKhóa API bị thiếu hoặc không hợp lệ
402billing_errorSố 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
403permission_errorKhó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ế
409conflict_errorThử lại với cùng một Idempotency-Key. Xem Thử lại an toàn với khóa idempotency
413request_too_largeĐầu vào yêu cầu quá lớn
429rate_limit_errorQuá nhiều yêu cầu
500, 502, 503api_error hoặc overloaded_errorYê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
504timeout_errorYêu cầu đã hết thời gian chờ

Các giao diện liên quan

Xác thực

BearerAuth
AuthorizationBearer <token>

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

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Độ dài1 <= length <= 255

Nộ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