API mô hình và văn bản

Danh mục mô hình và hội thoại văn bản đều dùng cùng một khóa API nền tảng. Quy ước chung (địa chỉ cơ sở, xác thực, giới hạn tần suất, thử lại) xem Xác thực và quy chuẩn cơ bản.

Truy vấn danh sách mô hình

Phương thức xác thực

Authorization: Bearer <API_KEY>.

Tham số yêu cầu

Không có phần thân yêu cầu, chỉ cần mang khóa API trong header yêu cầu.

Ví dụ yêu cầu

curl "https://locopalai.com/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Tham số phản hồi

object và success là trường cấp cao nhất, không nằm trong data[]. object cố định là list, success là true khi thành công. Để phán đoán yêu cầu có thành công hay không hãy lấy mã trạng thái HTTP làm chuẩn, success chỉ mang tính hỗ trợ.

Phần thân phản hồi

{
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    },
    {
      "id": "claude-sonnet-4-5-20250929",
      "object": "model",
      "created": 1626777600,
      "owned_by": "claude",
      "supported_endpoint_types": ["anthropic", "openai"]
    }
  ],
  "object": "list",
  "success": true
}

Trả về "data": [] nghĩa là nhóm gọi của Key hiện tại không có mô hình khả dụng, vui lòng xác nhận cấu hình nhóm trước hoặc liên hệ hỗ trợ nền tảng, đừng đổi sang tên hiển thị trên trang để thử lại. Danh mục mô hình sẽ thay đổi theo ủy quyền và tính khả dụng của nền tảng, khuyến nghị làm mới một lần khi khởi động dịch vụ, khi người dùng chọn mô hình hoặc khi nhận "mô hình không khả dụng".

Phản hồi lỗi

Hội thoại văn bản

Phương thức xác thực

Authorization: Bearer <API_KEY>.

Phần thân yêu cầu · application/json

Ví dụ yêu cầu

curl -X POST "https://locopalai.com/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的文本模型 ID",
  "messages": [{ "role": "user", "content": "只回复两个字：你好" }],
  "stream": false
}
JSON

Tham số phản hồi

usage còn có thể chứa các trường lượng dùng chi tiết của lần tính phí này (cache hit, phân tách đầu vào/đầu ra, v.v.), lấy theo thực tế trả về. Một số kênh còn trả về các trường mở rộng như latency_checkpoint, routing, system_fingerprint, client nên bỏ qua các trường không nhận diện được, đừng phân tích theo tập trường cố định đầy đủ.

Phần thân phản hồi

{
  "id": "msg_011CevNtsfivFKb6YP3WcL7A",
  "model": "claude-haiku-4-5-20251001",
  "object": "chat.completion",
  "created": 1789071575,
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20587,
    "completion_tokens": 6,
    "total_tokens": 20593
  }
}

Phản hồi dạng luồng (thêm "stream": true vào phần thân yêu cầu, phản hồi là text/event-stream):

data: {"choices":[{"delta":{"content":"这是"}}]}
data: {"choices":[{"delta":{"content":"模型输出"}}]}
data: [DONE]

Client phải tiếp tục đọc cho đến [DONE]; phản hồi dạng luồng không nên bị lớp trung gian cache hoặc ghép thành nội dung trùng lặp. Khối dữ liệu cuối cùng có thể chỉ chứa usage, lúc đó choices có thể rỗng.

Mô hình suy luận có thể trả về nội dung rỗng

Một số mô hình suy luận sẽ ưu tiên dùng hạn mức đầu ra cho suy luận ẩn. Thực tế khi yêu cầu gpt-5-nano và max_tokens quá nhỏ, HTTP trả về 200, nhưng message.content rỗng, finish_reason là length, usage.completion_tokens_details.reasoning_tokens bằng giới hạn đầu ra. Gặp trường hợp này nên tăng hạn mức hoặc đổi sang mô hình văn bản không suy luận, không được coi chuỗi rỗng là lỗi mô hình hay lỗi API.

Ví dụ phía máy chủ

const response = await fetch('https://locopalai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LOCOPAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '从 /v1/models 选择的模型 ID',
    messages: [{ role: 'user', content: '写一条产品简介。' }],
  }),
})

if (!response.ok) throw new Error(await response.text())
const data = await response.json()

Đừng đặt khóa API vào mã trình duyệt; yêu cầu từ frontend trước tiên đến backend nghiệp vụ của bạn, rồi backend chuyển tiếp.

Phản hồi lỗi

{
  "error": {
    "code": "model_not_found",
    "message": "No available channel for model xxx under group xxx (distributor) (request id: ...)",
    "type": "new_api_error"
  }
}

Giải thích đầy đủ xem Mã lỗi và khắc phục.