TokenLab

Văn bản

Tạo Chat Completion

Tạo completion cho tin nhắn chat

POST
/v1/chat/completions

Phần thân yêu cầu (Request Body)

Các tham số tùy chọn được hỗ trợ, các giá trị được chấp nhận và giá trị mặc định phụ thuộc vào model được chọn. Hãy kiểm tra chi tiết model trước khi thiết lập các tùy chọn sampling, reasoning hoặc tool. Một tùy chọn điều khiển mà model không thể đáp ứng, chẳng hạn như n lớn hơn 1 trên một số model, sẽ bị từ chối với lỗi 4xx. Thay vào đó, các tùy chọn điều khiển sampling phụ như seed hoặc các penalty có thể bị bỏ qua.

modelstringbắt buộc

ID của model cần sử dụng. Xem Models để biết các tùy chọn khả dụng.

messagesarraybắt buộc

Danh sách các tin nhắn tạo nên cuộc hội thoại.

Mỗi object tin nhắn bao gồm:

  • role (string): system, developer, user, assistant, tool, function
  • content (string | array | null): Nội dung tin nhắn

Đối với tin nhắn assistant có chứa tool_calls, content có thể được bỏ qua hoặc đặt thành null.

Khi content là một mảng, TokenLab hỗ trợ các khối multimodal có cấu trúc cho các model tương thích:

  • text: { "type": "text", "text": "..." }
  • image: { "type": "image_url", "image_url": { "url": "https://..." } }
  • video: { "type": "video_url", "video_url": { "url": "https://..." } }
  • audio: { "type": "input_audio", "input_audio": { "data": "https://... or base64 data URL", "format": "wav" } }, hoặc { "type": "audio_url", "audio_url": { "url": "https://..." } }

Đối với đầu vào multimodal, hãy sử dụng các URL https có thể truy cập công khai. Hình ảnh cũng có thể được gửi dưới dạng data URL base64. Các loại media được hỗ trợ phụ thuộc vào model được chọn.

temperaturenumber

Nhiệt độ sampling (sampling temperature). Khả năng hỗ trợ, các giá trị được phép và giá trị mặc định phụ thuộc vào model được chọn; bỏ qua trường này để sử dụng giá trị mặc định của model.

max_tokensinteger

Số lượng token tối đa cần tạo. Chỉ gửi một trong hai trường max_tokens hoặc max_completion_tokens, không gửi cả hai: model được phục vụ qua giao thức khác có thể từ chối request có cả hai trường này.

Đối với model có khả năng suy nghĩ (thinking), các token suy nghĩ được tính vào giới hạn này. Nếu giới hạn quá nhỏ, toàn bộ ngân sách token có thể bị dùng hết cho việc suy nghĩ và để lại phần thân tin nhắn trống, đồng thời các token đã sử dụng vẫn bị tính phí. Hãy tăng giới hạn hoặc tắt tính năng suy nghĩ nếu model cho phép, ví dụ với "reasoning_effort": "none". Trên deepseek-v4.1-flash (alias deepseek-flash), "thinking": {"type": "disabled"} cũng sẽ tắt tính năng này.

Trước khi request được thực thi, TokenLab sẽ kiểm tra xem số dư của bạn có đủ để chi trả cho mức tối đa này hay không. Một giá trị quá lớn có thể trả về lỗi 402 khi số dư thấp ngay cả khi câu trả lời ngắn.

streambooleanmặc định: false

Nếu là true, các delta tin nhắn từng phần sẽ được gửi dưới dạng server-sent events (SSE). Xem Streaming.

Đối với đầu ra dài (hàng nghìn token trở lên), hãy đặt stream: true để client và proxy không bị time out trong khi chờ toàn bộ response.

stream_optionsobject

Các tùy chọn cho streaming. Đặt include_usage: true để nhận thêm một chunk chứa thông tin sử dụng token trước data: [DONE]. Nếu không có tùy chọn này, stream sẽ không mang thông tin sử dụng.

top_pnumber

