# API

> Các địa chỉ API của KONG API AI, cách xác thực, các header riêng (Idempotency-Key, X-Router-Session, X-GW-Customer) và cách tra cứu một yêu cầu.

Source: https://kongapiai.com/docs/api

## Địa chỉ gốc và xác thực

```text
https://kongapiai.com/v1
```

Gửi khoá trong header `Authorization: Bearer gw_live_…`. Các công cụ dùng định dạng Anthropic có thể gửi khoá trong header `x-api-key`.

## Các địa chỉ

| Phương thức | Địa chỉ | Dùng để |
| --- | --- | --- |
| POST | `/v1/chat/completions` | Hội thoại, định dạng OpenAI Chat Completions |
| POST | `/v1/responses` | Định dạng OpenAI Responses |
| POST | `/v1/messages` | Định dạng Anthropic Messages |
| GET | `/v1/models` | Các model mà khoá này được dùng |
| GET | `/v1/key` | Thông tin của chính khoá này: hạn mức, model, trạng thái |
| GET | `/v1/requests/{id}` | Trạng thái của một yêu cầu |
| DELETE | `/v1/requests/{id}` | Yêu cầu huỷ một yêu cầu đang chạy |

## Idempotency-Key

Gửi header `Idempotency-Key` với một mã duy nhất cho mỗi yêu cầu, ví dụ một UUID.

- Gửi lại cùng mã khi yêu cầu đã được nhận: API trả về `409` với mã `duplicate_request` và `request_id` của yêu cầu ban đầu. Nhà cung cấp không bị gọi lần hai.
- Gửi lại cùng mã với nội dung khác: API trả về `409` với mã `idempotency_conflict`.

Nếu bạn không gửi header này, KONG API AI tự sinh một mã, và mỗi lần gửi lại được coi là một yêu cầu mới.

## X-Request-ID

Mỗi câu trả lời có header `X-Request-ID`. Hãy ghi lại mã này trong log của bạn. Dùng nó để tra cứu:

```bash
curl https://kongapiai.com/v1/requests/REQUEST_ID \
  -H "Authorization: Bearer gw_live_…"
```

## X-Router-Session

Gửi header `X-Router-Session` kèm một mã cố định bất kỳ, ví dụ mã cuộc hội thoại. Các yêu cầu có cùng mã sẽ dùng cùng một nguồn AI. Việc này giúp một cuộc hội thoại dài không bị đổi nguồn giữa chừng.

## X-GW-Customer

Dùng khi một khoá phục vụ nhiều khách hàng của bạn. Xem [Tính mức dùng theo khách hàng](https://kongapiai.com/docs/customers).

## Giới hạn kích thước

Nội dung một yêu cầu tối đa 2 MB. Lớn hơn, API trả về `413` với mã `body_too_large`.
