Models

Giao diện danh sách mô hình trả lời một câu hỏi: Token hiện tại có thể gọi những mô hình nào. Kết quả trả về đã được lọc theo quyền của Token, nhóm và trạng thái phát hành, không phải toàn bộ danh mục mô hình của nền tảng. Giá trị model trong yêu cầu buộc phải lấy từ danh sách này.

Liệt kê mô hình khả dụng

GET /v1/models

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Phản hồi:

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "gpt-5.5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["openai", "openai-response"]
    },
    {
      "id": "claude-sonnet-4-5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "anthropic",
      "supported_endpoint_types": ["openai", "anthropic"]
    },
    {
      "id": "text-embedding-3-large",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["embeddings"]
    }
  ]
}

Trường	Mô tả
id	Giá trị điền vào model khi gọi, là định danh mô hình đáng tin cậy duy nhất
object	Luôn là "model"
created	Giá trị giữ chỗ cố định 1626777600, không phải thời gian phát hành thực tế, đừng dùng nó để sắp xếp hay phán đoán mới/cũ
owned_by	Loại kênh mà mô hình thuộc về (ví dụ openai, anthropic); mô hình tùy chỉnh của nền tảng là custom
supported_endpoint_types	Danh sách loại endpoint khả dụng cho mô hình này, xem Loại endpoint bên dưới

Tầng ngoài cùng của phản hồi có đồng thời success và object/data theo phong cách OpenAI. OpenAI SDK chỉ đọc data, trường success dư ra không ảnh hưởng việc phân tích.

Thứ tự của data không đảm bảo ổn định, hai lần yêu cầu có thể khác nhau. Nếu cần thứ tự cố định, hãy tự sắp xếp ở phía client.

Loại endpoint

supported_endpoint_types là trường mở rộng của RouteAPI, và cũng là tín hiệu năng lực duy nhất trong danh sách mô hình. Nó cho biết mô hình này có thể được gọi từ những cổng giao thức nào:

Giá trị	Endpoint tương ứng
openai	POST /v1/chat/completions
openai-response	POST /v1/responses
anthropic	POST /v1/messages
gemini	POST /v1beta/models/{model}:generateContent
embeddings	POST /v1/embeddings
image-generation	POST /v1/images/generations
jina-rerank	POST /v1/rerank
openai-video	Endpoint tạo video của OpenAI
suno-*	Các endpoint dòng Suno, xem Suno API

Nếu supported_endpoint_types của một mô hình không có embeddings, đừng truyền nó cho /v1/embeddings — kiểu lệch khớp này sẽ thất bại ở giai đoạn chuyển tiếp.

Danh sách không có trường năng lực chi tiết. Việc có hỗ trợ gọi công cụ, đầu vào hình ảnh hay đầu ra có cấu trúc thì giao diện danh sách mô hình không trả về, cũng không có các trường kiểu supports_tools / supports_vision. Những năng lực này do chính mô hình phía trên quyết định; cách xác nhận là tra tài liệu của nhà cung cấp mô hình, hoặc gửi trực tiếp một yêu cầu thật tới mô hình đích để kiểm chứng. Các metadata như độ dài ngữ cảnh, phương thức (modality) và giá cũng không nằm trong giao diện này, chúng được trình bày ở trang quảng trường mô hình trong console.

Truy vấn một mô hình

GET /v1/models/{model}

curl https://api.routeapi.ai/v1/models/gpt-5.5 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Khi mô hình tồn tại, đối tượng mô hình được trả về trực tiếp (không bọc trong data):

{
  "id": "gpt-5.5",
  "object": "model",
  "created": 1626777600,
  "owned_by": "openai"
}

Khi không tồn tại hoặc không hiển thị với tài khoản hiện tại, phản hồi là:

