Tài liệu tham khảo API

Base URL

Mọi yêu cầu đều được gửi tới:

Xác thực

Tạo một khóa tại trang khóa API, sau đó gửi nó dưới dạng bearer token trong header Authorization. Chỉ một mã băm (hash) của khóa của bạn được lưu trữ — hãy sao chép nó ngay khi được tạo, vì GatifyAI sẽ không thể hiển thị lại nó cho bạn.

Bắt đầu nhanh

Một yêu cầu tối giản bằng curl, Python, hoặc TypeScript:

curl https://gatifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Giới hạn một khóa cho các mô hình cụ thể

Theo mặc định, một khóa mới có thể dùng bất kỳ mô hình miễn phí nào của GatifyAI, với cùng cơ chế tự động chuyển đổi dự phòng mà web chat sử dụng nếu một mô hình không khả dụng. Thay vào đó, bạn có thể giới hạn một khóa cho một mô hình cụ thể hoặc một danh sách ngắn — khi đó khóa sẽ chỉ sử dụng các mô hình trong danh sách đó, theo đúng thứ tự bạn đã đưa ra, bất kể yêu cầu đòi hỏi mô hình nào. Yêu cầu một mô hình ngoài danh sách đó sẽ trả về lỗi 400 nêu rõ các mô hình mà khóa thực sự được phép sử dụng.

Trò chuyện với vai trò một nhân vật

Truyền model: "persona/<slug>" để trò chuyện với vai trò một nhân vật được xuất bản trong thư viện cộng đồng — tính cách và các mô hình ưa thích của nhân vật đó được sử dụng tự động, vẫn bị giới hạn bởi các mô hình được phép của khóa bạn nếu bạn đã thiết lập. Tìm slug của một nhân vật và một ví dụ dựng sẵn ngay trên trang riêng của nhân vật đó, ở tab API.

{
  "model": "persona/senior-engineer",
  "messages": [{"role": "user", "content": "Review my code."}]
}

Streaming so với không streaming

Đặt stream: true để nhận token ngay khi chúng được tạo ra, giống hệt định dạng streaming của OpenAI (Server-Sent Events, kết thúc bằng [DONE]). Bỏ qua tham số này, hoặc đặt là false, để chờ phản hồi đầy đủ và nhận lại một phản hồi JSON duy nhất — đây là hành vi mặc định.

Lỗi

Lỗi tuân theo định dạng lỗi của OpenAI: {"error": {"message": "...", "type": "..."}}. Lỗi 401 nghĩa là khóa bị thiếu, không hợp lệ, hoặc đã bị thu hồi. Lỗi 400 nghĩa là bản thân yêu cầu không hợp lệ — thường gặp nhất là một mô hình không được nhận diện, một slug nhân vật chưa xuất bản/không xác định, hoặc một mô hình nằm ngoài danh sách cho phép của khóa bạn. Lỗi 502 nghĩa là không có mô hình ứng viên nào phản hồi.

{
  "error": {
    "message": "This API key may only use: llama-3.1-8b:free",
    "type": "invalid_request_error"
  }
}

Giới hạn tốc độ

Các yêu cầu API được tính vào cùng giới hạn tốc độ chat theo từng tài khoản như ứng dụng web — hiện tại không có hạn mức riêng cho lưu lượng API.