# LLM-API — Hướng dẫn sử dụng

## 1. Thông tin kết nối

| Mục | Giá trị |
| --- | --- |
| API base URL cho SDK | `https://llm-api.io.vn/v1` |
| Tài liệu | `https://llm-api.io.vn/docs` |
| Xác thực | `Authorization: Bearer <API_KEY_CUA_BAN>` |
| Định dạng key | `gw_...`, do quản trị viên LLM-API cấp |
| Định dạng request | JSON, `Content-Type: application/json` |

Liên hệ người cung cấp dịch vụ để nhận key và danh sách model/quyền được cấp. Key là bí mật:
lưu ở biến môi trường phía backend, không commit vào Git hoặc nhúng vào mã frontend/browser.
User không cần tài khoản nhà cung cấp upstream, slug hay relay secret.

Các endpoint cơ bản được tài liệu hóa: `GET /v1/models` và `POST /v1/chat/completions`.
Các API khác như Responses/Embeddings chỉ sử dụng khi quản trị viên xác nhận hỗ trợ.

## 2. Bắt đầu với cURL

Đặt key thật của bạn, không giữ nguyên placeholder:

```bash
export LLM_API_KEY='gw_THAY_BANG_KEY_CUA_BAN'
```

Kiểm tra dịch vụ (không cần key; chỉ chứng minh gateway đang hoạt động):

```bash
curl https://llm-api.io.vn/healthz
```

Lấy danh sách model:

```bash
curl --max-time 30 https://llm-api.io.vn/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY"
```

Model ID phải đúng như danh sách trả về. Model xuất hiện trong danh sách không bảo đảm key
của bạn có quyền/quota sử dụng tất cả model. Nếu bị từ chối, gửi mã lỗi cho quản trị viên.
Gateway bỏ trường `owned_by` khỏi response. Model ID và nội dung model được giữ nguyên.

Gọi chat không streaming:

```bash
curl --max-time 120 https://llm-api.io.vn/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-terra",
    "messages": [
      {"role": "user", "content": "Xin chào! Hãy giới thiệu ngắn gọn."}
    ],
    "max_tokens": 256,
    "stream": false
  }'
```

Đọc nội dung câu trả lời tại `choices[0].message.content`. Trường `usage`, nếu có, phản ánh
token usage do upstream trả về; không tự suy ra giá tiền khi chưa có bảng giá được xác nhận.
`gpt-6.1-terra` là ví dụ đã được gọi thành công trong quá trình tích hợp; quyền sử dụng phụ
thuộc cấu hình tài khoản tại thời điểm gọi.

## 3. Streaming / SSE

```bash
curl -N --max-time 120 https://llm-api.io.vn/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-terra",
    "messages": [{"role": "user", "content": "Viết một lời chào ngắn."}],
    "max_tokens": 256,
    "stream": true
  }'
```

`-N` tắt buffering của cURL. Response là các sự kiện SSE `data: ...`; ghép nội dung từ
`choices[0].delta.content`. Với stream OpenAI-compatible, `data: [DONE]` đánh dấu kết thúc.
Không gọi `.json()` một lần cho toàn bộ response streaming. Stream có thể bị gián đoạn do
mạng, deadline hoặc upstream; xử lý trường hợp kết thúc không đầy đủ.

## 4. Python — OpenAI SDK

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLM_API_KEY"],
    base_url="https://llm-api.io.vn/v1",
    timeout=120.0,
    max_retries=0,
)

response = client.chat.completions.create(
    model="gpt-6.1-terra",
    messages=[{"role": "user", "content": "Xin chào!"}],
    max_tokens=256,
)
print(response.choices[0].message.content)

# Để streaming: thay lời gọi ở trên bằng:
# stream = client.chat.completions.create(
#     model="gpt-6.1-terra",
#     messages=[{"role": "user", "content": "Xin chào!"}],
#     max_tokens=256,
#     stream=True,
# )
# for chunk in stream:
#     if chunk.choices:
#         print(chunk.choices[0].delta.content or "", end="", flush=True)
```

## 5. Node.js / TypeScript — OpenAI SDK

```bash
npm install openai
```

Lưu ví dụ thành `example.mjs` và chạy `node example.mjs`:

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LLM_API_KEY,
  baseURL: "https://llm-api.io.vn/v1",
  timeout: 120_000,
  maxRetries: 0,
});

const response = await client.chat.completions.create({
  model: "gpt-6.1-terra",
  messages: [{ role: "user", content: "Xin chào!" }],
  max_tokens: 256,
});
console.log(response.choices[0].message.content);
```