Tham số nucleus sampling. Chúng tôi khuyên bạn chỉ nên thay đổi tham số này hoặc temperature, không nên thay đổi cả hai.

frequency_penaltynumber

Số trong khoảng từ -2.0 đến 2.0. Các giá trị dương sẽ phạt các token lặp lại.

presence_penaltynumber

Số trong khoảng từ -2.0 đến 2.0. Các giá trị dương sẽ phạt các token đã xuất hiện trong văn bản.

stopstring | array

Stop sequence hoặc danh sách các stop sequence. Khả năng hỗ trợ và giới hạn sequence phụ thuộc vào model được chọn.

toolsarray

Danh sách các tool mà model có thể gọi (function calling). Mỗi tool có dạng { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }. Xem Output có cấu trúc và tool calling.

tool_choicestring | object

Kiểm soát cách model sử dụng tool. Các tùy chọn: auto, none, required, hoặc { "type": "function", "function": { "name": "..." } } để bắt buộc dùng một tool cụ thể.

parallel_tool_callsboolean

Cho phép nhiều lệnh gọi tool trong một lượt của assistant, khi được hỗ trợ bởi model đã chọn.

max_completion_tokensinteger

Giới hạn trên cho completion, bao gồm cả các token suy nghĩ. Là giải pháp thay thế cho max_tokens được sử dụng bởi các dòng model OpenAI mới hơn. Chỉ gửi một trong hai tham số.

reasoning_effortstring

Mức độ suy luận (reasoning effort) cho các model hỗ trợ tính năng này. Các giá trị được chấp nhận phụ thuộc vào model được chọn.

Đối với các model Claude, giá trị này thiết lập cơ chế suy nghĩ của model: mức effort trên các model có adaptive thinking, hoặc ngân sách suy nghĩ (thinking budget) trên các model sử dụng ngân sách này. none sẽ tắt tính năng suy nghĩ trên các model cho phép. Giá trị mà model không hỗ trợ sẽ bị từ chối với lỗi 400, mã invalid_value, và thông báo lỗi sẽ liệt kê các giá trị được hỗ trợ. Trong khi tính năng suy nghĩ đang bật, Claude từ chối temperature khác 1, top_k, top_p nằm ngoài khoảng 0.95–1 và tin nhắn assistant được điền sẵn (prefilled). Việc bắt buộc tool_choice hoạt động được với adaptive thinking nhưng không hoạt động với thinking budget.

anthropic_optionsobject

Các tùy chọn cho các model Claude.

  • prompt_caching (boolean): Đặt thành true để lưu cache phần đầu của prompt. TokenLab đánh dấu phần cuối của system prompt và tin nhắn user mới nhất làm các điểm cache. Một request sau đó bắt đầu bằng nội dung tương tự sẽ đọc nội dung đó từ cache. Chỉ sử dụng tùy chọn này hoặc các đánh dấu cache_control của riêng bạn, không sử dụng cả hai.
  • prompt_caching_ttl (string): 5m (mặc định) hoặc 1h. Khi dịch vụ xử lý request không thể giữ cache trong một giờ, TokenLab có thể sử dụng cache năm phút thay vì từ chối request.

extra.prompt_caching và extra.prompt_caching_ttl cũng được chấp nhận là các tùy chọn tương đương. Xem Prompt caching để biết mức giá và cách kiểm tra các token đã được lưu vào cache.

seedinteger

Seed sampling cho các model hỗ trợ. Không đảm bảo output sẽ hoàn toàn giống nhau.

ninteger

Số lượng completion cần tạo. Các model hỗ trợ sẽ chấp nhận từ 1-128. Nhiều model chỉ hỗ trợ 1.

logprobsboolean

Có trả về xác suất log (log probabilities) hay không.

top_logprobsinteger

Số lượng xác suất log hàng đầu cần trả về (0-20). Yêu cầu logprobs: true.

top_kinteger

Top-K sampling cho các model có hỗ trợ.

response_formatobject

