Chat completions

Chat completion là endpoint được dùng nhiều nhất: gửi một danh sách tin nhắn tới mô hình và nhận lại phản hồi được sinh ra. Cổng vào chính của nền tảng là giao thức tương thích OpenAI; giao thức Anthropic và Gemini là các dạng đẳng cấu tương đương.

Cấu trúc yêu cầu (tương thích OpenAI)

POST {base}/chat/completions — xác thực xem tại Xác thực:

{
  "model": "your-model",
  "messages": [
    {"role": "system", "content": "You are a support assistant."},
    {"role": "user", "content": "Where is my order?"},
    {"role": "assistant", "content": "Sure, may I have the order number?"},
    {"role": "user", "content": "A1024"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}

• messages là lịch sử hội thoại theo thứ tự; role là system / user / assistant. Với hội thoại nhiều lượt, ứng dụng khách ghép toàn bộ lịch sử lại và gửi lại mỗi lần;
• temperature càng cao thì đầu ra càng đa dạng (thường từ 0–1); max_tokens giới hạn độ dài phản hồi;
• Streaming: với "stream": true, phản hồi được đẩy dần qua SSE (choices[0].delta) — rất phù hợp để hiển thị văn bản ngay khi đang được sinh. Với SDK chính thức: truyền stream=True rồi lặp qua các phần tử.

Cấu trúc phản hồi

Các trường chính của một phản hồi không streaming:

{
  "choices": [
    {
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 58, "completion_tokens": 132, "total_tokens": 190}
}

• choices[0].message.content chứa nội dung phản hồi; finish_reason là stop nghĩa là kết thúc tự nhiên, length nghĩa là bị max_tokens cắt;
• usage là lượng token tiêu thụ của lệnh gọi này — cả việc tính phí lẫn trang "Mức sử dụng" đều dựa trên đó.

Các endpoint tương đương trong giao thức khác

• Anthropic: POST {base}/v1/messages — tên trường khác đi (max_tokens là bắt buộc, phản hồi nằm trong mảng content), còn ngữ nghĩa thì giống hệt;
• Gemini: POST {base}/v1beta/models/{model}:generateContent — tin nhắn nằm trong mảng contents.

Ba giao thức là đẳng cấu; việc chuyển đổi chủ yếu là đổi tên trường. Cách làm thực tế là dùng SDK chính thức tương ứng (openai / @anthropic-ai/sdk / @google/genai) với base_url trỏ về nền tảng.