> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiid.edu.kg/llms.txt
> Use this file to discover all available pages before exploring further.

# Quy ước gọi

> Hướng dẫn về xác thực, cấu trúc lỗi, các enum phổ biến và truy vấn tác vụ bất đồng bộ.

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

Tất cả các giao diện công khai mặc định sử dụng Bearer Token:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Địa chỉ cơ sở (Base URL):

```text theme={null}
https://api.aiid.edu.kg
```

Một số định dạng gốc hoặc API dành riêng cho mô hình tuy có đường dẫn khác nhau, nhưng vẫn dùng cùng cơ chế xác thực bằng API Key.

## Cấu trúc lỗi

Khi khắc phục sự cố các yêu cầu thất bại, hãy ưu tiên tập trung vào:

* Mã trạng thái HTTP
* `error.code`
* `error.message`

Cấu trúc điển hình:

```json theme={null}
{
  "error": {
    "code": "invalid_request_error",
    "message": "the reason why error occurred"
  }
}
```

## Các mã trạng thái thường gặp

| HTTP | Ý nghĩa                             | Khuyến nghị                                                  |
| ---- | ----------------------------------- | ------------------------------------------------------------ |
| 400  | Lỗi tham số yêu cầu                 | Kiểm tra các trường bắt buộc, tên mô hình, tham số đường dẫn |
| 401  | Xác thực thất bại                   | Kiểm tra xem API Key có hợp lệ không                         |
| 404  | Đường dẫn hoặc tác vụ không tồn tại | Kiểm tra đường dẫn truy vấn và ID tác vụ                     |
| 429  | Kích hoạt giới hạn lưu lượng        | Giảm tần suất hoặc thử lại                                   |
| 500  | Lỗi máy chủ                         | Ghi lại yêu cầu và thử lại hoặc liên hệ hỗ trợ               |

## Các Enum trạng thái thường dùng

Các Enum vai trò (Role) thường gặp:

* `system`
* `user`
* `assistant`

Các trạng thái tác vụ dài thường gặp:

* `queued`
* `running`
* `succeeded`
* `failed`
* `in_progress`
* `completed`

Các trường trạng thái được trả về bởi các giao diện video khác nhau có thể hơi khác nhau, nhưng ngữ nghĩa đều xoay quanh "Đang chờ / Đang chạy / Đã hoàn thành / Thất bại".

## Truy vấn tác vụ bất đồng bộ

Tài liệu công khai hiện tại chủ yếu tập trung vào việc "Chủ động truy vấn kết quả tác vụ

* `GET /v1/videos/{task_id}`
* `GET /v1/responses/{response_id}`
* `GET /api/v3/contents/generations/tasks/{task_id}`
* `GET /suno/fetch/{task_id}`
* `GET /ent/v2/tasks/{task_id}/creations`
* `GET /v1beta/{operation_name}`

Kiến nghị phía tích hợp:

* Thực hiện thử lại và trì hoãn (backoff) khi truy vấn tác vụ
* Lưu trữ bền vững `task_id` hoặc `operation_name`
* Truy vấn kết quả đóng vai trò là phương thức dự phòng để kiểm tra lại các tác vụ bất đồng bộ