Chat Completions

Chat Completions là giao diện hội thoại được dùng phổ biến nhất, phù hợp với chat thông thường, trợ lý lập trình, tóm tắt, phân loại, gọi công cụ và hội thoại nhiều lượt.

Giao diện tuân theo protocol Chat Completions của OpenAI, nên tích hợp OpenAI hiện có chỉ cần đổi Base URL và API Key. Cùng endpoint này cũng gọi được mô hình Claude, Gemini và các mô hình khác; RouteAPI tự chuyển đổi định dạng yêu cầu và phản hồi.

Endpoint

POST /v1/chat/completions

Địa chỉ đầy đủ:

https://api.routeapi.ai/v1/chat/completions

Nếu client cấu hình Base URL không có /v1 (ví dụ https://api.routeapi.ai), yêu cầu tới /chat/completions vẫn được chấp nhận; RouteAPI ghi lại thành /v1/chat/completions.

Ví dụ yêu cầu

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "Hãy giới thiệu RouteAPI trong một câu" }
    ]
  }'

Tham số yêu cầu

Trường	Kiểu	Bắt buộc	Mô tả
`model`	string	Có	ID mô hình, phải là mô hình khả dụng cho tài khoản hiện tại
`messages`	array	Có	Danh sách tin nhắn hội thoại
`stream`	boolean	Không	Có sử dụng đầu ra streaming SSE hay không, mặc định `false`
`temperature`	number	Không	Nhiệt độ lấy mẫu
`top_p`	number	Không	Tham số nucleus sampling
`max_tokens`	number	Không	Số token đầu ra tối đa
`max_completion_tokens`	number	Không	Tên mới của giới hạn đầu ra; khi cả hai cùng có, RouteAPI ưu tiên trường này cho giới hạn và cách tính của chính nó
`stop`	string/array	Không	Chuỗi dừng tùy chỉnh
`n`	integer	Không	Số ứng viên; có thực sự trả nhiều ứng viên hay không tùy mô hình
`presence_penalty`	number	Không	Hình phạt hiện diện
`frequency_penalty`	number	Không	Hình phạt tần suất
`seed`	number	Không	Seed lấy mẫu trong khả năng; khả năng tái lập tùy mô hình upstream
`user`	string	Không	Định danh người dùng cuối, được chuyển tiếp tới upstream hỗ trợ trường này
`tools`	array	Không	Định nghĩa công cụ
`tool_choice`	string/object	Không	Chiến lược chọn công cụ
`response_format`	object	Không	JSON mode hoặc JSON Schema
`stream_options`	object	Không	Tùy chọn bổ sung cho streaming, ví dụ `include_usage`

Trường tùy chọn được chuyển tiếp nguyên trạng: trường không gửi sẽ không bị điền giá trị mặc định. Xem mục “Giá trị zero tường minh” bên dưới.

Định dạng `messages`

[
  { "role": "system", "content": "Bạn là một trợ lý kỹ thuật cẩn trọng." },
  { "role": "user", "content": "Giải thích API gateway là gì." }
]

Các role thường gặp:

Role	Mô tả
`system`	Prompt hệ thống
`user`	Đầu vào người dùng
`assistant`	Phản hồi lịch sử của mô hình
`tool`	Kết quả gọi công cụ

content có thể là chuỗi hoặc mảng khối nội dung cho đầu vào đa phương thức, xem Đầu vào đa phương thức. Khi tin nhắn assistant trả về lời gọi công cụ, hãy gửi lại nguyên tin nhắn đó rồi thêm kết quả với role: "tool", xem Gọi công cụ.

Ví dụ phản hồi

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "RouteAPI là một API gateway thống nhất để quản lý nhiều dịch vụ mô hình AI."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42
  }
}

finish_reason cho biết lý do kết thúc: stop (kết thúc tự nhiên), length (chạm giới hạn đầu ra), tool_calls (mô hình muốn gọi công cụ) hoặc content_filter (bị bộ lọc nội dung chặn).

Streaming

Đặt stream: true để nhận Server-Sent Events. Mỗi dòng là một chat.completion.chunk, phần tăng dần nằm trong choices[0].delta, và luồng kết thúc bằng data: [DONE]:

data: {"id":"chatcmpl_xxx","object":"chat.completion.chunk","created":1730000000,"model":"gpt-5.5","choices":[{"index":0,"delta":{"content":"RouteAPI"},"finish_reason":null}]}

