Chat Completions

Endpoint

POST https://api.tokspan.com/v1/chat/completions

Ví Dụ Nhanh

Cùng một API, mọi mô hình. Chọn ngôn ngữ của bạn:

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.tokspan.com/v1")
response = client.chat.completions.create(model="gpt-4o", messages=[{"role":"user","content":"Hello"}])
print(response.choices[0].message.content)

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.TOKSPAN_API_KEY, baseURL: 'https://api.tokspan.com/v1' });
const response = await client.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello' }] });
console.log(response.choices[0].message.content);

curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Nội Dung Yêu Cầu

Ví Dụ Yêu Cầu & Phản Hồi

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What is the capital of France?" }
  ],
  "temperature": 0.7,
  "max_tokens": 256
}

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

Các Trường Phản Hồi

Hiểu Về Mức Sử Dụng Token

Đối tượng usage báo cáo token đã tiêu thụ cho mục đích thanh toán:

• prompt_tokens — Token trong các message đầu vào của bạn (bao gồm system prompt, lịch sử hội thoại và mọi phương tiện đính kèm được quy đổi thành token tương đương)
• completion_tokens — Token được mô hình tạo ra trong phản hồi
• total_tokens — Tổng của prompt + completion tokens = số tiền bạn bị tính phí

Đối với đầu vào đa phương thức (hình ảnh, âm thanh), các nhà cung cấp quy đổi phương tiện thành token tương đương. GPT-4o tính ~85 token cho ảnh độ phân giải thấp và ~170+ cho độ phân giải cao. Bảng điều khiển của bạn hiển thị số token cuối cùng và chi phí cho mỗi yêu cầu.

Phản Hồi Streaming (SSE)

Đặt stream: true để nhận token theo thời gian thực khi mô hình tạo ra chúng. TokSpan sử dụng Server-Sent Events (SSE) tiêu chuẩn — hoàn toàn tương thích với định dạng streaming của OpenAI.

Ví Dụ

from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://api.tokspan.com/v1")

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Tell me a story."}],
    "stream": true
  }'

Định Dạng SSE Chunk

Mỗi chunk là một đối tượng JSON có tiền tố data:. Luồng kết thúc bằng data: [DONE]:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":" world"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Mỗi chunk chứa một đối tượng delta (không phải message). Trường content có thể trống hoặc không có trong chunk cuối cùng. Chunk cuối cùng có finish_reason được đặt và delta trống.

Streaming Với Gọi Công Cụ

Khi mô hình gọi một function trong quá trình streaming, các chunk gọi công cụ đến trong delta với tool_calls — tên function và tham số được truyền tải tăng dần. Tích lũy tất cả các chunk cho một tool_call_id nhất định để tập hợp lời gọi function hoàn chỉnh, sau đó gửi lại một message role: "tool".

Gọi Công Cụ / Function Calling

TokSpan hỗ trợ function calling tương thích OpenAI trên tất cả các mô hình có khả năng. Định nghĩa tool của bạn trong yêu cầu và mô hình sẽ phản hồi bằng lời gọi function JSON có cấu trúc để code của bạn thực thi.

Định Nghĩa Công Cụ

Truyền một mảng tools với các định nghĩa function. Mỗi function cần có name, description và JSON Schema parameters:

"tools": [{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}]

Phản Hồi Của Mô Hình Với Gọi Công Cụ

Khi mô hình quyết định gọi một function, phản hồi sẽ bao gồm tool_calls thay vì nội dung văn bản:

{
  "role": "assistant",
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"city\": \"Paris\"}"
    }
  }]
}

Quy Trình Gọi Công Cụ Hoàn Chỉnh

1. Gửi yêu cầu với định nghĩa tools
2. Nhận tool_calls trong phản hồi — trích xuất tên function và tham số
3. Thực thi function trong code của bạn (gọi API thời tiết, truy vấn cơ sở dữ liệu, v.v.)
4. Gửi kết quả trở lại dưới dạng message với role: "tool", tham chiếu đến tool_call_id
5. Mô hình phản hồi bằng câu trả lời ngôn ngữ tự nhiên tích hợp kết quả công cụ

Mô Hình Được Hỗ Trợ

Gọi công cụ được hỗ trợ bởi: GPT-4o, GPT-4.1, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 2.5 Pro, Gemini 2.5 Flash, DeepSeek V3, Mistral Large 3, Llama 4, Qwen3 và nhiều mô hình khác. Xem trang Mô Hình để biết chi tiết khả năng từng mô hình.

Thị Giác / Đầu Vào Hình Ảnh

Đối với các mô hình đa phương thức như GPT-4o và Claude 4 Vision, bao gồm hình ảnh dưới dạng URL hoặc dữ liệu base64 trong mảng content:

{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "What's in this image?" },
      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
    ]
  }]
}

Định dạng hình ảnh được hỗ trợ: PNG, JPEG, WebP, GIF (không hoạt ảnh). Kích thước tối đa tùy theo mô hình — thường là 20MB mỗi ảnh. Đối với mô hình Claude, tài liệu PDF cũng được hỗ trợ làm đầu vào trực quan.

Chế Độ JSON / Đầu Ra Có Cấu Trúc

Buộc mô hình trả về JSON hợp lệ bằng cách đặt response_format:

• Chế độ JSON: {"type": "json_object"} — Mô hình trả về JSON hợp lệ. Bạn phải bao gồm từ "JSON" trong system prompt của mình.
• Đầu ra có cấu trúc: {"type": "json_schema", "json_schema": {...}} — Mô hình trả về JSON khớp chính xác schema của bạn. Được hỗ trợ bởi GPT-4o và các mô hình mới hơn.