Ví dụ streaming (thay lời gọi phía trên):

```javascript
const stream = await client.chat.completions.create({
  model: "gpt-6.1-terra",
  messages: [{ role: "user", content: "Xin chào!" }],
  max_tokens: 256,
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

SDK được đặt `max_retries=0` / `maxRetries: 0` trong ví dụ để tránh tự gửi lại inference
khi request trước có thể đã chạy. Nếu cần retry, hãy thiết kế chính sách theo loại lỗi.

## 6. Cấu hình ứng dụng hỗ trợ OpenAI-compatible

- Provider type: **OpenAI-compatible / Custom OpenAI**.
- Base URL: **`https://llm-api.io.vn/v1`**.
- API key: **key `gw_...` của bạn**.
- Model: ID được cấp quyền, ví dụ **`gpt-6.1-terra`**.

Không ghép `/v1` hai lần. Nếu ứng dụng yêu cầu URL endpoint đầy đủ, dùng
`https://llm-api.io.vn/v1/chat/completions`. Tài liệu này dành cho SDK/server-side;
gateway chưa bật CORS để gọi trực tiếp từ các website khác origin.

## 7. Mã lỗi thường gặp

| HTTP | Ý nghĩa / xử lý |
| --- | --- |
| 400 | Kiểm tra model, JSON và tham số mà model hỗ trợ |
| 401 | Thiếu/sai key, key bị khóa/hết hạn; cũng có thể là lỗi auth upstream, liên hệ quản trị viên nếu key vừa cấp vẫn lỗi |
| 402 | Key hết quota tổng input + output, có usage cần đối soát, hoặc upstream thiếu số dư; liên hệ người cấp key |
| 403 | Key không được phép dùng provider hoặc upstream từ chối quyền |
| 404 | Sai endpoint/provider; kiểm tra `/v1` và URL |
| 429 | Vượt giới hạn provider; giảm concurrency, tuân thủ `Retry-After` nếu có |
| 502/503/504 | Upstream hoặc gateway không phản hồi/gián đoạn; đừng tự retry vô hạn |
| 52x từ Cloudflare | Sự cố tunnel/kết nối/deadline; lưu thời điểm và Cloudflare Ray ID nếu có |

Khi cần hỗ trợ, gửi: model, endpoint, thời điểm + múi giờ, HTTP status, body lỗi đã xóa
thông tin nhạy cảm, `x-request-id` và `cf-ray` nếu có. Không gửi toàn bộ API key.

## 8. Hành vi cần biết

- Key user có thể được giới hạn provider, có hạn sử dụng hoặc bị thu hồi.
- Key dùng quota tổng input + output và một đơn giá chung, hiển thị bằng USD / 1M token (tỷ giá cố định 1 USD = 26.000 ₫); hỏi người cấp key về hạn mức và giá. Chi phí lịch sử giữ nguyên, request mới tính tổng token × đơn giá chung.
  Key có quota được gọi song song. Output tối đa có thể bị hạ về quota còn lại.
  Input được quyết toán sau khi upstream trả usage; request làm hết quota sẽ chặn request sau.
- Gateway yêu cầu usage cuối stream bằng `stream_options.include_usage=true` với Chat API.
  Nếu bạn huỷ request giữa chừng (bấm Stop), token được trừ theo ước lượng và key vẫn dùng tiếp được.
  Nếu upstream lỗi 5xx mà không rõ usage, key có quota có thể cần admin đối soát trước khi dùng tiếp.
- Khóa/thu hồi ngăn request mới; không đảm bảo dừng request đang chạy hoặc hủy phí upstream.
- Gateway không tự retry inference hoặc đổi model/provider giữa một stream.
- Deadline gateway mặc định 300 giây; SDK, tunnel và provider có thể có timeout ngắn hơn.
- Tham số tool calling, ảnh, reasoning và structured output tùy model; OpenAI-compatible
  không có nghĩa mọi model hỗ trợ mọi tính năng.
- Tài liệu này không cam kết giá, quota hoặc SLA; dùng thông tin do người cấp key xác nhận.