data: {"id":"chatcmpl_xxx","object":"chat.completion.chunk","created":1730000000,"model":"gpt-5.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Mặc định RouteAPI thêm một chunk cuối chứa lượng token dùng với mảng choices rỗng trước data: [DONE]. Gửi "stream_options": {"include_usage": false} để tắt (kênh không hỗ trợ stream_options luôn gửi khung này); lượng dùng vẫn được ghi trong log console. Cách xử lý từng sự kiện và lỗi giữa luồng xem tại Phản hồi streaming.

Cấu hình SDK

SDK OpenAI chính thức dùng được nguyên vẹn sau khi trỏ API Key và Base URL sang RouteAPI.

OpenAI Python SDK

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hãy giới thiệu RouteAPI trong một câu"}],
)

print(response.choices[0].message.content)

OpenAI Node.js SDK

npm install openai

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,
  baseURL: 'https://api.routeapi.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Hãy giới thiệu RouteAPI trong một câu' }],
});

console.log(response.choices[0].message.content);

LangChain và LiteLLM

Cả hai thư viện đều nhận endpoint tương thích OpenAI tùy chỉnh:

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-5.5",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

import os
import litellm

response = litellm.completion(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hãy giới thiệu RouteAPI trong một câu"}],
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
)

Client tương thích khác

Bất kỳ client nào hỗ trợ Base URL OpenAI tùy chỉnh đều kết nối được với cùng ba cấu hình:

API Key — API Key RouteAPI bắt đầu bằng sk-.
Base URL — https://api.routeapi.ai/v1.
Mô hình — ID do GET /v1/models trả về, xem Models.

Cấu hình sẵn cho Codex, Cursor, Claude Code, OpenCode và các công cụ khác có trong Chuyển từ OpenAI.

Khác biệt so với OpenAI API chính thức

Phạm vi mô hình rộng hơn

OpenAI API chính thức chỉ phục vụ mô hình của OpenAI. Ở đây, cùng trường model nhận mô hình của nhiều nhà cung cấp — ví dụ gpt-5.5, claude-sonnet-4-5, gemini-2.5-pro — tùy theo Key và nhóm của bạn. Chỉ GET /v1/models cho biết bạn gọi được những mô hình nào.

Tính phí và giới hạn do RouteAPI quản lý

Tính phí theo bảng giá của RouteAPI, có thể khác giá chính thức của nhà cung cấp.
Giới hạn tốc độ theo chính sách của RouteAPI chứ không phải hạn mức của nhà cung cấp.
Số dư và hạn mức key quản lý trong console RouteAPI.

Xem Tính phí và hạn mức và Giá mô hình.

Năng lực phụ thuộc mô hình được chọn

Protocol chỉ định nghĩa các trường; mô hình quyết định trường nào thực sự có hiệu lực. Gọi công cụ, đầu vào hình ảnh, đầu ra có cấu trúc, usage trong streaming và điều khiển suy luận đều phụ thuộc mô hình đã chọn và dịch vụ upstream phía sau. Endpoint danh sách mô hình không trả cờ năng lực, nên hãy xác nhận bằng một yêu cầu thật trước khi dựa vào tính năng đó ở production.

Giá trị zero tường minh

Tham số tùy chọn gửi rõ ràng 0, 0.0 hoặc false được giữ nguyên và chuyển tiếp, không bị coi là “chưa đặt” mà bỏ đi. Nhờ vậy có thể cố định temperature: 0 để lấy mẫu tất định. Muốn để tham số chưa đặt, hãy bỏ hẳn trường thay vì gửi null.

Lỗi từ upstream

Khi dịch vụ mô hình từ chối yêu cầu, RouteAPI trả về mã trạng thái và thông điệp của upstream trong body lỗi chuẩn, kèm hậu tố (request id: <id>). Lỗi phát sinh trước khi định tuyến — key không hợp lệ, mô hình không được phép, không có kênh khả dụng — dùng mã liệt kê trong Lỗi thường gặp.

Lưu ý tương thích

Mức độ hỗ trợ cùng một tham số có thể khác nhau giữa các dịch vụ mô hình.
Nếu yêu cầu chứa tham số tùy chọn như tools, response_format, stream_options, hãy xác nhận trước rằng mô hình đã chọn hỗ trợ năng lực tương ứng.
Tham số tùy chọn được truyền rõ ràng là 0 hoặc false nên được coi là thiết lập rõ ràng của người dùng.
Khi dùng chung đầu ra có cấu trúc với gọi công cụ, đọc ràng buộc trong Đầu ra có cấu trúc trước.

Responses — protocol OpenAI mới hơn, phổ biến trong agent lập trình.
Claude Messages — định dạng gốc Anthropic, dùng được tính năng riêng của Claude.
Google Gemini API — định dạng gốc Google.
Models — Key của bạn gọi được mô hình nào và loại endpoint của chúng.