Định dạng response. Sử dụng {"type": "text"} (mặc định), {"type": "json_object"} cho chế độ JSON, hoặc {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} cho JSON schema. Khả năng hỗ trợ phụ thuộc vào model được chọn. Xem Output có cấu trúc và tool calling.

logit_biasobject

Điều chỉnh khả năng xuất hiện của các token được chỉ định. Ánh xạ các token ID (dưới dạng chuỗi) tới các giá trị bias từ -100 đến 100. Khả năng hỗ trợ phụ thuộc vào model được chọn.

service_tierstring

TokenLab phục vụ và tính phí các request Chat ở service tier tiêu chuẩn. auto và default được chấp nhận. Các giá trị khác, chẳng hạn như flex hoặc priority, sẽ bị xóa khỏi request và request sẽ được tính phí theo mức giá tiêu chuẩn.

userstring

Định danh duy nhất đại diện cho người dùng cuối của bạn để giám sát hành vi lạm dụng.

Phản hồi

idstring

Định danh duy nhất cho completion.

objectstring

Luôn là chat.completion.

createdinteger

Unix timestamp thời điểm completion được tạo.

modelstring

Model được sử dụng cho completion.

choicesarray

Danh sách các lựa chọn completion.

Mỗi lựa chọn bao gồm:

  • index (integer): Index của lựa chọn
  • message (object): Tin nhắn được tạo
  • finish_reason (string): Lý do model dừng lại, ví dụ stop, length, tool_calls hoặc content_filter

Khi model suy nghĩ, message cũng có thể chứa:

  • reasoning_content (string): Nội dung văn bản suy nghĩ. Một số model chỉ trả về bản tóm tắt hoặc không có nội dung văn bản.
  • reasoning_details (array): Các khối suy nghĩ kèm theo chữ ký của chúng. Để tiếp tục cuộc hội thoại có chứa suy nghĩ, ví dụ sau một lệnh gọi tool, hãy gửi lại chúng mà không thay đổi gì trong tin nhắn assistant.

Trong một stream, các trường tương tự sẽ xuất hiện dưới dạng delta.reasoning_content và delta.reasoning_details.

usageobject

Thống kê mức sử dụng token.

  • prompt_tokens (integer): Số token trong prompt
  • completion_tokens (integer): Số token trong completion, bao gồm cả token suy nghĩ
  • total_tokens (integer): Tổng số token đã sử dụng
  • prompt_tokens_details.cached_tokens (integer): Số token prompt được đọc từ cache
  • cache_creation_input_tokens (integer): Số token prompt được ghi vào cache. Chỉ xuất hiện khi giá trị lớn hơn 0
  • completion_tokens_details.reasoning_tokens (integer): Số token suy nghĩ, khi model có báo cáo

Trong một stream, thông tin usage chỉ được gửi khi stream_options.include_usage là true.

Yêu cầu

curl -X POST "https://api.tokenlab.sh/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000
  }'

Ví dụ Multimodal

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this video briefly." },
        { "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
      ]
    }
  ],
  "max_tokens": 64
}

Phản hồi

Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

Streaming

Với stream: true, response sẽ là một text/event-stream. Mỗi event có dạng data: {...} với một object chat.completion.chunk mà choices[].delta của nó chứa văn bản mới, các đối số gọi tool hoặc văn bản suy nghĩ. Stream kết thúc với data: [DONE]. Các dòng bắt đầu bằng dấu : là các comment keep-alive: hãy bỏ qua chúng. Một stream kết thúc mà không có [DONE] hoặc không có finish_reason là chưa hoàn thành. Xem Streaming.

Lỗi

Lỗi sử dụng object error theo phong cách OpenAI. Các trường hợp phổ biến: 400 cho trường không hợp lệ hoặc giá trị mà model không chấp nhận, 401 cho key không hợp lệ, 402 cho số dư không đủ, 413 cho đầu vào vượt quá giới hạn kích thước và 429 cho giới hạn tốc độ (rate limit). Xem Xử lý lỗi API.

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