API Claude Messages — Tài liệu TokSpan

Endpoint

http
POST https://api.tokspan.com/v1/messages

Ví Dụ Nhanh

Sử dụng Anthropic SDK với TokSpan làm base URL — không cần thay đổi code ngoài cấu hình:

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-key",
    base_url="https://api.tokspan.com",  # ← host root; the SDK appends /v1/messages
)

response = client.messages.create(
    model="MODEL_NAME",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response.content[0].text)

shell
curl -X POST "https://api.tokspan.com/v1/messages" \
  -H "x-api-key: sk-your-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

json — Response
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [{
    "type": "text",
    "text": "Hello! How can I help you today?"
  }],
  "model": "MODEL_NAME",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12
  }
}

Nội Dung Yêu Cầu

Tham Số	Kiểu	Bắt Buộc	Mô Tả
model	string	Có	ID mô hình Claude (ví dụ: `claude-opus-4-8`, `claude-sonnet-4-6`).
max_tokens	integer	Có	Số token tối đa để tạo. <strong>Bắt buộc</strong> đối với API Messages.
messages	array	Có	Mảng các message xen kẽ giữa vai trò <code>user</code> và <code>assistant</code>. Message đầu tiên phải từ người dùng.
system	string	Không	System prompt — một chuỗi hoặc mảng các content blocks.
temperature	number	Không	Nhiệt độ lấy mẫu (0–1).
stream	boolean	Không	Bật streaming SSE. Mặc định: <code>false</code>.
top_p	number	Không	Nucleus sampling (0–1).
tools	array	Không	Định nghĩa tool cho việc sử dụng tool. Xem Gọi Công Cụ.
tool_choice	object	Không	Kiểm soát lựa chọn tool: `{"type": "auto"}` hoặc một tool cụ thể.
thinking	object	Không	Cấu hình extended thinking: `{"type": "enabled", "budget_tokens": 1024}`. Budget phải ≥1024 và nhỏ hơn `max_tokens`.

Lời Nhắc Hệ Thống

Truyền system prompt dưới dạng trường <code>system</code> cấp cao nhất (không phải một message):

json
{
  "model": "MODEL_NAME",
  "max_tokens": 1024,
  "system": "You are a helpful assistant that always answers in French.",
  "messages": [{"role": "user", "content": "What is the capital of France?"}]
}

Phản Hồi Streaming (SSE)

Đặt stream: true để nhận các sự kiện SSE của Anthropic (message_start, content_block_delta, message_stop, v.v.).

shell
curl -X POST "https://api.tokspan.com/v1/messages" \
  -H "x-api-key: sk-your-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Tell me a story."}],
    "stream": true
  }'

Cấu hình: Đặt base_url của Anthropic SDK thành https://api.tokspan.com — SDK tự thêm /v1/messages. Xác thực chấp nhận cả header x-api-key + anthropic-version (gốc Anthropic) và Authorization: Bearer. Anthropic SDK xử lý việc này tự động.