{
  "error": {
    "message": "The model 'foo' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Lưu ý mã trạng thái HTTP vẫn là 200. Giao diện này đặt lỗi vào trường error của thân phản hồi, không dùng mã trạng thái để diễn đạt “mô hình không tồn tại”. Client buộc phải kiểm tra xem trong thân phản hồi có error hay không; chỉ xem mã trạng thái HTTP sẽ khiến thất bại bị hiểu thành thành công.

Mô hình không hiển thị với tài khoản hiện tại và mô hình thực sự không tồn tại trả về lỗi hoàn toàn giống nhau, không thể phân biệt hai trường hợp qua giao diện này.

Danh sách mô hình ở các giao thức khác

Cùng một tập mô hình khả dụng có thể lấy về theo ba định dạng giao thức, chọn theo SDK của bạn.

Định dạng Claude Messages

Trên GET /v1/models, gửi đồng thời header x-api-key và anthropic-version sẽ nhận về phong cách Anthropic:

curl https://api.routeapi.ai/v1/models \
  -H "x-api-key: $ROUTEAPI_KEY" \
  -H "anthropic-version: 2023-06-01"

{
  "data": [
    {
      "id": "claude-sonnet-4-5",
      "created_at": "2021-07-20T12:00:00Z",
      "display_name": "claude-sonnet-4-5",
      "type": "model"
    }
  ],
  "first_id": "claude-sonnet-4-5",
  "has_more": false,
  "last_id": "claude-sonnet-4-5"
}

Hai header phải cùng tồn tại mới chuyển sang định dạng này, chỉ gửi x-api-key thì vẫn trả về định dạng OpenAI. display_name bằng với id, không phải tên hiển thị trong console. has_more luôn là false — danh sách trả về hết trong một lần, không có phân trang. Khi danh sách rỗng thì first_id và last_id là chuỗi rỗng.

Định dạng Gemini

curl "https://api.routeapi.ai/v1beta/models" \
  -H "x-goog-api-key: $ROUTEAPI_KEY"

{
  "models": [
    { "name": "gemini-2.5-pro", "displayName": "gemini-2.5-pro" }
  ],
  "nextPageToken": null
}

Đối tượng mô hình ở định dạng Gemini còn bao gồm các trường như inputTokenLimit, supportedGenerationMethods, nhưng RouteAPI chỉ điền name và displayName, các trường còn lại trả về null. Đừng dựa vào những trường rỗng này để phán đoán năng lực mô hình.

Danh sách mô hình theo giao thức Gemini hãy dùng đường dẫn /v1beta/models, đừng gửi header Gemini trên /v1/models.

Không có tiền tố /v1

Khi client cấu hình Base URL không kèm /v1 (ví dụ https://api.routeapi.ai), GET /models vẫn dùng được, bên trong sẽ được viết lại về /v1/models.

Bốn lớp lọc quyết định nội dung danh sách

Để một mô hình xuất hiện trong danh sách của bạn, nó cần vượt qua đồng thời bốn lớp lọc. Khi xử lý sự cố “mô hình không có trong danh sách”, hãy xem theo thứ tự này:

1. Danh sách trắng mô hình của Token — nếu Token này bật giới hạn mô hình, danh sách là phần giao của danh sách trắng với các điều kiện còn lại. Nếu không bật thì sang mục tiếp theo.
2. Mô hình đã bật của nhóm — lấy hợp của các mô hình đã bật thuộc nhóm người dùng của bạn (và nhóm do Token chỉ định). Mô hình không có kênh khả dụng nào sẽ không xuất hiện.
3. Trạng thái phát hành trong danh mục — khi nền tảng bật chế độ metadata nghiêm ngặt, mô hình chưa phát hành đối với bên ngoài tương đương như không tồn tại.
4. Đã cấu hình giá hay chưa — mô hình chưa cấu hình giá mặc định bị lọc bỏ, trừ khi nền tảng bật chế độ tự dùng, hoặc trong thiết lập tài khoản của bạn đã bật “chấp nhận mô hình chưa đặt giá”.

Sau bốn lớp lọc, trả về danh sách rỗng là kết quả bình thường, không phải lỗi. Khi toàn bộ mô hình trong nhóm đều chưa phát hành thì sẽ như vậy.

Trên cùng một nền tảng, danh sách mô hình của các Token khác nhau có thể hoàn toàn khác nhau. Dùng Token A để xem danh sách rồi dùng Token B để gửi yêu cầu là cách mắc bẫy thường gặp — khi xử lý sự cố nhất định phải dùng cùng một Token cho cả hai việc.

Xử lý sự cố mô hình không khả dụng

Khi yêu cầu báo lỗi liên quan tới mô hình, trước tiên hãy đối chiếu nội dung lỗi để xác định đúng khâu:

Nội dung lỗi	HTTP	Ý nghĩa	Cách xử lý
Model name not specified...	400	model trong yêu cầu bị rỗng	Bổ sung trường model
This token has no access to model {model}	403	Mô hình không nằm trong danh sách trắng của Token đó	Thêm mô hình đó cho Token trong console, hoặc đổi sang Token không giới hạn mô hình
This token has no access to any models	403	Token đã bật giới hạn mô hình nhưng danh sách trắng rỗng	Bổ sung đầy đủ danh sách trắng
No valid upstream service	503	Mô hình không có kênh khả dụng (chưa cấu hình, bị tắt hết hoặc đang ngắt mạch)	Xác nhận chính tả ID mô hình; đổi sang mô hình khác trong danh sách; liên hệ quản trị viên nền tảng
The model '{model}' does not exist	200 (error trong thân)	GET /v1/models/{model} không tìm thấy hoặc không hiển thị	Dùng GET /v1/models để xác nhận ID chính xác

Thứ tự xử lý sự cố:

1. Dùng cùng một Token gọi GET /v1/models, xác nhận mô hình thực sự có trong danh sách.
2. Đối chiếu từng ký tự chính tả của model, gồm cả chữ hoa chữ thường và dấu gạch nối. ID mô hình khớp chính xác tuyệt đối.
3. Xác nhận endpoint đang gọi nằm trong supported_endpoint_types của mô hình đó.
4. Nếu các mục trên đều đúng mà vẫn thất bại, nghĩa là vấn đề ở phía kênh (không có upstream khả dụng hoặc upstream báo lỗi), hãy vào log console tra theo request ID để xem phản hồi upstream cụ thể. Chi tiết xem Lỗi và gỡ lỗi.

Thực hành tốt nhất

• Cố định ID mô hình, đừng dùng tên hiển thị trong console hay bí danh tạm thời. Yêu cầu chỉ nhận id.
• Lấy danh sách một lần khi khởi động rồi cache lại, đừng truy vấn ở mỗi yêu cầu nghiệp vụ. Tập mô hình khả dụng thay đổi rất ít.
• Đừng sắp xếp theo created, nó là giá trị giữ chỗ cố định dùng chung cho mọi mô hình.
• Chuẩn bị mô hình dự phòng cho luồng quan trọng, chuyển sang nó khi mô hình chính trả về 503.
• Trước khi lên production hãy kiểm thử thực tế một lần bằng Token production, chạy cả danh sách mô hình và một lần gọi thật, bao phủ gọi công cụ, đầu vào hình ảnh và các năng lực bạn thực sự dùng — những năng lực này giao diện danh sách không đảm bảo.

Tiếp theo

• Phương thức xác thực — quyền của Token, danh sách trắng mô hình và cấu hình hạn mức.
• Chat Completions — dùng mô hình trong danh sách để khởi tạo hội thoại.
• Lỗi và gỡ lỗi — mã trạng thái đầy đủ và thứ tự xử lý sự cố.
• Tính phí và hạn mức — giá mô hình và cách tính lượng dùng.