Tài liệu API

Tài liệu API Reference

Giới thiệu

KN Vista API là một RESTful API cho phép ứng dụng của bạn tương tác với nền tảng KN Vista AI. API này cung cấp các endpoint theo định hướng tài nguyên, trả về phản hồi dạng JSON, và sử dụng các mã phản hồi HTTP tiêu chuẩn, cơ chế xác thực, và các động từ HTTP phổ biến.

Xác thực và Bảo mật

API Key

Tất cả các yêu cầu API đều yêu cầu xác thực bằng API Key. Để lấy API Key, vui lòng liên hệ với quản trị viên hệ thống của bạn.

API Key phải được gửi trong header Authorization của mỗi yêu cầu:

Authorization: Bearer YOUR_API_KEY

Endpoint xác thực

Bạn có thể kiểm tra tính hợp lệ của API Key bằng cách sử dụng endpoint /validate:

GET /validate

Phản hồi khi thành công:

{
  "name": "my-api-key",
  "expires_at": "1704081600000",
  "company": "54fb80af-576c-4fdc-ba4f-b596c83f15a1",
  "status": "active"
}

Giới hạn tốc độ

KN Vista API áp dụng giới hạn tốc độ để bảo vệ hệ thống khỏi việc sử dụng quá mức. Giới hạn cụ thể sẽ được cung cấp trong header phản hồi:

  • X-RateLimit-Limit: Số lượng yêu cầu tối đa được phép trong khoảng thời gian
  • X-RateLimit-Remaining: Số lượng yêu cầu còn lại trong khoảng thời gian hiện tại
  • X-RateLimit-Reset: Thời gian (tính bằng giây) khi giới hạn sẽ được đặt lại

Phân trang

Để hỗ trợ tập dữ liệu lớn, API sử dụng phân trang theo token tiếp tục. API giới hạn phản hồi GET nhiều bản ghi tối đa 1000 bản ghi, mặc dù người gọi có thể cung cấp giới hạn thấp hơn bằng tham số limit.

Kiểm tra giá trị thuộc tính continuation_token và next để xác định xem có thêm bản ghi hay không.

Các endpoint API

Ứng dụng (Applications)

Lấy danh sách ứng dụng

GET /applications

Tham số:

  • company_id (bắt buộc): ID công ty

Lấy thông tin ứng dụng theo ID

GET /applications/{id}

Cập nhật thông tin cơ bản của ứng dụng

PUT /applications/{id}

Mô hình AI (AI Models)

Lấy danh sách mô hình AI

GET /models

Tham số:

  • status (không bắt buộc): Lọc theo trạng thái mô hình (active, inactive)
  • type (không bắt buộc): Lọc theo loại mô hình (text, image, audio)

Lấy thông tin mô hình theo ID

GET /models/{id}

Đại lý (Agents)

Tạo đại lý mới

POST /agents

Body yêu cầu:

{
  "name": "Tên đại lý",
  "description": "Mô tả về đại lý",
  "model_id": "id_của_mô_hình",
  "tools": ["web_search", "code_interpreter"]
}

Lấy danh sách đại lý

GET /agents

Lấy thông tin đại lý theo ID

GET /agents/{id}

Kiến thức (Knowledge)

Tải lên tài liệu kiến thức

POST /knowledge/upload

Body yêu cầu:

{
  "file": "file_data",
  "name": "Tên tài liệu",
  "description": "Mô tả tài liệu"
}

Lấy danh sách tài liệu kiến thức

GET /knowledge

Hội thoại (Conversations)

Tạo hội thoại mới

POST /conversations

Body yêu cầu:

{
  "agent_id": "id_của_đại_lý",
  "messages": [
    {
      "role": "user",
      "content": "Nội dung tin nhắn"
    }
  ]
}

Lấy danh sách hội thoại

GET /conversations

Lấy thông tin hội thoại theo ID

GET /conversations/{id}

Thêm tin nhắn vào hội thoại

POST /conversations/{id}/messages

Body yêu cầu:

{
  "role": "user",
  "content": "Nội dung tin nhắn"
}

Thống kê sử dụng (Usage Statistics)

Lấy thống kê sử dụng

GET /usage

Tham số:

  • start_date (không bắt buộc): Ngày bắt đầu (YYYY-MM-DD)
  • end_date (không bắt buộc): Ngày kết thúc (YYYY-MM-DD)
  • type (không bắt buộc): Loại thống kê (tokens, requests, conversations)

Mã lỗi

API sử dụng mã HTTP tiêu chuẩn để chỉ ra thành công hoặc thất bại của một yêu cầu:

  • 200 OK: Yêu cầu thành công
  • 201 Created: Tài nguyên đã được tạo thành công
  • 400 Bad Request: Yêu cầu không hợp lệ
  • 401 Unauthorized: Xác thực thất bại
  • 403 Forbidden: Không có quyền truy cập vào tài nguyên
  • 404 Not Found: Tài nguyên không tồn tại
  • 429 Too Many Requests: Vượt quá giới hạn tốc độ
  • 500 Internal Server Error: Lỗi máy chủ

Xử lý lỗi

Khi xảy ra lỗi, API sẽ trả về một đối tượng JSON với cấu trúc sau:

{
  "error": {
    "code": "error_code",
    "message": "Mô tả lỗi",
    "details": {
      // Thông tin chi tiết về lỗi (nếu có)
    }
  }
}

Môi trường

KN Vista API có sẵn trong hai môi trường:

Môi trường thử nghiệm (Sandbox)

https://api-sandbox.knvista.com/v1

Môi trường sản xuất (Production)

https://api.knvista.com/v1

Hỗ trợ và câu hỏi

Nếu bạn có bất kỳ câu hỏi hoặc vấn đề nào khi sử dụng KN Vista API, vui lòng liên hệ đội ngũ hỗ trợ của chúng tôi qua email support@knvista.com.

IndexVí dụ