# aicentos Tài liệu

> aicentos là nền tảng tổng hợp AI API cho lập trình viên và doanh nghiệp. Một API Key gọi OpenAI, Anthropic, Google, xAI và nhiều hơn nữa — nhiều tuyến dự phòng với chuyển đổi tự động, tỷ lệ khả dụng công khai theo thời gian thực, hỗ trợ hợp đồng và triển khai riêng.

Tệp này tổng hợp các tài liệu có tiếng Việt, kèm URL nguồn của từng trang.

[Mục lục tài liệu](https://docs.aicentos.com/vi/llms.txt)

# Định dạng Claude gốc

Nguồn: https://docs.aicentos.com/vi/api/chat/claude

Language: vi

Chat

`POST /messages`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung yêu cầu

`application/json`

Định nghĩa kiểu TypeScript

Sử dụng kiểu request body trong TypeScript

## Nội dung phản hồi

###

`application/json`

###

`application/json`

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/messages" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "model": "claude-sonnet-4-6",    "max_tokens": 256,    "messages": [      {        "role": "user",        "content": "Giới thiệu bản thân trong một câu"      }    ]  }'
```

```bash
{
  "id": "string",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "string"
    }
  ],
  "model": "string",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  }
}
```

```bash
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

```bash
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

---

# Chat văn bản Gemini

Nguồn: https://docs.aicentos.com/vi/api/chat/gemini/text

Language: vi

Chat — định dạng Gemini gốc

`POST /v1beta/models/{model}:generateContent`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Tham số path

model\*string

## Nội dung yêu cầu

`application/json`

Định nghĩa kiểu TypeScript

Sử dụng kiểu request body trong TypeScript

## Nội dung phản hồi

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1beta/models/gemini-2.0-pro:generateContent" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "contents": [      {        "role": "user",        "parts": [          {            "text": "Giới thiệu bản thân trong một câu"          }        ]      }    ]  }'
```

```bash
{
  "candidates": [
    {
      "content": {},
      "finishReason": "string",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0
  }
}
```

---

# Định dạng ChatCompletions

Nguồn: https://docs.aicentos.com/vi/api/chat/openai/chat-completions

Language: vi

Chat — định dạng OpenAI gốc

`POST /chat/completions`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung yêu cầu

`application/json`

Định nghĩa kiểu TypeScript

Sử dụng kiểu request body trong TypeScript

## Nội dung phản hồi

###

`application/json`

###

`application/json`

###

`application/json`

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/chat/completions" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "model": "gpt-4o-mini",    "messages": [      {        "role": "user",        "content": "Giới thiệu bản thân trong một câu"      }    ]  }'
```

```bash
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 0,
  "model": "string",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "system",
        "content": "string",
        "name": "string"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}
```

```bash
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

```bash
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

```bash
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

---

# Định dạng Responses

Nguồn: https://docs.aicentos.com/vi/api/chat/openai/responses

Language: vi

Chat — định dạng OpenAI gốc

`POST /responses`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung yêu cầu

`application/json`

Định nghĩa kiểu TypeScript

Sử dụng kiểu request body trong TypeScript

## Nội dung phản hồi

###

`application/json`

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/responses" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "model": "gpt-5",    "input": "Giới thiệu bản thân trong một câu"  }'
```

```bash
{
  "id": "string",
  "object": "response",
  "status": "completed",
  "output": [],
  "usage": {}
}
```

```bash
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

---

# Định dạng Gemini gốc

Nguồn: https://docs.aicentos.com/vi/api/images/nano-banana/gemini

Language: vi

Ảnh (Images) Nano Banana

`POST /v1beta/models/gemini-3-pro-image-preview:generateContent`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung yêu cầu

`application/json`

Định nghĩa kiểu TypeScript

Sử dụng kiểu request body trong TypeScript

## Nội dung phản hồi

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "contents": [      {        "role": "user",        "parts": [          {            "text": "Một chú capybara mặc bộ đồ phi hành gia lơ lửng trong không gian"          }        ]      }    ],    "generationConfig": {      "responseModalities": [        "IMAGE"      ]    }  }'
```

```bash
{
  "candidates": [
    {
      "content": {
        "role": "string",
        "parts": [
          {
            "text": "string",
            "inlineData": {
              "mimeType": "string",
              "data": "string"
            }
          }
        ]
      },
      "finishReason": "string",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0
  },
  "modelVersion": "string"
}
```

---

# Chỉnh sửa ảnh

Nguồn: https://docs.aicentos.com/vi/api/images/openai/edits

Language: vi

Ảnh (Images) — định dạng OpenAI gốc

`POST /images/edits`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung yêu cầu

`multipart/form-data`

Định nghĩa kiểu TypeScript

Sử dụng kiểu request body trong TypeScript

## Nội dung phản hồi

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/images/edits" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -F image="[    \"string\"  ]" \
  -F prompt="string"
```

```bash
{
  "created": 0,
  "background": "string",
  "output_format": "string",
  "size": "string",
  "data": [
    {
      "url": "string",
      "b64_json": "string"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}
```

---

# Tạo ảnh

Nguồn: https://docs.aicentos.com/vi/api/images/openai/generations

Language: vi

Ảnh (Images) — định dạng OpenAI gốc

`POST /images/generations`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung yêu cầu

`application/json`

Định nghĩa kiểu TypeScript

Sử dụng kiểu request body trong TypeScript

## Nội dung phản hồi

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/images/generations" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "model": "gpt-image-2",    "prompt": "A futuristic city skyline at sunset, neon lights, cinematic",    "size": "1024x1024",    "quality": "hd"  }'
```

```bash
{
  "created": 0,
  "background": "string",
  "output_format": "string",
  "quality": "string",
  "size": "string",
  "data": [
    {
      "url": "string",
      "b64_json": "string",
      "revised_prompt": "string"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "input_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 0
    },
    "output_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 0
    }
  }
}
```

---

# Định dạng Gemini gốc

Nguồn: https://docs.aicentos.com/vi/api/models/gemini

Language: vi

Mô hình (Models)

`GET /v1beta/models`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung phản hồi

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X GET "https://aicentos.com/v1beta/models" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

```bash
{
  "models": [
    {
      "name": "models/gemini-2.0-pro",
      "displayName": "string",
      "description": "string",
      "inputTokenLimit": 0,
      "outputTokenLimit": 0,
      "supportedGenerationMethods": [
        "string"
      ]
    }
  ]
}
```

---

# Định dạng OpenAI gốc

Nguồn: https://docs.aicentos.com/vi/api/models/openai

Language: vi

Mô hình (Models)

`GET /models`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung phản hồi

###

`application/json`

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X GET "https://aicentos.com/v1/models" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

```bash
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1715000000,
      "owned_by": "openai"
    }
  ]
}
```

```bash
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

---

# Dreamina · Tạo video

Nguồn: https://docs.aicentos.com/vi/api/videos/dreamina/create

Language: vi

> Gửi task tạo video Dreamina, trả về ID task và trạng thái ban đầu

Video (Videos) định dạng Dreamina

`POST /videos`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung yêu cầu

`application/json`

Định nghĩa kiểu TypeScript

Sử dụng kiểu request body trong TypeScript

## Nội dung phản hồi

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "model": "veo-3.1-fast-generate-preview",    "prompt": "DJ đang chơi đĩa nhạc",    "size": "1920x1080",    "seconds": "8"  }'
```

```bash
{
  "id": "string",
  "task_id": "string",
  "status": "queued"
}
```

---

# Dreamina · Lấy trạng thái task video

Nguồn: https://docs.aicentos.com/vi/api/videos/dreamina/get-task

Language: vi

> Truy vấn tiến độ và kết quả tạo video Dreamina theo ID task

Video (Videos) định dạng Dreamina

`GET /videos/{task_id}`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Tham số path

task\_id\*string

## Nội dung phản hồi

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X GET "https://aicentos.com/v1/videos/string" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

```bash
{
  "id": "string",
  "task_id": "string",
  "status": "queued",
  "progress": 0,
  "url": "string",
  "error": "string"
}
```

---

# Sora · Tạo video

Nguồn: https://docs.aicentos.com/vi/api/videos/sora/create

Language: vi

> Gửi task tạo video Sora, trả về ID task và trạng thái ban đầu; sau đó dùng ID task để truy vấn tiến độ

Video (Videos) Veo (tương thích OpenAI)

`POST /videos`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Nội dung yêu cầu

`application/json`

Định nghĩa kiểu TypeScript

Sử dụng kiểu request body trong TypeScript

## Nội dung phản hồi

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "model": "veo-3.1-fast-generate-preview",    "prompt": "DJ đang chơi đĩa nhạc",    "size": "1920x1080",    "seconds": "8"  }'
```

```bash
{
  "id": "string",
  "task_id": "string",
  "status": "queued"
}
```

---

# Sora · Lấy nội dung video

Nguồn: https://docs.aicentos.com/vi/api/videos/sora/get-content

Language: vi

> Sau khi task hoàn thành, lấy địa chỉ tệp video do Sora tạo theo ID task

Video (Videos) Veo (tương thích OpenAI)

`GET /videos/{task_id}/content`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Tham số path

task\_id\*string

## Nội dung phản hồi

###

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X GET "https://aicentos.com/v1/videos/string/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

```bash
{
  "url": "string",
  "expires_at": 0
}
```

---

# Sora · Lấy trạng thái task video

Nguồn: https://docs.aicentos.com/vi/api/videos/sora/get-task

Language: vi

> Truy vấn tiến độ tạo video Sora theo ID task, lấy trạng thái và nguyên nhân thất bại

Video (Videos) Veo (tương thích OpenAI)

`GET /videos/{task_id}`

## Xác thực

Lưu API Key vào biến môi trường `AICENTOS_API_KEY`; các ví dụ shell dùng giá trị của biến trong header `Authorization: Bearer`.

API Key lấy từ mục "Quản lý token" trong Console

Vị trí: `header`

## Tham số path

task\_id\*string

## Nội dung phản hồi

###

`application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X GET "https://aicentos.com/v1/videos/string" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

```bash
{
  "id": "string",
  "task_id": "string",
  "status": "queued",
  "progress": 0,
  "url": "string",
  "error": "string"
}
```

---

# Lỗi

Nguồn: https://docs.aicentos.com/vi/billing/errors

Language: vi

> Mã trạng thái HTTP, cấu trúc phản hồi lỗi, lỗi thường gặp và cách xử lý

aicentos dùng hoàn toàn **định dạng phản hồi lỗi của OpenAI**. Khi SDK ném lỗi, chỉ cần catch exception tương ứng.

## Cấu trúc phản hồi lỗi

Mọi phản hồi lỗi đều theo định dạng này:

```bash
{
  "error": {
    "message": "API Key của bạn không có quyền truy cập gpt-5",
    "type": "permission_denied",
    "code": "model_not_allowed",
    "param": "model"
  }
}
```

| Trường    | Ý nghĩa                                            |
| --------- | -------------------------------------------------- |
| `message` | Mô tả lỗi dễ đọc cho người                         |
| `type`    | Loại lỗi (xem bảng dưới)                           |
| `code`    | Mã lỗi chi tiết (dùng để xử lý trong chương trình) |
| `param`   | Tên trường gây lỗi (nếu có)                        |

## Bảng tra nhanh mã trạng thái HTTP

| Mã trạng thái | Loại                     | Nguyên nhân thường gặp                                                        |
| ------------- | ------------------------ | ----------------------------------------------------------------------------- |
| `400`         | `invalid_request_error`  | Sai định dạng body, tham số không hợp lệ, gõ sai tên model                    |
| `401`         | `authentication_error`   | Thiếu / sai / đã bị thu hồi API Key                                           |
| `402`         | `insufficient_quota`     | Không đủ số dư                                                                |
| `403`         | `permission_denied`      | Key bị vô hiệu hóa, mô hình chưa được cấp quyền, IP không nằm trong whitelist |
| `404`         | `not_found`              | Sai đường dẫn endpoint, sai ID mô hình                                        |
| `408`         | `request_timeout`        | Upstream timeout (thường là không phản hồi > 60s)                             |
| `413`         | `payload_too_large`      | Body quá lớn (ảnh, tệp)                                                       |
| `415`         | `unsupported_media_type` | Sai Content-Type                                                              |
| `422`         | `invalid_request_error`  | Body parse được nhưng sai ngữ nghĩa                                           |
| `429`         | `rate_limit_exceeded`    | Chạm rate limit, giảm tần suất request rồi thử lại                            |
| `500`         | `server_error`           | Lỗi nội bộ nền tảng (hiếm gặp)                                                |
| `502`         | `bad_gateway`            | Dịch vụ upstream gặp sự cố                                                    |
| `503`         | `service_unavailable`    | Upstream quá tải, nên thử lại sau                                             |
| `504`         | `gateway_timeout`        | Upstream phản hồi vượt thời hạn                                               |

## Lỗi thường gặp và cách xử lý

### 401 — Invalid API key

```bash
{ "error": { "message": "Incorrect API key provided", "type": "authentication_error" } }
```

**Danh sách cần kiểm tra**:

* Header `Authorization` có đúng định dạng `Bearer sk-xxx` không (chú ý có dấu cách)
* Key có bị dính dấu cách / xuống dòng khi sao chép từ Console không
* Key đã bị xóa / vô hiệu hóa / hết hạn chưa
* Có lỡ dùng key test trên môi trường production không

### 402 — Insufficient quota

```bash
{ "error": { "message": "Insufficient quota", "type": "insufficient_quota" } }
```

Nạp tiền → Console, mục "Quản lý ví". Bật [cảnh báo số dư](https://docs.aicentos.com/vi/billing/pricing#c%E1%BA%A3nh-b%C3%A1o-s%E1%BB%91-d%C6%B0) để tránh tái diễn.

### 403 — Model not allowed

```bash
{ "error": { "message": "Model gpt-5 not allowed for this key", "code": "model_not_allowed" } }
```

Khi tạo token đã tick whitelist "Mô hình khả dụng", model yêu cầu không nằm trong đó. Sửa cài đặt token hoặc đổi Key.

### 404 — Model not found

```bash
{ "error": { "message": "The model 'gpt-4-turbo-2024-04-09' does not exist", "code": "model_not_found" } }
```

ID mô hình bị gõ sai hoặc đã ngừng cung cấp. Vào [thị trường mô hình](https://aicentos.com/pricing) để xác nhận ID hiện đang khả dụng.

### 429 — Rate limit exceeded

Header phản hồi `Retry-After` cho biết bao nhiêu giây sau nên thử lại. Giảm mức đồng thời và tần suất request là sẽ phục hồi.

### 500 / 502 / 503 — Lỗi dịch vụ

Thường do upstream chập chờn. **Tự động thử lại 2-3 lần** thường là thành công. Nếu kéo dài quá 5 phút:

* Xem [trang trạng thái](https://status.aicentos.com) (nếu có)
* Liên hệ bộ phận hỗ trợ

### 408 / 504 — Timeout

Request quá 60s không phản hồi. Nguyên nhân thường gặp:

* Prompt quá dài khiến mô hình "suy nghĩ" vượt thời gian
* Chưa bật streaming (phản hồi dài nên thêm `stream: true`)

**Cách xử lý**:

* Rút ngắn prompt
* Bật streaming: `{ "model": "...", "messages": [...], "stream": true }`
* Chuyển sang mô hình nhanh hơn (ví dụ từ `gpt-4o` sang `gpt-4o-mini`)

## Ví dụ xử lý lỗi trong SDK

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"
```

### Python

```python
import os
from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(api_key=os.environ["AICENTOS_API_KEY"], base_url="https://aicentos.com/v1")

try:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "hi"}],
    )
except AuthenticationError:
    print("Sai Key")
except RateLimitError as e:
    print(f"Bị rate limit, thử lại sau {e.response.headers.get('Retry-After')}s")
except APIError as e:
    print(f"Lỗi API khác: {e.status_code} {e.message}")
```

### Node.js

```js
import OpenAI, { APIError } from 'openai';

const client = new OpenAI({
  apiKey: process.env.AICENTOS_API_KEY,
  baseURL: 'https://aicentos.com/v1',
});

try {
  const resp = await client.chat.completions.create({ ... });
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.code, err.message);
  }
}
```

## Khuyến nghị retry và giảm cấp

| Loại lỗi                              | Cách xử lý khuyến nghị                               |
| ------------------------------------- | ---------------------------------------------------- |
| `400` / `401` / `402` / `403` / `404` | **Không retry**, lỗi code / cấu hình, kiểm tra trước |
| `429`                                 | Retry theo `Retry-After`, backoff theo cấp số nhân   |
| `500` / `502` / `503` / `504` / `408` | Retry ngay 1-3 lần, cách nhau 1-5s                   |

SDK chính thức của OpenAI mặc định đã có chính sách retry hợp lý, **code production hãy dùng thẳng SDK, đừng tự fetch**.

---

# Các mô hình hỗ trợ

Nguồn: https://docs.aicentos.com/vi/billing/models-list

Language: vi

> Danh sách toàn bộ mô hình của Google / xAI / OpenAI / Anthropic / Alibaba / DeepSeek / Zhipu / Moonshot / MiniMax

aicentos đã tích hợp mô hình của OpenAI, Anthropic, Google, xAI, Alibaba Qwen, DeepSeek, Zhipu, Moonshot, MiniMax và các nhà cung cấp lớn khác, bao phủ chat, suy luận, code, ảnh, video, embedding...

## Nhà cung cấp và mô hình tiêu biểu

Danh sách nhà cung cấp và mô hình đang bán thay đổi theo việc thêm hoặc gỡ ở thượng nguồn; con số thực tế lấy theo chợ mô hình trực tiếp. Bảng dưới chỉ liệt kê mô hình tiêu biểu:

| Nhà cung cấp | Mô hình tiêu biểu                                       |
| ------------ | ------------------------------------------------------- |
| Google       | `gemini-3.8-flash`, `gemini-3.1-pro`, `nano-banana-2`   |
| xAI          | `grok-4.7`, `grok-4.6`, `grok-build-0.1`                |
| OpenAI       | `gpt-5.6-sol`, `gpt-6-astra`, `gpt-image-2.5`           |
| Anthropic    | `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-5` |
| Alibaba Qwen | `qwen3.8-max`, `qwen3-coder-plus`                       |
| DeepSeek     | `deepseek-v4-pro`, `deepseek-v4.1-flash`                |
| Zhipu        | `glm-5.3`, `glm-5.2`                                    |
| Moonshot     | `kimi-k3`, `kimi-k2.6`                                  |
| MiniMax      | `minimax-m3`, `minimax-m2.7`                            |

Danh sách mô hình thời gian thực đầy đủ và định giá lấy theo Console:

Thị trường mô hình

Thị trường mô hình hỗ trợ lọc theo **nhà cung cấp**, **nhóm token khả dụng**, **loại tính phí**, **nhãn**, và có thể chuyển đổi giữa dạng thẻ và dạng bảng.

[👉 Mở trang định giá mô hình](https://aicentos.com/pricing)

## Điền gì vào trường model khi dùng

Trường `model` điền **ID mô hình** (có thể sao chép một chạm trên từng thẻ ở trang định giá mô hình). Một số ví dụ phổ biến:

| Bạn muốn dùng        | Điền vào trường `model` |
| -------------------- | ----------------------- |
| Claude Opus mới nhất | `claude-opus-4-8`       |
| Claude Sonnet        | `claude-sonnet-5`       |
| Claude Haiku         | `claude-haiku-4-5`      |
| GPT flagship         | `gpt-5.6-sol`           |
| GPT tạo ảnh          | `gpt-image-2.5`         |
| Gemini Pro           | `gemini-3.1-pro`        |
| Gemini Flash         | `gemini-3.8-flash`      |
| Grok                 | `grok-4.7`              |
| DeepSeek             | `deepseek-v4-pro`       |
| Qwen                 | `qwen3.8-max`           |
| Zhipu GLM            | `glm-5.3`               |
| Kimi                 | `kimi-k3`               |
| MiniMax              | `minimax-m3`            |

## Xem khả dụng thời gian thực của mô hình

Các mô hình upstream của từng nhà có thể bảo trì hoặc bị rate limit không định kỳ. Trước khi tích hợp, hãy xem trước **bảng sức khoẻ mô hình** để biết tỷ lệ khả dụng và độ trễ gần đây của mô hình mục tiêu:

[👉 Xem giám sát trạng thái mô hình](https://docs.aicentos.com/status)

Mỗi vòng kiểm tra định kỳ, bảng sẽ ghi lại tỷ lệ khả dụng 1 giờ / 24 giờ / 7 ngày, độ trễ phản hồi và PING endpoint của từng mô hình; thất bại liên tiếp sẽ được tự động đánh dấu.

## Giới hạn mô hình khả dụng

Nếu bạn muốn một key chỉ gọi được một số mô hình nhất định, khi tạo **API Key** hãy tick chọn "**Mô hình khả dụng**" làm whitelist. Ví dụ demo Key dành cho bên ngoài chỉ mở `claude-haiku-4-5` và `gemini-3.8-flash`.

## Chưa tìm thấy mô hình bạn muốn?

Khi các nhà cung cấp upstream phát hành mô hình mới, chúng tôi sẽ tích hợp dần. Nếu mô hình bạn cần chưa có, hãy thông báo qua kênh liên hệ trong Console, hoặc theo dõi thông báo cập nhật trên [X / Twitter](https://x.com/aicentos).

---

# Tham chiếu giá chính thức

Nguồn: https://docs.aicentos.com/vi/billing/official-pricing

Language: vi

> Toàn bộ mô hình aicentos đã tích hợp, ứng với giá API chính thức của OpenAI / Anthropic / Google

Bảng dưới đây liệt kê **toàn bộ mô hình aicentos đã tích hợp**, giá là **giá API chính thức** do các nhà cung cấp công bố trên trang chủ (tính đến tháng 5 năm 2026).

* Đơn vị: **USD / mỗi 1M tokens** (ảnh, giọng nói, video được ghi chú riêng).
* "Đọc cache" là giá đầu vào khi trúng cache; Anthropic còn có thêm giá ghi cache (bằng 1.25× giá đầu vào chuẩn).
* Các biến thể như `-thinking` / `-nothinking` / phiên bản theo ngày / `-high/-low/-medium` của cùng một mô hình nền **có giá chính thức giống mô hình nền**, nên đã được gộp lại hiển thị.

>

Giá thực tế khi gọi qua aicentos thấp hơn giá chính thức rất nhiều, lấy theo hiển thị thời gian thực trên [trang định giá aicentos](https://docs.aicentos.com/vi/billing/pricing) và [thị trường mô hình](https://aicentos.com/pricing).

## OpenAI

### Dòng GPT-5.x

| Mô hình                                                                | Đầu vào chính thức | Đầu ra chính thức | Đọc cache |
| ---------------------------------------------------------------------- | ------------------ | ----------------- | --------- |
| `gpt-5`, `gpt-5-codex`, `gpt-5-chat-latest`                            | $1.25              | $10.00            | $0.125    |
| `gpt-5-mini`                                                           | $0.25              | $2.00             | $0.025    |
| `gpt-5-nano`                                                           | $0.05              | $0.40             | $0.005    |
| `gpt-5-pro`                                                            | $15.00             | $120.00           | —         |
| `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.1-codex-max`, `gpt-5.1-chat-latest` | $1.25              | $10.00            | $0.125    |
| `gpt-5.1-codex-mini`                                                   | $0.25              | $2.00             | $0.025    |
| `gpt-5.2`, `gpt-5.2-codex`, `gpt-5.2-chat-latest`                      | $1.75              | $14.00            | $0.175    |
| `gpt-5.2-pro`                                                          | $21.00             | $168.00           | —         |
| `gpt-5.3-codex`, `gpt-5.3-chat-latest`                                 | $1.75              | $14.00            | $0.175    |
| `gpt-5.4`                                                              | $2.50              | $15.00            | $0.25     |
| `gpt-5.4-mini`                                                         | $0.75              | $4.50             | —         |
| `gpt-5.4-nano`                                                         | $0.20              | $1.25             | —         |
| `gpt-5.4-pro`                                                          | $30.00             | $180.00           | —         |
| `gpt-5.5`                                                              | $5.00              | $30.00            | $0.50     |

>

Ngữ cảnh của GPT-5.x khoảng 400K (các dòng flagship 5.4 / 5.5 cao hơn). `-codex` là bản chuyên cho code, `-chat` là bản hội thoại, `-pro` là bản hiệu năng cao, giá chính thức như bảng trên.

### Dòng GPT-4o

| Mô hình                                            | Đầu vào chính thức | Đầu ra chính thức | Đọc cache |
| -------------------------------------------------- | ------------------ | ----------------- | --------- |
| `gpt-4o`, `gpt-4o-2024-08-06`, `gpt-4o-2024-11-20` | $2.50              | $10.00            | $1.25     |
| `gpt-4o-2024-05-13`                                | $5.00              | $15.00            | —         |
| `chatgpt-4o-latest`                                | $5.00              | $15.00            | —         |
| `gpt-4o-mini`, `gpt-4o-mini-2024-07-18`            | $0.15              | $0.60             | $0.075    |
| `gpt-4o-search-preview`                            | $2.50              | $10.00            | —         |
| `gpt-4o-mini-search-preview`                       | $0.15              | $0.60             | —         |

>

Ngữ cảnh 128K. `-search-preview` tính thêm phí tìm kiếm $10 / 1000 lượt truy vấn.

### Dòng GPT-4.1

| Mô hình                                   | Đầu vào chính thức | Đầu ra chính thức | Đọc cache | Ngữ cảnh |
| ----------------------------------------- | ------------------ | ----------------- | --------- | -------- |
| `gpt-4.1`, `gpt-4.1-2025-04-14`           | $2.00              | $8.00             | $0.50     | 1M       |
| `gpt-4.1-mini`, `gpt-4.1-mini-2025-04-14` | $0.40              | $1.60             | $0.10     | 1M       |
| `gpt-4.1-nano`, `gpt-4.1-nano-2025-04-14` | $0.10              | $0.40             | $0.025    | 1M       |

### GPT-4 / GPT-3.5 (bản cũ)

| Mô hình                                                                                       | Đầu vào chính thức | Đầu ra chính thức | Ngữ cảnh |
| --------------------------------------------------------------------------------------------- | ------------------ | ----------------- | -------- |
| `gpt-4.5-preview`, `gpt-4.5-preview-2025-02-27`                                               | $75.00             | $150.00           | 128K     |
| `gpt-4-turbo-2024-04-09`, `gpt-4-turbo-preview`, `gpt-4-0125-preview`, `gpt-4-vision-preview` | $10.00             | $30.00            | 128K     |
| `gpt-4-0613`                                                                                  | $30.00             | $60.00            | 8K       |
| `gpt-4-32k-0613`                                                                              | $60.00             | $120.00           | 32K      |
| `gpt-3.5-turbo`, `gpt-3.5-turbo-0125`                                                         | $0.50              | $1.50             | 16K      |
| `gpt-3.5-turbo-1106`                                                                          | $1.00              | $2.00             | 16K      |
| `gpt-3.5-turbo-instruct`                                                                      | $1.50              | $2.00             | 4K       |
| `gpt-3.5-turbo-16k`, `gpt-3.5-turbo-16k-0613`                                                 | $3.00              | $4.00             | 16K      |
| `gpt-3.5-turbo-0613`                                                                          | $1.50              | $2.00             | 4K       |
| `babbage-002`                                                                                 | $0.40              | $0.40             | 16K      |
| `davinci-002`                                                                                 | $2.00              | $2.00             | 16K      |

>

`gpt-4.5-preview` đã được OpenAI đánh dấu ngừng hỗ trợ, chỉ giữ lại làm tham chiếu giá lịch sử.

### Dòng mô hình suy luận o

| Mô hình                                                            | Đầu vào chính thức | Đầu ra chính thức | Đọc cache | Ngữ cảnh |
| ------------------------------------------------------------------ | ------------------ | ----------------- | --------- | -------- |
| `o1`, `o1-2024-12-17`, `o1-preview`, `o1-preview-2024-09-12`       | $15.00             | $60.00            | $7.50     | 200K     |
| `o1-mini`, `o1-mini-2024-09-12`                                    | $1.10              | $4.40             | $0.55     | 128K     |
| `o1-pro`, `o1-pro-2025-03-19`                                      | $150.00            | $600.00           | —         | 200K     |
| `o3`                                                               | $2.00              | $8.00             | $0.50     | 200K     |
| `o3-pro`, `o3-pro-2025-06-10`                                      | $20.00             | $80.00            | —         | 200K     |
| `o3-mini`, `o3-mini-2025-01-31` (bao gồm `-high`/`-low`/`-medium`) | $1.10              | $4.40             | $0.55     | 200K     |
| `o3-deep-research`                                                 | $10.00             | $40.00            | $2.50     | 200K     |
| `o4-mini`                                                          | $1.10              | $4.40             | $0.275    | 200K     |
| `o4-mini-deep-research`, `o4-mini-deep-research-2025-06-26`        | $2.00              | $8.00             | $0.50     | 200K     |

### Ảnh / Giọng nói / Thời gian thực

| Mô hình                                           | Giá chính thức                                                        |
| ------------------------------------------------- | --------------------------------------------------------------------- |
| `gpt-image-1`                                     | Đầu vào văn bản $5 / đầu vào ảnh $10 / đầu ra ảnh $40 (mỗi 1M tokens) |
| `gpt-image-1.5`                                   | Đầu vào văn bản $5 / đầu ra ảnh khoảng $30 (mỗi 1M tokens)            |
| `gpt-image-2`                                     | Chưa công bố chính thức, liên hệ để được báo giá                      |
| `dall-e-3`                                        | $0.040 / ảnh (chuẩn 1024×1024), $0.080 / ảnh (HD)                     |
| `dall-e-2`                                        | $0.016 \~ $0.020 / ảnh                                                |
| `gpt-4o-realtime-preview` (và bản theo ngày)      | Văn bản $5 / $20, đầu vào âm thanh $40 / đầu ra âm thanh $80          |
| `gpt-4o-mini-realtime-preview` (và bản theo ngày) | Văn bản $0.60 / $2.40, đầu vào âm thanh $10 / đầu ra $20              |
| `gpt-realtime-2`, `gpt-realtime-2025-08-28`       | Văn bản $4 / $16 + phí âm thanh tính riêng theo mức dùng              |
| `gpt-4o-audio-preview` (và bản theo ngày)         | Văn bản $2.50 / $10, đầu vào âm thanh $40 / đầu ra $80                |
| `gpt-4o-mini-audio-preview`                       | Văn bản $0.15 / $0.60, đầu vào âm thanh $10 / đầu ra $20              |
| `gpt-4o-mini-tts`                                 | Khoảng $0.015 / phút                                                  |

## Anthropic Claude

| Mô hình                                           | Đầu vào chính thức | Đầu ra chính thức | Ghi cache (5m) | Đọc cache | Ngữ cảnh |
| ------------------------------------------------- | ------------------ | ----------------- | -------------- | --------- | -------- |
| `claude-opus-4-7`, `claude-opus-4-7-thinking`     | $5.00              | $25.00            | $6.25          | $0.50     | 1M       |
| `claude-opus-4-6`, `claude-opus-4-6-thinking`     | $5.00              | $25.00            | $6.25          | $0.50     | 1M       |
| `claude-opus-4-5-20251101` (và `-thinking`)       | $5.00              | $25.00            | $6.25          | $0.50     | 200K     |
| `claude-opus-4-1-20250805` (và `-thinking`)       | $15.00             | $75.00            | $18.75         | $1.50     | 200K     |
| `claude-opus-4-20250514`                          | $15.00             | $75.00            | $18.75         | $1.50     | 200K     |
| `claude-sonnet-4-6`, `claude-sonnet-4-6-thinking` | $3.00              | $15.00            | $3.75          | $0.30     | 1M       |
| `claude-sonnet-4-5-20250929` (và `-thinking`)     | $3.00              | $15.00            | $3.75          | $0.30     | 1M       |
| `claude-sonnet-4-20250514` (và `-thinking`)       | $3.00              | $15.00            | $3.75          | $0.30     | 200K     |
| `claude-haiku-4-5-20251001` (và `-thinking`)      | $1.00              | $5.00             | $1.25          | $0.10     | 200K     |

>

Đọc cache của Anthropic thống nhất bằng **0.1×** giá đầu vào chuẩn (trúng cache rẻ hơn 90%); ghi cache là 1.25× (5 phút) hoặc 2× (1 giờ). Opus 4 / Sonnet 4 đã được nhà cung cấp đánh dấu ngừng hỗ trợ. Opus 4.7 dùng tokenizer mới, cùng một văn bản có thể tốn thêm khoảng 35% token.

## Google Gemini

| Mô hình                                                                | Đầu vào chính thức                                        | Đầu ra chính thức | Đọc cache       | Ngữ cảnh |
| ---------------------------------------------------------------------- | --------------------------------------------------------- | ----------------- | --------------- | -------- |
| `gemini-3.5-flash`                                                     | $1.50                                                     | $9.00             | $0.15           | 1M       |
| `gemini-3.1-pro-preview` (và `-customtools`/`-high`/`-low`/`-medium`)  | $2.00 / $4.00\*                                           | $12.00 / $18.00\* | $0.20 \~ $0.40  | 1M       |
| `gemini-3.1-flash-lite`, `gemini-3.1-flash-lite-preview`               | $0.25                                                     | $1.50             | $0.025          | 1M       |
| `gemini-3-pro-preview` (và `-thinking`)                                | $2.00 / $4.00\*                                           | $12.00 / $18.00\* | $0.20 \~ $0.40  | 1M       |
| `gemini-3-flash-preview` (và `-thinking`)                              | $0.50                                                     | $3.00             | $0.065          | 1M       |
| `gemini-2.5-pro` (và `-thinking`/`-nothinking`)                        | $1.25 / $2.50\*                                           | $10.00 / $15.00\* | $0.125 \~ $0.25 | 1M       |
| `gemini-2.5-flash` (và `-thinking`/`-nothinking`)                      | $0.30                                                     | $2.50             | $0.03           | 1M       |
| `gemini-2.5-flash-lite`                                                | $0.10                                                     | $0.40             | $0.01           | 1M       |
| `gemini-flash-latest`, `gemini-pro-latest`, `gemini-flash-lite-latest` | Giống mức hiện tại của Flash / Pro / Flash-Lite tương ứng |                   |                 | 1M       |
| `gemini-embedding-001`                                                 | $0.15                                                     | —                 | —               | —        |
| `gemini-embedding-2-preview`                                           | $0.20                                                     | —                 | —               | —        |

>

\*Dòng Gemini Pro tính giá theo hai mức dựa trên độ dài prompt: ≤200K tokens áp dụng giá thấp, >200K tokens áp dụng giá cao.

### Ảnh / Giọng nói / Video

| Mô hình                                                                                      | Giá chính thức                                                         |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `gemini-2.5-flash-image` (Nano Banana)                                                       | Đầu vào $0.30, đầu ra ảnh khoảng $30 / 1M tokens (khoảng $0.039 / ảnh) |
| `gemini-3-pro-image-preview`, `gemini-3.1-flash-image-preview`                               | Tính theo image token, khoảng $0.04 \~ $0.13 / ảnh                     |
| `gemini-2.5-flash-preview-tts`, `gemini-2.5-pro-preview-tts`, `gemini-3.1-flash-tts-preview` | Tổng hợp giọng nói, tính theo audio token                              |
| `veo-3.0-generate-001`, `veo-3.1-generate-preview`                                           | $0.40 / giây                                                           |
| `veo-3.0-fast-generate-001`, `veo-3.1-fast-generate-preview`                                 | $0.15 / giây                                                           |

# Tất cả giá trên đều là giá gốc chính thức của từng nhà cung cấp; gọi qua trung chuyển aicentos, giá rẻ hơn giá chính thức hơn 10 lần.

**Một API Key, truy cập được toàn bộ các mô hình trên.**[Đăng ký ngay →](https://aicentos.com/) ｜ [Xem giá thời gian thực của aicentos →](https://docs.aicentos.com/vi/billing/pricing)

---

# Thanh toán

Nguồn: https://docs.aicentos.com/vi/billing/pricing

Language: vi

> Nạp tiền và tính phí theo mức dùng — nạp qua Alipay, tính phí theo Token, tra cứu số dư và mức sử dụng

aicentos hoạt động theo mô hình **nạp trước + tính phí theo mức dùng**. Tiền nạp vào số dư Ví, mỗi request bị trừ phí theo mức tiêu thụ thực tế. Số dư được quy đổi bằng **nhân dân tệ ¥**.

Tài khoản mới đăng ký được tặng ngay **¥1** tín dụng dùng thử, chạy được request đầu tiên mà không cần nạp tiền.

## Nạp tiền

Console → **Ví** → "**Thêm tiền**":

Ví

### Các mốc nạp tiền

**Nạp từ ¥100 trở lên có chiết khấu, số tiền thực trả thấp hơn mức nạp**:

| Mức nạp              | Ưu đãi | Thực trả |
| -------------------- | ------ | -------- |
| ¥1 / ¥10 / ¥20 / ¥50 | Không  | Giá gốc  |
| ¥100                 | 1% OFF | ¥99      |
| ¥500                 | 2% OFF | ¥490     |
| ¥1,000               | 3% OFF | ¥970     |
| ¥10,000              | 5% OFF | ¥9,500   |

Ưu đãi được thể hiện trực tiếp trên số tiền thanh toán: nạp ¥500 thực trả ¥490, tiết kiệm ¥10. Cũng có thể nhập số tiền tùy ý, hoặc dùng mã đổi quà để nhận hạn mức.

Các mốc nạp tiền

### Phương thức thanh toán

Phương thức thanh toán

* **Alipay**: quét mã là trả, tiền về nhanh chóng
* Cũng có thể dùng **mã đổi quà** để nhận hạn mức
* Các kênh thanh toán khác lấy theo hiển thị thực tế trên trang Ví

### Thời hạn hiệu lực của hạn mức

**Số dư không bao giờ hết hạn**, cứ yên tâm nạp, đừng lo dùng không hết.

## Tính phí theo mức dùng

Mỗi API request bị trừ phí theo **số Token tiêu thụ thực tế**:

```bash
Phí = (Tokens đầu vào × đơn giá đầu vào + Tokens đầu ra × đơn giá đầu ra) × hệ số nhóm
```

* Mỗi mô hình có đơn giá đầu vào / đầu ra riêng, đơn vị thường là **per 1M tokens**
* **Hệ số nhóm** phụ thuộc vào nhóm mà key thuộc về, nhóm khác nhau có hệ số khác nhau
* Đơn giá và hệ số cụ thể lấy theo hiển thị thời gian thực trên [trang định giá mô hình](https://aicentos.com/pricing)

### Mô hình tính phí theo lượt

Các mô hình đa phương tiện như ảnh, video có thể tính phí theo **lượt** hoặc theo **tấm** thay vì theo Token, chi tiết lấy theo mô tả trên trang định giá mô hình.

## Tra số dư / mức tiêu thụ

Vào "**Ví**" ở menu bên trái của Console để xem số dư và tổng mức sử dụng:

| Chỉ số               | Ý nghĩa                       |
| -------------------- | ----------------------------- |
| **Số dư hiện tại**   | Hạn mức còn lại của tài khoản |
| **Tổng mức sử dụng** | Hạn mức đã tiêu thụ lũy kế    |
| **API request**      | Tổng số request đã gọi        |

Chi tiết tiêu thụ tinh hơn nằm trong "**Nhật ký sử dụng**": có thể lọc theo thời gian, mô hình, key; xem số Token và số tiền bị trừ của từng request. "**Dashboard**" cung cấp xu hướng gọi và thống kê hạn mức theo từng mô hình.

## Cảnh báo số dư

Console → **Hồ sơ cá nhân** → cài đặt thông báo, có thể đặt ngưỡng cảnh báo số dư. Khi số dư thấp hơn ngưỡng sẽ tự động nhận thông báo, tránh công việc bị gián đoạn giữa chừng vì hết số dư.

Ngưỡng tùy chọn và kênh thông báo cụ thể lấy theo hiển thị thực tế trong Console.

## Hoàn tiền và hóa đơn

* Số dư **không hoàn bằng tiền mặt**
* Trừ phí bất thường / gọi nhầm, sau khi bộ phận hỗ trợ xác minh có thể được bù hạn mức
* Số dư của tài khoản lâu không dùng **không hết hạn**
* Hóa đơn: khách hàng doanh nghiệp đã ký hợp đồng có thể được xuất hóa đơn; loại hóa đơn và quy trình cụ thể sẽ được xác nhận khi trao đổi thương mại

## Nhóm / hạn mức chia sẻ

Phân bổ hạn mức cho thành viên nhóm:

* Tạo key riêng cho từng thành viên trong mục "**API Key**"
* Đặt **giới hạn hạn mức** độc lập cho từng key
* Khi cần, dùng "**Mô hình khả dụng**" để giới hạn key đó được gọi những mô hình nào
* Kiểm toán mức tiêu thụ theo từng key trong "**Nhật ký sử dụng**"

## Thưởng giới thiệu

Console → **Ví** → **Chương trình giới thiệu**: mời bạn bè đăng ký, cả hai bên đều nhận thưởng. Người dùng đăng ký qua link giới thiệu riêng của bạn sẽ được liên kết với bạn, thưởng tích lũy có thể chuyển vào số dư bất cứ lúc nào.

Tỷ lệ thưởng cụ thể lấy theo mô tả thời gian thực trên trang Ví.

## Bước tiếp theo

* [Bắt đầu nhanh](https://docs.aicentos.com/vi/quickstart) — tích hợp ba bước, chạy được request đầu tiên
* [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list) — xem danh sách mô hình
* [Xử lý lỗi](https://docs.aicentos.com/vi/billing/errors) — xử lý lỗi hết số dư và các báo lỗi khác

---

# Amp

Nguồn: https://docs.aicentos.com/vi/clients/amp

Language: vi

> Dùng aicentos trong Amp —— ghi đè địa chỉ backend qua file cấu hình

Amp là agent lập trình do Sourcegraph phát hành, CLI và extension IDE dùng chung một bộ tài khoản và thiết lập. Nó không có ô nhập "Base URL tương thích OpenAI" thông thường, mà qua mục cấu hình `amp.url` trỏ toàn bộ backend về endpoint tùy chỉnh, credentials lưu riêng trong file secrets.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho Amp tại trang "API Key" trong Console (khuyến nghị đặt tên `amp-cli` để dễ theo dõi mức sử dụng):

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền khi hết số dư: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Mô hình  | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

Các mục thiết lập của Amp đều có tiền tố `amp.`, file cấu hình cấp người dùng nằm tại:

* macOS / Linux: `~/.config/amp/settings.json`
* Windows: `%USERPROFILE%\.config\amp\settings.json`

Tạo thư mục trước, rồi ghi địa chỉ backend vào:

```bash
mkdir -p ~/.config/amp ~/.local/share/amp
```

```json
{
  "amp.url": "https://aicentos.com/v1"
}
```

API Key không ghi trong file này, mà đặt riêng trong file secrets, tên khoá là `apiKey@<URL-của-bạn>`:

```json
{
  "apiKey@https://aicentos.com/v1": "sk-API-Key-của-bạn"
}
```

Sau khi cấu hình có hiệu lực, không cần chạy `amp login` nữa, yêu cầu sẽ đi thẳng endpoint bạn chỉ định. Nếu trước đó từng đăng nhập, khuyến nghị `amp logout` thoát trước rồi khởi động lại `amp`, tránh trạng thái đăng nhập còn sót ghi đè cấu hình.

Cũng có thể dùng biến môi trường để ghi đè tạm thời, phù hợp để xác minh một lần trước:

```bash
export AMP_URL="https://aicentos.com/v1"
export AMP_API_KEY="sk-API-Key-của-bạn"
```

**Lưu ý:** một khi đặt hai biến này, Amp sẽ bỏ qua quy trình đăng nhập, độ ưu tiên cao hơn file cấu hình.

## Kiểm tra

Trước gửi một yêu cầu nhẹ, xác nhận endpoint đã chuyển qua:

```bash
amp -x "Trả lời trong một câu: 1+1 bằng mấy"
```

Trả về bình thường nghĩa là cấu hình có hiệu lực. Nếu trả về 401, nhiều khả năng tên khoá trong file secrets không khớp hoàn toàn với `amp.url` (kể cả phần cuối có `/v1` hay không).

## Lưu ý

* Giao thức backend của Amp là giao diện quản lý riêng của nó, không phải giao thức tương thích OpenAI thông dụng, do đó `amp.url` bắt buộc trỏ đến endpoint đồng thời cung cấp giao diện phong cách Anthropic Messages (`/v1/messages`).
* aicentos cung cấp giao diện định dạng Claude gốc (xem [Định dạng Claude gốc](https://docs.aicentos.com/vi/api/chat/claude)) và giao diện tương thích OpenAI (xem [Chat Completions](https://docs.aicentos.com/vi/api/chat/openai/chat-completions)); Amp đi theo cái trước.
* Amp sẽ yêu cầu model ID cố định, nếu phía endpoint không có mô hình cùng tên, sẽ xảy ra fallback hoặc báo lỗi. Khi gặp trường hợp này, hãy lấy "Model Square" của Console làm chuẩn để đối chiếu tên mô hình.
* Thiết lập của extension IDE (VS Code / Cursor / Windsurf) được bảo trì tách riêng với CLI, cần điền riêng Amp URL và Amp API Key.
* `.amp/settings.json` trong workspace sẽ ghi đè thiết lập cấp người dùng; khi xử lý sự cố, trước tiên xác nhận trong thư mục hiện tại không có file cùng tên.

## Liên kết liên quan

* Tài liệu thiết lập chính thức: [https://ampcode.com/docs/cli/settings](https://ampcode.com/docs/cli/settings)

---

# Antigravity CLI

Nguồn: https://docs.aicentos.com/vi/clients/antigravity-cli

Language: vi

> Dùng aicentos trong Antigravity CLI —— kết nối qua chế độ API Key

Antigravity CLI là công cụ dòng lệnh do Google phát hành, hỗ trợ kết nối các dịch vụ tương thích Gemini API qua chế độ API Key. Tài liệu này giới thiệu cách cấu hình Antigravity CLI để dùng endpoint API tùy chỉnh.

## Cài đặt

Chọn cách cài tương ứng theo hệ điều hành:

### macOS / Linux

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

### Windows (PowerShell)

```powershell
irm https://antigravity.google/cli/install.ps1 | iex
```

### Windows (CMD)

```cmd
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
```

### Kiểm tra cài đặt

```bash
agy --version
```

## Cấu hình

### Bật chế độ API Key

Sửa `~/.gemini/antigravity-cli/settings.json`, thêm vào JSON hiện có:

```json
{
  "modelProvider": "gemini"
}
```

⚠️ **Lưu ý**: chỉ đặt `GEMINI_API_KEY` sẽ không chuyển cách xác thực. `modelProvider` bắt buộc đặt là `"gemini"` chữ thường.

### Thiết lập biến môi trường

```bash
export GOOGLE_GEMINI_BASE_URL="https://aicentos.com"
export GEMINI_API_KEY="your_api_key_here"
```

**Lưu ý quan trọng:**

* `GOOGLE_GEMINI_BASE_URL` điền địa chỉ gốc dịch vụ, đừng kèm đường dẫn API cụ thể. Endpoint bắt buộc phải tương thích Gemini API.
* `GEMINI_API_KEY` điền API Key của bạn.
* Chạy các lệnh trên trong cùng shell khởi động `agy`. CLI không đọc `.env` hay `GOOGLE_API_KEY`.

Khi cần hiệu lực vĩnh viễn, ghi hai dòng `export` vào `~/.zshrc` hoặc `~/.bashrc`.

## Khởi động và xác minh

```bash
agy --model gemini-2.0-flash
```

Sau khi trên cùng hiển thị `Gemini API key`, mở một hội thoại.

### Xử lý sự cố thường gặp

* **Vẫn yêu cầu đăng nhập**: kiểm tra `"modelProvider": "gemini"`, thoát và khởi động lại `agy`.
* **Khởi động báo thiếu Key**: đặt lại `GEMINI_API_KEY` trong shell hiện tại.
* **Yêu cầu thất bại**: kiểm tra API Key, địa chỉ gốc dịch vụ và quyền truy cập của mô hình đã chọn.

## Lưu ý

* Bắt buộc đặt đồng thời mục cấu hình `modelProvider` và biến môi trường mới dùng được chế độ API Key bình thường
* Biến môi trường cần đặt trong phiên shell khởi động CLI, hoặc ghi vào file cấu hình shell để có hiệu lực vĩnh viễn
* Endpoint dịch vụ bắt buộc phải tuân thủ chuẩn Gemini API

## Liên kết liên quan

* Tài liệu chính thức: [https://docs.aicentos.com/clients/antigravity-cli.html](https://docs.aicentos.com/clients/antigravity-cli.html)

---

# Antigravity

Nguồn: https://docs.aicentos.com/vi/clients/antigravity

Language: vi

> Google Antigravity hiện chưa hỗ trợ Base URL tùy chỉnh —— giải thích giới hạn và các phương án thay thế khả dụng

Antigravity là IDE agentic do Google ra mắt. Cần nói rõ một điểm trước: **bản chính thức của Antigravity desktop IDE không hỗ trợ API endpoint tùy chỉnh, cũng không cung cấp BYOK (mang key theo)**, bộ chọn mô hình chỉ là một danh sách cố định do Google duy trì, hiện không thể trỏ về aicentos.

Bài viết này trình bày căn cứ của giới hạn này, cách xác minh, cùng ba đường thay thế khả dụng.

## Vì sao không thể kết nối trực tiếp

Tài liệu về phương án tài khoản của Google nói rõ rằng Antigravity tạm chưa hỗ trợ tự mang mô hình hay tự mang endpoint. Một số mục cấu hình được truyền miệng trong cộng đồng (ví dụ ghi `antigravity.ai.provider`, `antigravity.openai-compatible.endpoint` vào `~/.antigravity/settings.json`) không phải là key được hỗ trợ chính thức, kiểm nghiệm thực tế cho thấy yêu cầu không được định tuyến tới endpoint tùy chỉnh, hoặc lặng lẽ rơi về mô hình mặc định, và bộ chọn mô hình cũng không xuất hiện mục tùy chỉnh.

Nói cách khác, vấn đề này không phải là "cấu hình viết sai", mà là phiên bản hiện tại chưa mở khả năng này. Trong `Settings → Models` của IDE cũng không có trường Base URL nào để điền.

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Mô hình  | tên mô hình trong "Model Square" của Console |

Bảng trên là tham số chung phía aicentos, dùng cho bất kỳ phương án thay thế nào dưới đây.

## Phương án thay thế

### Phương án một: đổi sang Antigravity CLI (khuyến nghị, chỉ giới hạn giao thức Gemini)

Công cụ dòng lệnh cùng tên `agy` hỗ trợ ghi đè endpoint, có thể kết nối qua `GOOGLE_GEMINI_BASE_URL` + `GEMINI_API_KEY`, nhưng chỉ nhận giao thức Gemini, chỉ gọi được các mô hình dòng Gemini. Các bước cụ thể xem tại [Kết nối Antigravity CLI](https://docs.aicentos.com/vi/clients/antigravity-cli).

Nếu nhu cầu của bạn là "dùng cách tương tác của Antigravity trong terminal", thì đây là đường tiết kiệm công nhất.

### Phương án hai: đóng gói mô hình cục bộ hoặc dịch vụ bên thứ ba thành công cụ MCP

Bảng Customizations của Antigravity hỗ trợ đăng ký MCP Server. Có thể đóng gói dịch vụ cục bộ thành công cụ MCP rồi gắn vào, dùng như một **công cụ có thể gọi**. Cần lưu ý: điều này không thay thế mô hình suy luận của IDE, mà chỉ cho agent thêm một công cụ.

### Phương án ba: nhánh cộng đồng hoặc proxy cục bộ

* Nhánh cộng đồng `open-antigravity` hỗ trợ mọi endpoint tương thích OpenAI và mô hình tùy chỉnh, là đường "sạch" nhất ngoài bản chính thức.
* Cũng có người dùng proxy chặn cục bộ để ghi đè lưu lượng đi ra của IDE. Đường này không có hỗ trợ chính thức, cấu hình mong manh, nâng cấp là mất tác dụng, không khuyến nghị dùng trong môi trường sản xuất.

## Kiểm tra

Dù chọn đường nào, trước tiên hãy dùng một câu prompt đơn giản xác nhận kết nối thông, rồi mới chính thức đưa vào sử dụng. Với loại tác vụ agent, khuyến nghị chạy thử trước trên một repo nhỏ.

## Lưu ý

* **Đừng coi "mục cấu hình có vẻ tồn tại" thành "tính năng dùng được"**. Các key `antigravity.*` trong IDE phần lớn là suy đoán của cộng đồng, ghi vào không báo lỗi nhưng cũng không có tác dụng.
* Nếu bạn cần giao thức tương thích OpenAI, hoặc muốn gọi các mô hình dòng Claude / GPT, bản desktop Antigravity hiện chưa đáp ứng được, hãy ưu tiên cân nhắc các client hỗ trợ Base URL tùy chỉnh như [Cursor](https://docs.aicentos.com/vi/clients/cursor), [Windsurf](https://docs.aicentos.com/vi/clients/windsurf).
* Antigravity CLI và desktop IDE là hai bộ cấu hình riêng biệt, việc ghi đè endpoint của CLI không ảnh hưởng tới IDE.
* Trước khi dùng bất kỳ nhánh bên thứ ba hay proxy nào, hãy tự đánh giá tính an toàn và tình hình bảo trì về sau của nó.

## Liên kết liên quan

* [Kết nối Antigravity CLI](https://docs.aicentos.com/vi/clients/antigravity-cli)

---

# Augment Code

Nguồn: https://docs.aicentos.com/vi/clients/augment-code

Language: vi

> Augment Code không mở endpoint tùy chỉnh, không thể đổi mô hình sang aicentos —— giải thích căn cứ và phương án thay thế

Augment Code là plugin lập trình cho VS Code / JetBrains / Vim, kèm CLI `auggie`. Nó **không hỗ trợ Base URL tùy chỉnh, cũng không cung cấp BYOK**: mô hình đến từ danh mục chính thức, tài khoản bắt buộc đăng nhập qua `auggie auth login`, yêu cầu không thể trỏ về aicentos.

## Vì sao không thể kết nối trực tiếp

* Trong file cấu hình không có các trường như `baseUrl`, `apiKey`, bảng cài đặt của plugin cũng không có ô nhập endpoint.
* CLI chỉ nhận hai biến môi trường liên quan: `AUGMENT_SESSION_AUTH` (trạng thái đăng nhập) và `AUGMENT_DISABLE_AUTO_UPDATE` (tắt tự động cập nhật), không có biến nào ghi đè endpoint.
* `--model` chỉ nhận tên trong danh mục mô hình chính thức (Claude, GPT, Gemini, GLM, Kimi...), điền tên mô hình bên thứ ba sẽ bị từ chối.
* Trong chỉ mục tài liệu chính thức `docs.augmentcode.com/llms.txt` không có mục nào về BYOK hay provider tùy chỉnh.

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Mô hình  | tên mô hình trong "Model Square" của Console |

Bảng trên là tham số chung phía aicentos, dùng cho bất kỳ phương án thay thế nào dưới đây.

## Phương án thay thế

### Phương án 1: Đổi sang agent lập trình hỗ trợ endpoint tùy chỉnh

[Craft Agent](https://docs.aicentos.com/vi/clients/craft-agent), [Gajae Code](https://docs.aicentos.com/vi/clients/gajae-code), [Oh My Pi](https://docs.aicentos.com/vi/clients/oh-my-pi) đều là agent lập trình trong terminal, trong cấu hình có thể ghi trực tiếp `baseUrl`.

### Phương án 2: Ở lại VS Code, đổi plugin

[Cline](https://docs.aicentos.com/vi/clients/cline), [Roo Code](https://docs.aicentos.com/vi/clients/roo-code), [Kilo](https://docs.aicentos.com/vi/clients/kilo) đều hỗ trợ provider tương thích OpenAI, có thể điền trực tiếp `https://aicentos.com/v1`.

### Phương án 3: Chỉ chuyển các tác vụ hàng loạt

Nếu nhóm của bạn đã mua gói đăng ký Augment mà vẫn tiếc trải nghiệm gợi ý hoàn thành của nó, có thể giữ mô hình chính thức cho việc chỉnh sửa hàng ngày, và chuyển các tác vụ tái cấu trúc hàng loạt, tác vụ dạng script sang chạy trên CLI hỗ trợ endpoint tùy chỉnh.

## Kiểm tra

Sau khi đổi sang một client thay thế bất kỳ, trước tiên dùng một câu prompt đơn giản xác nhận kết nối thông, rồi xem mức sử dụng trong Console có được ghi vào Key mới không.

## Lưu ý

* Trên mạng có hướng dẫn ghi các khóa như `augment.modelProvider: "openai-compatible"`, `augment.baseUrl`, `augment.apiKeyEnv`. Trong cấu hình chính thức không tồn tại, ghi vào không báo lỗi cũng không có hiệu lực, `--model` vẫn chỉ nhận danh mục chính thức.
* Đừng coi "mục cấu hình không báo lỗi" là "cấu hình đã có hiệu lực". Cách kiểm chứng là hỏi nó tên mô hình hiện tại, rồi đối chiếu với danh mục chính thức.
* Chỉ mục cloud và gợi ý hoàn thành của Augment không có phương án thay thế tương đương, đổi client là đổi cả bộ quy trình làm việc, khuyến nghị thử trên một repo nhỏ trước.

## Liên kết liên quan

* [Tài liệu Augment Code CLI](https://docs.augmentcode.com/cli/overview)

---

# CC Switch

Nguồn: https://docs.aicentos.com/vi/clients/cc-switch

Language: vi

> Nhập cấu hình từ Console aicentos vào CC Switch chỉ với một cú nhấp, quản lý Claude Code / Codex / Gemini CLI

CC Switch là công cụ quản lý cấu hình AI CLI đa nền tảng, dùng để quản lý tập trung cấu hình nhà cung cấp mô hình (Provider) của các công cụ như Claude Code, Codex, Gemini CLI, cho phép bạn chuyển đổi chỉ với một cú nhấp giữa nhiều công cụ CLI hoặc nhiều bộ cấu hình, không phải sửa đi sửa lại biến môi trường.

Console aicentos tích hợp sẵn **nhập CC Switch một chạm**: không cần chép tay Base URL và key, chỉ vài cú nhấp là cấu hình được ghi vào CC Switch.

## Chuẩn bị

1. Đăng nhập [Console aicentos](https://aicentos.com/)
2. Xác nhận tài khoản còn số dư (đăng ký tặng ¥1 tín dụng dùng thử, dùng hết thì nạp tại "**Ví**")
3. Cài CC Switch (xem dưới)

## Cài đặt CC Switch

CC Switch là dự án mã nguồn mở, mã nguồn lưu trữ trên GitHub: [farion1231/cc-switch](https://github.com/farion1231/cc-switch).

Mở [trang Releases](https://github.com/farion1231/cc-switch/releases), trong danh sách tài nguyên của bản mới nhất, chọn gói cài đặt tương ứng theo hệ điều hành của bạn:

* macOS: `.dmg`
* Windows: `.msi`
* Linux: `.AppImage` / `.deb`

Sau khi tải xong, cài theo cách bình thường của hệ điều hành, và **mở CC Switch ít nhất một lần**, để liên kết nhập của Console nhận diện được máy này đã cài.

## Nhập một chạm (khuyến nghị)

### Bước 1: Bắt đầu nhập từ Console

Vào "**API Key**" ở bên trái Console, ở dòng key muốn dùng nhấn "**⋯**" bên phải, trong menu chọn "**CC Switch**":

Chọn CC Switch trong danh sách API Key

### Bước 2: Chọn ứng dụng và mô hình

Trong hộp thoại "**Điền vào CC Switch**", chọn ứng dụng đích (Claude / Codex / Gemini) và xác nhận mô hình muốn dùng:

Điền cấu hình vào CC Switch

| Trường                 | Mô tả                                                                                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ứng dụng               | Chọn cấu hình của CLI nào sẽ được ghi vào. **Claude** đi giao thức Anthropic, **Codex** đi định dạng tương thích OpenAI, **Gemini** đi định dạng gốc Gemini |
| Tên                    | Tên cấu hình hiển thị trong CC Switch sau khi nhập, có thể tự đặt                                                                                           |
| Mô hình chính          | Mô hình mặc định của cấu hình này, bắt buộc                                                                                                                 |
| Mô hình Haiku / Sonnet | Các mô hình phân cấp trong ứng dụng Claude, chỉ định theo nhu cầu                                                                                           |

Tên mô hình có thể tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list), ví dụ `claude-opus-4-8`, `claude-sonnet-5`, `claude-haiku-4-5`.

Chọn xong nhấn "**Mở CC Switch**".

### Bước 3: Xác nhận khởi chạy trên trình duyệt

Trình duyệt sẽ hỏi có mở CC Switch không, nhấn "**Mở CC Switch.app**":

Trình duyệt hỏi mở CC Switch

> Nếu tích "Luôn cho phép aicentos.com mở loại liên kết này trong ứng dụng liên quan", các lần nhập sau sẽ không còn hiện hộp xác nhận này.

### Bước 4: Xác nhận nhập trong CC Switch

CC Switch sẽ hiện "**Xác nhận nhập cấu hình nhà cung cấp**", kiểm tra thông tin rồi nhấn "**Nhập**":

CC Switch xác nhận nhập

Hộp thoại sẽ liệt kê endpoint, key và các mô hình phân cấp sẽ được ghi, kiểm tra không sai rồi nhấn "**Nhập**".

Sau khi nhập xong, `aicentos Claude` sẽ xuất hiện trong danh sách cấu hình của CC Switch, nhấn một cái là chuyển được:

Nhập hoàn tất

## Cấu hình thủ công

Nếu không muốn dùng nhập một chạm, cũng có thể trong CC Switch nhấn "**Thêm nhà cung cấp mới**" rồi điền thủ công:

CC Switch thêm nhà cung cấp mới

| Trường           | Điền gì                                                                           |
| ---------------- | --------------------------------------------------------------------------------- |
| Tên nhà cung cấp | `aicentos` (tự đặt, miễn dễ nhận diện)                                            |
| API Key          | Key tạo tại trang "**API Key**" của Console, dạng `sk-xxxxxxxx`                   |
| Địa chỉ yêu cầu  | Claude / Gemini điền `https://aicentos.com`; Codex điền `https://aicentos.com/v1` |

> **Giao thức Anthropic chỉ điền địa chỉ gốc**, đừng thủ công thêm `/v1/messages`, client sẽ tự nối.

## Bước tiếp theo

* [Giám sát trạng thái mô hình](https://docs.aicentos.com/status) — xem tỷ lệ khả dụng thời gian thực của từng mô hình
* [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list) — xem danh sách đầy đủ mô hình và ID
* [Thanh toán](https://docs.aicentos.com/vi/billing/pricing) — tìm hiểu nạp tiền và tính phí theo lượng

---

# Chatbot UI

Nguồn: https://docs.aicentos.com/vi/clients/chatbot-ui

Language: vi

> Dùng aicentos trong Chatbot UI —— kết nối qua cài đặt OpenAI tương thích tùy chỉnh

Chatbot UI là một web frontend mã nguồn mở theo phong cách ChatGPT, hỗ trợ giao diện OpenAI tương thích tùy chỉnh.

## Cấu hình triển khai tự lưu trữ

Với bản tự lưu trữ, cấu hình giao diện tùy chỉnh qua biến môi trường:

```bash
OPENAI_API_KEY=codex_your_api_key
OPENAI_API_HOST=https://aicentos.com/v1
```

Sau khi cấu hình xong, khởi động lại dịch vụ là giao diện mới có hiệu lực. Sau khi thiết lập biến môi trường, các ô nhập tương ứng trong giao diện UI sẽ bị vô hiệu hóa (đề phòng rò rỉ cấu hình trên bản dùng chung).

## Cấu hình giao diện UI

Với bản không giới hạn cài đặt UI, điền trong bảng cài đặt:

* **OpenAI API Key**: Key của bạn dạng `codex_...` hoặc `sk-...`
* **OpenAI API Host / Base URL**: `https://aicentos.com/v1`

## Lưu ý

* Chatbot UI cần kết hợp Supabase để triển khai xác thực và lưu trữ dữ liệu
* API Host điền đường dẫn gốc của dịch vụ có kèm `/v1`
* Mô hình khả dụng lấy theo danh sách trả về của `GET /v1/models`

## Liên kết liên quan

* GitHub: [https://github.com/mckaywrigley/chatbot-ui](https://github.com/mckaywrigley/chatbot-ui)

---

# Chatbox

Nguồn: https://docs.aicentos.com/vi/clients/chatbox

Language: vi

> Dùng aicentos trong Chatbox —— kết nối qua cài đặt OpenAI tương thích tùy chỉnh

Chatbox là một AI client desktop hỗ trợ giao diện OpenAI tương thích, có thể kết nối tới dịch vụ hiện tại qua chế độ "OpenAI API Compatible".

## Mở cài đặt

Nhấn vào biểu tượng **Cài đặt (Settings)** trên thanh bên trái, chuyển sang tab **Mô hình (Model)**.

## Chọn nhà cung cấp AI

Trong dropdown **Model Provider**, chọn `OpenAI API Compatible` (tương thích OpenAI API).

## Cấu hình cần điền

Điền các trường sau:

| Trường          | Nội dung điền                                 |
| --------------- | --------------------------------------------- |
| API Key         | Key của bạn dạng `codex_...` hoặc `sk-...`    |
| API Host        | `https://aicentos.com`                        |
| Mô hình (Model) | `gpt-5-codex-mini` hoặc mô hình khả dụng khác |

**Lưu ý:** Trường **API Host** của Chatbox chỉ điền địa chỉ gốc của dịch vụ, **đừng** thêm hậu tố `/v1`. Ví dụ điền: `https://aicentos.com`

## Kiểm tra

Sau khi lưu, tạo một cuộc hội thoại, xác nhận có phản hồi bình thường.

## Lưu ý

* API Host điền đường dẫn gốc của dịch vụ không kèm `/v1`, Chatbox sẽ tự nối đường dẫn API
* Mô hình khả dụng lấy theo danh sách trả về của `GET /v1/models`

## Liên kết liên quan

* Tài liệu chính thức: [https://docs.chatboxai.app/en/guides/providers](https://docs.chatboxai.app/en/guides/providers)

---

# Cherry Studio

Nguồn: https://docs.aicentos.com/vi/clients/cherry-studio

Language: vi

> Dùng aicentos trong Cherry Studio —— thêm nhà cung cấp OpenAI tương thích để dùng toàn bộ mô hình

Cherry Studio hỗ trợ nhà cung cấp mô hình OpenAI tương thích tùy chỉnh, sau khi thêm aicentos là có thể dùng toàn bộ mô hình aicentos tích hợp ngay trong ứng dụng.

## Thông tin cần chuẩn bị

| Trường                 | Giá trị                                             |
| ---------------------- | --------------------------------------------------- |
| Tên nhà cung cấp       | `aicentos`                                          |
| Địa chỉ API (Base URL) | `https://aicentos.com/v1`                           |
| API Key                | Tạo trong Console của aicentos                      |
| Tên mô hình            | tên mô hình đầy đủ trong "Model Square" của Console |

Các bước lấy API Key xem tại [Bắt đầu nhanh](https://docs.aicentos.com/vi/quickstart).

## Các bước thiết lập

* Mở cài đặt Cherry Studio, vào **Dịch vụ mô hình / Quản lý nhà cung cấp**.
* Thêm một nhà cung cấp **OpenAI tương thích** mới.
* Tên nhà cung cấp điền `aicentos`.
* Điền API Key và địa chỉ API `https://aicentos.com/v1`.
* Lưu cấu hình, nếu có nút "Kiểm tra / Test connection" thì nhấn để xác minh.

### Thêm mô hình

Nếu không tự nhận diện được mô hình, có thể thêm tên mô hình thủ công.

>

Tên mô hình phải copy đầy đủ, chữ hoa chữ thường, dấu gạch ngang, hậu tố ngày tháng đều không được thay đổi, lấy theo [Model Square](https://aicentos.com/pricing) / [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list).

## Kiểm tra và xử lý sự cố

Gửi một tin nhắn kiểm tra để xác nhận kết nối thông, ví dụ:

```bash
Xin chào, hãy giới thiệu bản thân trong một câu.
```

Các vấn đề thường gặp:

* **Lỗi xác thực**: kiểm tra API Key có khoảng trắng thừa không.
* **Timeout**: kiểm tra mạng hoặc trạng thái dịch vụ.
* **Mô hình không khả dụng**: dùng tên mô hình đầy đủ trong Console.
* **Hội thoại thất bại**: xác nhận đã chọn nhà cung cấp aicentos này.

---

# Claude Code

Nguồn: https://docs.aicentos.com/vi/clients/claude-code

Language: vi

> Cài đặt Claude Code từ đầu và kết nối aicentos —— môi trường Node.js, cài đặt trên Windows / Mac, biến môi trường và cấu hình CC Switch, kèm hướng dẫn Termux trên điện thoại

Claude Code tương thích giao thức Anthropic, chỉ cần trỏ Base URL về aicentos và điền API Key của bạn là có thể dùng toàn bộ các mô hình Claude mà aicentos đã tích hợp.

## Bước 1: Cài đặt Claude Code

### Cài môi trường Node.js

Truy cập [trang chủ Node.js](https://nodejs.org/) để tải bản LTS mới nhất, hãy tải gói cài đặt phù hợp với hệ điều hành của bạn.

Tải Node.js từ trang chủ

Sau khi cài xong, mở terminal (trên Windows dùng git bash hoặc cmd), nhập:

```bash
node -v
```

Thấy số phiên bản tức là cài đặt thành công.

### Cài đặt Claude Code

Trước khi cài, hãy xác nhận môi trường Node.js ở trên đã được thiết lập xong.

**Windows:** Nhấn `Win + R`, nhập `cmd` rồi Enter để mở terminal, thực hiện:

```bash
npm install -g @anthropic-ai/claude-code
```

**Mac / Linux:** Chạy trong terminal:

```bash
npm install -g @anthropic-ai/claude-code
```

Hoặc dùng script curl được trang chính thức khuyến nghị:

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Sau khi cài xong, kiểm tra xem có thành công không:

```bash
claude --version
```

Xuất hiện số phiên bản tức là cài đặt thành công.

claude --version cài đặt thành công

## Bước 2: Lấy API Key

Truy cập Console trên [trang chủ aicentos](https://aicentos.com/) để tạo API Key của bạn.

Các bước tạo key chi tiết xem tại [Bắt đầu nhanh](https://docs.aicentos.com/vi/quickstart).

## Bước 3: Cấu hình kết nối

Dưới đây có hai cách: **quản lý tập trung bằng CC Switch chỉ với một cú nhấp** (khuyến nghị), hoặc **tự cấu hình thủ công**.

### Cách 1: Dùng CC Switch (khuyến nghị)

Nếu bạn cần chuyển đổi thường xuyên giữa nhiều Provider, nhiều công cụ CLI, nên dùng CC Switch để quản lý cấu hình tập trung, không cần sửa đi sửa lại biến môi trường.

Xem chi tiết tại [Kết nối CC Switch →](https://docs.aicentos.com/vi/clients/cc-switch)

### Cách 2: Cấu hình thủ công

Nếu không muốn cài thêm công cụ, chỉ cần cấu hình biến môi trường trực tiếp. Chọn một trong ba cách.

#### Hiệu lực tạm thời (phiên terminal hiện tại)

Phù hợp để thử nhanh, chỉ có hiệu lực trong cửa sổ terminal hiện tại:

```bash
export ANTHROPIC_BASE_URL="https://aicentos.com"
export ANTHROPIC_AUTH_TOKEN="sk-API-Key-của-bạn"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude
```

Một số phiên bản nếu không nhận diện `ANTHROPIC_AUTH_TOKEN`, dùng thay thế:

```bash
export ANTHROPIC_API_KEY="sk-API-Key-của-bạn"
```

#### Lưu lâu dài (file cấu hình, cách thủ công được khuyến nghị)

Sửa `~/.claude/settings.json`, ghi vào:

```bash
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://aicentos.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-API-Key-của-bạn",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}
```

**Windows** cũng có thể trong "Biến môi trường hệ thống" → "Biến người dùng" nhấn "Mới", lần lượt tạo hai biến sau:

| Tên biến               | Giá trị                |
| ---------------------- | ---------------------- |
| `ANTHROPIC_BASE_URL`   | `https://aicentos.com` |
| `ANTHROPIC_AUTH_TOKEN` | key đã tạo ở Bước 2    |

Sau khi lưu, khởi động lại Claude Code để có hiệu lực.

#### Ghi vào cấu hình Shell (hiệu lực toàn cục)

Thêm biến môi trường vào `~/.zshrc` hoặc `~/.bashrc`:

```bash
nano ~/.zshrc
```

Thêm vào cuối file:

```bash
# API Key của aicentos (key đã tạo ở Bước 2)
export ANTHROPIC_AUTH_TOKEN="key-của-bạn"

# Base URL của aicentos
export ANTHROPIC_BASE_URL="https://aicentos.com"
```

Lưu và thoát, rồi thực hiện `source ~/.zshrc` (hoặc mở lại terminal) để có hiệu lực.

## Bước 4: Chạy Claude Code

Vào thư mục dự án của bạn và khởi động:

```bash
cd /path/to/your/project
claude
```

## Chỉ định mô hình

Khi khởi động, dùng `--model` để chỉ định mô hình cụ thể:

```bash
claude --model claude-opus-4-7
```

Tên mô hình lấy theo danh sách trong "Model Square" của Console aicentos, có thể tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list).

## Các lệnh thường dùng

| Lệnh                      | Công dụng                                                      |
| ------------------------- | -------------------------------------------------------------- |
| `/add-dir`                | Thêm thư mục làm việc bổ sung                                  |
| `/resume`                 | Quay lại hội thoại lịch sử                                     |
| `/clear`                  | Xoá lịch sử hội thoại                                          |
| `/compact [instructions]` | Nén hội thoại, có thể cung cấp hướng dẫn trọng tâm nếu muốn    |
| `/config`                 | Xem / sửa cấu hình                                             |
| `/cost`                   | Hiển thị thống kê sử dụng token                                |
| `/doctor`                 | Kiểm tra tình trạng cài đặt Claude Code                        |
| `/help`                   | Xem hướng dẫn sử dụng                                          |
| `/init`                   | Khởi tạo dự án với hướng dẫn CLAUDE.md                         |
| `/login`                  | Chuyển tài khoản Anthropic                                     |
| `/logout`                 | Đăng xuất khỏi tài khoản Anthropic                             |
| `/mcp`                    | Quản lý kết nối máy chủ MCP và xác thực OAuth                  |
| `/memory`                 | Sửa file bộ nhớ CLAUDE.md                                      |
| `/model`                  | Chọn hoặc đổi mô hình AI                                       |
| `/permissions`            | Xem hoặc cập nhật quyền                                        |
| `/pr_comments`            | Xem bình luận pull request                                     |
| `/review`                 | Yêu cầu review code                                            |
| `/status`                 | Xem trạng thái tài khoản và hệ thống                           |
| `/terminal-setup`         | Cài binding phím Shift+Enter xuống dòng (chỉ iTerm2 và VSCode) |
| `/vim`                    | Vào chế độ vim, chuyển giữa chế độ insert và command           |

## Chạy trên điện thoại (Termux + Ubuntu)

Phù hợp cho tình huống "không mang laptop, ra đường cần sửa gấp một bug, hay muốn vibe một chút trên đường đi làm". Không cần root, không cần flash máy, toàn bộ thực hiện trong Termux. Làm trọn bộ hết khoảng 10–20 phút, tuỳ tốc độ mạng.

### Bạn sẽ có được

* Một môi trường **Ubuntu** chạy ngay trong điện thoại (không ảnh hưởng hệ thống, không chiếm nhiều dung lượng)
* Công cụ dòng lệnh **Claude Code** bản đầy đủ (giống hệt bản trên máy tính)
* Kết nối chi phí thấp qua **aicentos**, chuyển Opus / Sonnet / Haiku trong một giây

### Chuẩn bị

Chỉ cần hai thứ:

* **Một chiếc điện thoại Android** (iOS không cài được Termux, hướng dẫn này không áp dụng)
* **Một tài khoản [aicentos](https://aicentos.com) + API Key** ([Nạp tiền vào Ví →](https://aicentos.com/wallet), [Tạo Key →](https://aicentos.com/keys))

**Đừng cài Termux từ Google Play**, bản đó quá cũ và không còn được bảo trì, sẽ không cài được các script phía sau. Hãy tải bản mới nhất từ [F-Droid](https://f-droid.org/packages/com.termux/) hoặc [Termux GitHub Releases](https://github.com/termux/termux-app/releases).

### Bước 1: Cài script một chạm tmoe-linux

Mở Termux, chờ dấu nhắc lệnh xuất hiện (một dòng `~ $`), copy **cả dòng** dưới đây vào rồi Enter:

```bash
. <(curl -L l.tmoe.me)
```

>

Đây là mirror dành riêng cho người dùng Trung Quốc đại lục, người dùng ở nước ngoài dùng `. <(curl -L git.io/linux.sh)`.

Chạy xong sẽ hiện ra một **menu đồ hoạ**, trông như thế này:

Menu chính của tmoe

Dùng phím âm lượng để chọn lên xuống, Enter để xác nhận (hoặc chạm trực tiếp lên màn hình).

### Bước 2: Cài container Ubuntu

Trong menu tmoe, chọn lần lượt `安装 Linux 发行版` / `Install GNU/Linux container`, sẽ vào danh sách các bản phân phối:

Chọn bản phân phối Linux

**Rất khuyến nghị chọn Ubuntu** (tương thích nhất, tài liệu apt nhiều nhất, gặp vấn đề thì tìm được câu trả lời). Phiên bản chọn bản LTS mới nhất (ví dụ 22.04 / 24.04) là được.

Tải về + giải nén sẽ mất vài phút, tuỳ tốc độ mạng, cứ đợi.

### Bước 3: Vào container, xác định rõ "bạn đang ở đâu"

Sau khi cài xong, nhiều khả năng bạn sẽ được tự động đưa vào container. **Đây là chỗ người mới dễ lạc nhất**, trước tiên học cách phân biệt:

**Đã vào trong container Ubuntu** (dấu nhắc lệnh trông đại khái như thế này):

Đã vào trong container

**Vẫn còn ở Termux, chưa vào** (dấu nhắc khá đơn giản):

Vẫn còn ở Termux

Nếu là trường hợp sau, quay lại Termux và nhập:

```bash
tmoe
```

Mở lại menu, tìm `启动容器` / `Start container` rồi vào.

**Ghi nhớ quy tắc này**: cài Node, cài Claude Code, chạy lệnh Claude — **tất cả những việc này đều phải làm trong container Ubuntu**. Hệ thống gói `pkg` của Termux không cài được Claude Code.

### Bước 4: Cài Node.js và Claude Code

Sau khi xác nhận mình đang ở trong container Ubuntu, chạy lần lượt:

```bash
# 1. Cập nhật chỉ mục gói apt
apt update

# 2. Cài Node.js + npm (bản có sẵn trong Ubuntu là đủ dùng)
apt install -y nodejs npm

# 3. Cài Claude Code toàn cục
npm install -g @anthropic-ai/claude-code
```

Nếu npm báo lỗi quyền, thêm `sudo` phía trước. Nếu không có lệnh `sudo` thì bạn là user root, cứ chạy thẳng.

### Bước 5: Kết nối aicentos vào Claude Code

Claude Code mặc định kết nối đến endpoint chính thức, với người dùng trong nước có hai vấn đề: **không có hạn mức, không kết nối được**.

Chúng ta sửa hai biến môi trường để trỏ nó về aicentos:

```bash
# 1. Cài trình soạn thảo nano (trong container mặc định có thể chưa có)
apt install -y nano

# 2. Sửa cấu hình shell của bạn
nano ~/.bashrc
```

Dùng phím mũi tên di chuyển đến **cuối file**, sang dòng mới rồi dán:

```bash
export ANTHROPIC_BASE_URL=https://aicentos.com
export ANTHROPIC_AUTH_TOKEN=apikey-bạn-tạo-trên-aicentos.com
```

Thay `apikey-bạn-tạo-trên-aicentos.com` bằng API Key bạn đã tạo trong [Console aicentos](https://aicentos.com/keys) (thường bắt đầu bằng `sk-`).

Kết quả trông đại khái như thế này:

Thêm env vào cuối bashrc

**Lưu và thoát**:

* Nhấn `Ctrl + X` (phím Ctrl trên bộ gõ điện thoại, Termux mặc định có phím ảo này)
* Khi được hỏi Save, nhấn `Y`
* Rồi nhấn `Enter` để xác nhận tên file

Để cấu hình có hiệu lực ngay:

```bash
source ~/.bashrc
```

### Bước 6: Khởi động

```bash
claude
```

**Lần khởi động đầu tiên** sẽ yêu cầu chọn cách đăng nhập:

* Nếu trước đây từng đăng nhập bằng tài khoản chính thức và muốn xoá sạch, nhập `/logout` ngay trong Claude Code, nó sẽ đăng xuất, rồi `claude` vào lại sẽ dùng biến môi trường của bạn
* Nếu cài hoàn toàn mới, nó có thể bỏ qua và dùng thẳng biến môi trường

Khi thấy hộp hội thoại của Claude Code tức là đã xong, thử hỏi một câu bất kỳ:

```bash
Xin chào, giúp mình viết một script Python hello world
```

### Cheatsheet lệnh thường dùng trên điện thoại

Trong Claude Code:

| Lệnh       | Tác dụng                                                                |
| ---------- | ----------------------------------------------------------------------- |
| `/model`   | Chuyển mô hình (Opus / Sonnet / Haiku)                                  |
| `/logout`  | Đăng xuất tài khoản hiện tại (dùng một lần sau khi đổi biến môi trường) |
| `/clear`   | Xoá ngữ cảnh phiên hiện tại                                             |
| `/help`    | Xem tất cả lệnh                                                         |
| `Ctrl + C` | Ngắt việc sinh đang chạy                                                |

Ngoài container (trong Termux):

| Lệnh                | Tác dụng                    |
| ------------------- | --------------------------- |
| `tmoe`              | Mở menu chính của tmoe      |
| Khởi động container | Trong menu tmoe chọn "启动容器" |

### Các lỗi thường gặp trên điện thoại

**1. `npm install -g` không chạy được / bị treo**

Có thể do mạng. Trong container có thể chạy `npm config set registry https://registry.npmmirror.com` để đổi sang mirror Taobao, rồi `npm install -g @anthropic-ai/claude-code`.

**2. Lệnh `claude` not found**

Đường dẫn lệnh do `npm install -g` cài không nằm trong `PATH`. Thêm vào cuối `~/.bashrc`:

```bash
export PATH="$PATH:$(npm config get prefix)/bin"
```

Rồi `source ~/.bashrc`.

**3. Báo 401 / không đủ số dư**

Kiểm tra số dư trong [Ví aicentos](https://aicentos.com/wallet), và `ANTHROPIC_AUTH_TOKEN` đã được copy đủ chưa (chú ý đừng để dư khoảng trắng ở đầu cuối).

**4. Muốn dùng Sonnet, không muốn đốt tiền với Opus**

Sau khi vào `claude`, nhập `/model` và chọn sonnet là được. Hoặc thêm `export ANTHROPIC_MODEL=claude-sonnet-5` vào `.bashrc` để cố định mô hình mặc định.

### Nâng cao trên điện thoại

* Muốn nhập liệu tiện hơn: cài [Termux:Styling](https://f-droid.org/packages/com.termux.styling/) để đổi font và màu
* Muốn giao diện đồ hoạ: menu tmoe có desktop VNC, có thể chạy đầy đủ GNOME/XFCE trên điện thoại
* Muốn chạy nền lâu dài: dùng `tmux` hoặc `screen`, tắt Termux cũng không mất kết nối

Hướng dẫn đến đây là hết. Nếu gặp vấn đề, hoan nghênh phản hồi về [cộng đồng aicentos](https://aicentos.com).

## Lưu ý

* API Key được lấy tại trang "API Key" trong Console.
* `ANTHROPIC_AUTH_TOKEN` và `ANTHROPIC_API_KEY` **chọn một trong hai, không đặt cùng lúc**.
* Base URL chỉ điền địa chỉ gốc `https://aicentos.com`, **đừng** thủ công thêm `/v1/messages`, Claude Code sẽ tự nối.
* Sau khi sửa cấu hình, nhớ khởi động lại terminal / khởi động lại Claude Code.
* Tuyệt đối không commit API Key vào repo code.

---

# Cline

Nguồn: https://docs.aicentos.com/vi/clients/cline

Language: vi

> Đặt aicentos làm nhà cung cấp tương thích OpenAI trong tiện ích Cline: nhập Base URL và API Key

Cline chính thức hỗ trợ provider OpenAI Compatible, có thể kết nối trực tiếp tới dịch vụ hiện tại.

## Cài đặt

Theo tài liệu chính thức của Cline:

* Nếu bạn dùng VS Code, Cursor, Windsurf hoặc Antigravity, mở chợ extension, tìm kiếm `Cline` và cài extension chính thức
* Nếu bạn dùng JetBrains, vào `Settings / Plugins / Marketplace`, tìm `Cline` cài xong rồi khởi động lại IDE
* Nếu bạn chỉ muốn dùng bản terminal, có thể xem tài liệu Cline CLI chính thức: `https://docs.cline.bot/cline-cli/installation`

## Mở cài đặt

Trong panel Cline, nhấn nút cài đặt để vào phần cấu hình provider.

## Cấu hình cần điền

Đặt `API Provider` thành `OpenAI Compatible`, rồi điền:

* Base URL: `https://aicentos.com/v1`
* API Key: Key của bạn dạng `codex_...` hoặc `sk-...`
* Model ID: `gpt-5-codex-mini`

Nếu danh sách dropdown không tự xuất hiện mô hình này, cũng có thể nhập trực tiếp `gpt-5-codex-mini` bằng tay.

## Kiểm tra

Điền xong nhấn `Verify` của Cline, hoặc trực tiếp tạo một tác vụ mới. Nếu kết nối bình thường và bắt đầu được phiên hội thoại, tức là kết nối thành công.

## Lưu ý

* Tài liệu chính thức của Cline dùng chính cách cấu hình provider OpenAI Compatible
* Base URL nên điền đường dẫn gốc tương thích OpenAI
* Với dịch vụ hiện tại, không cần điền địa chỉ gốc của dịch vụ, cũng không cần bổ sung thành đường dẫn đầy đủ `/chat/completions`

---

# CodeBuddy

Nguồn: https://docs.aicentos.com/vi/clients/codebuddy

Language: vi

> Kết nối endpoint tương thích OpenAI của aicentos trong CodeBuddy (IDE / CLI) qua models.json

CodeBuddy hỗ trợ mô hình tùy chỉnh, qua `models.json` cấp người dùng hoặc cấp dự án có thể trỏ yêu cầu đến endpoint tương thích OpenAI của aicentos, IDE và CodeBuddy Code CLI dùng chung một bản cấu hình.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho CodeBuddy tại trang "API Key" trong Console (khuyến nghị đặt tên `codebuddy`).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Cấu hình cần điền

| Trường                               | Giá trị                                      |
| ------------------------------------ | -------------------------------------------- |
| Base URL                             | `https://aicentos.com/v1`                    |
| URL endpoint (trường `url`)          | `https://aicentos.com/v1/chat/completions`   |
| API Key (`apiKey`)                   | Key tạo trong Console                        |
| Model ID (trường `id`)               | tên mô hình trong "Model Square" của Console |
| `supportsToolCall`                   | `true`                                       |
| `maxInputTokens` / `maxOutputTokens` | Điền theo mô hình đã chọn                    |

Lưu ý: trường `url` trong `models.json` yêu cầu **đường dẫn API đầy đủ**, bắt buộc kết thúc bằng `/chat/completions`.

## Các bước thiết lập

* Mở CodeBuddy một lần, để nó sinh thư mục cấu hình.
* Tạo mới hoặc sửa file cấu hình cấp người dùng:
  * macOS / Linux: `~/.codebuddy/models.json`
  * Windows: `C:\Users\<tên-người-dùng>\.codebuddy\models.json`
  * Nếu chỉ muốn có hiệu lực với một dự án, có thể dùng cấp dự án `<thư-mục-gốc-dự-án>/.codebuddy/models.json`, độ ưu tiên cao hơn cấp người dùng.
* Ghi nội dung sau, thay `id` bằng tên mô hình bạn đã xác nhận khả dụng trong Console:

```json
{
  "models": [
    {
      "id": "gpt-5",
      "name": "GPT-5 (aicentos)",
      "vendor": "aicentos",
      "apiKey": "${AICENTOS_API_KEY}",
      "url": "https://aicentos.com/v1/chat/completions",
      "maxInputTokens": 128000,
      "maxOutputTokens": 16384,
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": false
    }
  ]
}
```

* Thiết lập biến môi trường (cả `apiKey` và `url` đều hỗ trợ tham chiếu `${VAR_NAME}`):

```bash
export AICENTOS_API_KEY="sk-Key-aicentos-của-bạn"
```

* Thoát hoàn toàn CodeBuddy rồi mở lại (khởi động lại panel IDE là được).
* Trong bộ chọn mô hình, chọn mô hình vừa cấu hình.

Nếu không muốn sửa file, cũng có thể ở dưới panel hội thoại của CodeBuddy IDE nhấn vào ô chọn mô hình → **Cấu hình mô hình tùy chỉnh** → nhà cung cấp chọn **Custom**, điền Base URL là `https://aicentos.com/v1`, điền API Key và tên mô hình là được.

## Kiểm tra

Sau khi lưu, tạo một hội thoại hoặc nhiệm vụ lập trình mới, trước dùng một prompt đơn giản để thử nhẹ, xác nhận trả về nội dung bình thường rồi mới dùng chính thức.

## Lưu ý

* Hiện chỉ hỗ trợ API **định dạng giao diện OpenAI**.
* `url` bắt buộc ghi thành đường dẫn đầy đủ `/v1/chat/completions`, ghi `https://aicentos.com/v1` sẽ không có hiệu lực.
* Lớp ngoài cùng bắt buộc là cấu trúc `{"models": [...]}`, `models` là trường bắt buộc ở cấp cao nhất.
* `availableModels` là danh sách trắng: một khi điền, hộp thả xuống mô hình chỉ hiển thị các mô hình trong danh sách, mô hình tích hợp sẵn sẽ biến mất cùng lúc. Khi không cần giới hạn, hãy bỏ qua trường này.
* Hãy lưu file ở dạng **UTF-8 không BOM**, JSON có BOM sẽ khiến việc đọc cấu hình mô hình local thất bại.
* Biến môi trường được phân tích khi khởi động; nếu biến không tồn tại, `${AICENTOS_API_KEY}` trong file cấu hình sẽ được giữ nguyên và khiến lời gọi thất bại.
* Khuyến nghị đặt quyền của `models.json` là `600`, đừng commit vào kho mã nguồn.
* Cũng có thể cấu hình CLI bằng biến môi trường: `CODEBUDDY_API_KEY`, `CODEBUDDY_BASE_URL`, `CODEBUDDY_MODEL`. Khi đặt trực tiếp `CODEBUDDY_BASE_URL`, đừng kèm `/chat/completions`, CLI sẽ tự thêm.
* Xem thêm giải thích tại trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

---

# Codebuff

Nguồn: https://docs.aicentos.com/vi/clients/codebuff

Language: vi

> Kết nối aicentos vào agent dòng lệnh Codebuff qua endpoint OpenAI tương thích

Codebuff là một AI coding agent chạy trong terminal, sẽ điều phối nhiều sub-agent theo tác vụ để đọc code, lập kế hoạch và sửa file. Mặc định nó kết nối tới dịch vụ đám mây chính thức; nếu phiên bản bạn đang dùng hỗ trợ ghi đè endpoint OpenAI tương thích, có thể trỏ yêu cầu về aicentos qua biến môi trường.

## Xác nhận trước phiên bản của bạn có hỗ trợ endpoint tùy chỉnh không

Codebuff chính thức khuyến khích dùng chế độ dịch vụ đám mây: đăng nhập để dùng hạn mức chính thức, hoặc dùng API chính thức qua `CODEBUFF_API_KEY`. Base URL tùy chỉnh không phải phiên bản nào cũng có, hãy xác nhận trước:

* Chạy `codebuff --help`, xem có tùy chọn dạng `--base-url`, `--provider` không.
* Xác nhận phiên bản có đọc `OPENAI_BASE_URL` (một số phiên bản là `CODEBUFF_BASE_URL`) để ghi đè endpoint không.
* Nếu cả hai đều không hỗ trợ, tức là phiên bản hiện tại chỉ đi được dịch vụ chính thức, không thể kết nối thẳng aicentos.

## Chuẩn bị

Nếu xác nhận phiên bản hỗ trợ endpoint tùy chỉnh, trước tiên tạo một Key chuyên dụng cho Codebuff tại trang "API Key" trong Console (khuyến nghị đặt tên `codebuff-cli`).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Đồng thời xác nhận máy đã cài Node.js, và đã cài toàn cục Codebuff:

```bash
npm install -g codebuff
```

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| Base URL | `https://aicentos.com/v1`                    |
| API Key  | Key tạo trong Console                        |
| Mô hình  | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

* Ghi endpoint và key vào cấu hình shell (`~/.zshrc` hoặc `~/.bashrc`):

```bash
export OPENAI_API_KEY="sk-Key-aicentos-của-bạn"
export OPENAI_BASE_URL="https://aicentos.com/v1"
```

* Tải lại cấu hình: `source ~/.zshrc`.
* Vào thư mục dự án, chạy trực tiếp `codebuff`.
* Nếu phiên bản hỗ trợ tham số `--model`, có thể chỉ định rõ mô hình khi khởi động; nếu không thì dùng lệnh chọn mô hình trong giao diện tương tác để chuyển.

Một số phiên bản ghi cấu hình vào file JSON trong thư mục cấu hình người dùng (file chứa thông tin xác thực mặc định có quyền `600`, đừng commit vào kho mã nguồn). Nếu phiên bản của bạn dùng file cấu hình thay vì biến môi trường, hãy điền cùng một Base URL và Key theo tên trường do `codebuff --help` hoặc tài liệu chính thức đưa ra.

## Kiểm tra

Sau khi khởi động, trước tiên dùng một câu prompt đơn giản test nhẹ, ví dụ cho nó đọc một file rồi tóm tắt nội dung, xác nhận trả về kết quả bình thường rồi mới chính thức sử dụng.

## Lưu ý

* Endpoint tùy chỉnh thuộc dạng nâng cao, tên trường giữa các phiên bản có thể không nhất quán; lấy output của `codebuff --help` trên máy bạn làm chuẩn.
* `OPENAI_BASE_URL` chỉ điền đến `https://aicentos.com/v1`, đừng bổ sung thành `/v1/chat/completions` đầy đủ.
* Codebuff sẽ gửi đoạn code và output terminal làm ngữ cảnh, trước khi dùng hãy xác nhận điều này phù hợp với yêu cầu tuân thủ dữ liệu của đội bạn.
* Khi gặp lỗi, lần lượt kiểm tra: biến môi trường có hiệu lực trong terminal hiện tại không, tên mô hình có khớp Console không, số dư tài khoản có đủ không ([https://aicentos.com/wallet](https://aicentos.com/wallet)).
* Xem thêm giải thích tại trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

---

# Codex CLI

Nguồn: https://docs.aicentos.com/vi/clients/codex-cli

Language: vi

> Dùng aicentos trong Codex CLI —— cấu hình thủ công model_providers trong config.toml

Codex CLI là agent lập trình dòng lệnh chính thức của OpenAI, định nghĩa nhà cung cấp mô hình qua `~/.codex/config.toml`. Trỏ provider tùy chỉnh về aicentos, là có thể dùng các mô hình aicentos tích hợp ngay trong terminal.

Nếu bạn muốn quản lý nhiều bộ cấu hình bằng giao diện đồ hoạ hơn, cũng có thể đi theo [CC Switch](https://docs.aicentos.com/vi/clients/cc-switch) để chuyển một chạm; bài này chỉ nói cấu hình thủ công.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho Codex CLI tại trang "API Key" trong Console (khuyến nghị đặt tên `codex-cli` để dễ theo dõi mức sử dụng):

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền khi hết số dư: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Xác nhận đã cài Codex CLI:

```bash
codex --version
```

## Cấu hình cần điền

| Trường                  | Giá trị                                      |
| ----------------------- | -------------------------------------------- |
| Provider ID             | `aicentos`                                   |
| Tên Provider            | `aicentos`                                   |
| Biến môi trường API Key | `AICENTOS_API_KEY`                           |
| Base URL                | `https://aicentos.com/v1`                    |
| Mô hình                 | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

### 1. Thiết lập biến môi trường API Key

```bash
export AICENTOS_API_KEY="sk-API-Key-của-bạn"
```

Muốn hiệu lực vĩnh viễn thì ghi vào `~/.zshrc` hoặc `~/.bashrc`, rồi `source` một lần, và dùng `echo $AICENTOS_API_KEY` để xác nhận.

### 2. Sửa config.toml

Thêm vào `~/.codex/config.toml`:

```toml
model = "tên-mô-hình-của-bạn"
model_provider = "aicentos"

[model_providers.aicentos]
name = "aicentos"
base_url = "https://aicentos.com/v1"
env_key = "AICENTOS_API_KEY"
wire_api = "responses"
```

Thay `tên-mô-hình-của-bạn` bằng tên mô hình được liệt kê trong "Model Square" của Console, có thể tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list).

### 3. Khởi động Codex

```bash
codex
```

Gửi một yêu cầu đơn giản, xác nhận provider hoạt động bình thường.

## Kiểm tra

```
codex exec "Trả lời trong một câu: 1+1 bằng mấy"
```

Trả về nội dung bình thường nghĩa là kết nối thành công, nội dung trả về sẽ tiêu tốn một ít hạn mức, có thể đối chiếu trong log sử dụng của Console.

## Lưu ý

* **Base URL chỉ điền đến `/v1`**, đừng bổ sung thành đường dẫn đầy đủ `/v1/chat/completions`.
* Các trường như `base_url`, `env_key` chỉ có hiệu lực trong `~/.codex/config.toml` cấp người dùng. `.codex/config.toml` ghi trong dự án sẽ bị bỏ qua, và có thể xuất hiện cảnh báo khi khởi động.
* `wire_api` điền `responses`, tương ứng với [giao diện Responses](https://docs.aicentos.com/vi/api/chat/openai/responses) của aicentos. Tài liệu chính thức hiện chỉ hỗ trợ giá trị này; nếu bản của bạn báo `unknown variant`, nghĩa là CLI quá cũ, khuyến nghị nâng cấp trước.
* `openai`, `ollama`, `lmstudio` là các provider ID được bảo lưu, **không thể** sửa base\_url của `openai` tích hợp sẵn để trỏ về gateway bên thứ ba, bắt buộc phải đặt tên provider mới (bài này dùng `aicentos`).
* Thứ tự xử lý sự cố: tên mô hình có khớp với Console không → Base URL có dừng ở `/v1` không → biến môi trường có hiển thị trong **terminal khởi động codex** không → số dư tài khoản có đủ không.

## Liên kết liên quan

* [Kết nối Codex (cách CC Switch)](https://docs.aicentos.com/vi/clients/codex)

---

# Codex++

Nguồn: https://docs.aicentos.com/vi/clients/codex-plus

Language: vi

> Dùng launcher tăng cường Codex++ để kết nối GPT API của aicentos vào Codex trên máy bạn, chế độ thuần API, cấu hình đồ hoạ, vài phút là xong

[Codex++](https://github.com/BigPizzaV3/CodexPlusPlus) là **launcher tăng cường bên ngoài và công cụ quản lý** dành cho Codex App. Nó không sửa các file cài đặt gốc của Codex App, mà khởi động Codex qua launcher bên ngoài, và dùng Chromium DevTools Protocol để tiêm script tăng cường — nên yên tâm dùng, không động đến Codex gốc của bạn.

Hướng dẫn này dạy bạn kết nối **GPT API của aicentos** vào Codex trên máy tính: toàn bộ hoàn thành bằng vài cú nhấp trong giao diện đồ hoạ của Codex++, không cần tự viết `config.toml`.

## Chuẩn bị

* Một máy tính (hỗ trợ cả Windows / macOS)
* Một tài khoản [aicentos](https://aicentos.com), và tạo một Key tại [trang API Key](https://aicentos.com/keys), khuyến nghị đặt tên có chữ `codex` để dễ theo dõi mức sử dụng

Khi tạo Key, chú ý **nhóm** mà Key thuộc về, phải cùng nhóm với mô hình bạn điền dưới đây, nếu không sẽ báo không có quyền.

## Bước 1: Tải và cài Codex++

Mở trang GitHub Releases chính thức: [github.com/BigPizzaV3/CodexPlusPlus/releases](https://github.com/BigPizzaV3/CodexPlusPlus/releases)

Trang tải Releases của Codex++

Trong bản mới nhất, chọn gói cài đặt **phù hợp với hệ điều hành của bạn**, tải về máy, cài và mở. Mở lên thấy chính là công cụ quản lý Codex++:

Giao diện công cụ quản lý Codex++

## Bước 2: Thêm nhà cung cấp

Nhấn "**Thêm nhà cung cấp**", tạo mới một cấu hình kết nối:

Thêm nhà cung cấp

Điền theo bảng dưới:

| Trường           | Điền gì                                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Tên              | Tên trạm trung chuyển, tự nhận ra được là được (ví dụ `aicentos`)                                                             |
| Chế độ kết nối   | **Thuần API**                                                                                                                 |
| Cấu hình mô hình | Điền mô hình aicentos hỗ trợ, **copy nguyên vẹn tên mô hình**, nhiều mô hình cách nhau bằng dấu phẩy, ví dụ `gpt-5.5,gpt-5.4` |

## Bước 3: Điền Codex target

Trong "Codex target" **bật ✅**, và điền hai mục dưới đây:

| Trường   | Giá trị                                                         |
| -------- | --------------------------------------------------------------- |
| Base URL | `https://aicentos.com`                                          |
| Key      | Key được tạo trong Quản lý token aicentos, thuộc nhóm tương ứng |

Điền Base URL và Key

**Giao thức upstream** nhớ chọn **chat completions**, đừng dùng giao thức khác, nếu không yêu cầu sẽ thất bại.

Chọn giao thức upstream là chat completions

Điền xong nhấn "**Lưu**" ở trên cùng.

## Bước 4: Khởi động lại Codex

Sau khi lưu, nhấn "**Khởi động lại**" ở góc trên phải để cấu hình có hiệu lực:

Khởi động lại Codex

## Bước 5: Đăng nhập bằng Key

Sau khi khởi động lại, chọn "**Dùng cách đăng nhập khác**":

Dùng cách đăng nhập khác

Dán Key vừa tạo trong [Quản lý token aicentos](https://aicentos.com/keys) vào, nhấn "**Tiếp tục**":

Dán Key và tiếp tục

Đến đây là kết nối hoàn tất, có thể bắt đầu dùng Codex ngay.

## Xử lý sự cố

Khi yêu cầu thất bại, đối chiếu đầu ra Codex và log sử dụng trong [Console aicentos](https://aicentos.com) để xử lý, nguyên nhân thường gặp:

* **Tên mô hình ghi sai**: lấy aicentos [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list) làm chuẩn, phải copy nguyên vẹn tên mô hình.
* **Chưa chọn đúng giao thức upstream**: bắt buộc là **chat completions**.
* **Base URL sai**: điền `https://aicentos.com`, đầu cuối đừng có khoảng trắng hoặc đường dẫn thừa.
* **Báo 401 / không có quyền**: kiểm tra Key đã được copy đủ chưa, và nhóm của Key có chứa mô hình bạn muốn dùng không; số dư xem tại [Ví](https://aicentos.com/wallet).

---

# Codex

Nguồn: https://docs.aicentos.com/vi/clients/codex

Language: vi

> Dùng aicentos trong Codex —— nhập một chạm bằng CC Switch, hoặc cấu hình thủ công config.toml

Codex tương thích giao thức OpenAI, chỉ cần trỏ nhà cung cấp mô hình về aicentos là có thể dùng toàn bộ mô hình aicentos tích hợp.

Dưới đây có hai cách kết nối: **quản lý một chạm bằng CC Switch** (khuyến nghị), hoặc **tự sửa config.toml bằng tay**.

## Cách một: dùng CC Switch (khuyến nghị)

CC Switch cũng hỗ trợ quản lý cấu hình Provider của Codex, nhiều bộ cấu hình chuyển đổi một chạm.

Xem chi tiết tại [Kết nối CC Switch →](https://docs.aicentos.com/vi/clients/cc-switch)

## Cách hai: cấu hình thủ công

### Thông tin cần chuẩn bị

| Mục                          | Giá trị                   |
| ---------------------------- | ------------------------- |
| Provider ID                  | `aicentos`                |
| Tên Provider                 | `aicentos`                |
| Base URL                     | `https://aicentos.com/v1` |
| Biến môi trường chứa API Key | `AICENTOS_API_KEY`        |

Trước tiên, tạo một Key chuyên dụng tại trang "API Key" trong Console, khuyến nghị đặt tên có chữ `codex` để dễ theo dõi mức sử dụng.

### Thiết lập API Key

Cấu hình biến môi trường trong terminal:

```bash
export AICENTOS_API_KEY="sk-API-Key-của-bạn"
```

Muốn lưu lâu dài thì thêm vào `~/.zshrc` hoặc `~/.bashrc`, rồi tải lại:

```bash
source ~/.zshrc
```

Xác nhận biến đã có hiệu lực:

```bash
echo $AICENTOS_API_KEY
```

### Cấu hình Provider cho Codex

Sửa `~/.codex/config.toml`, thêm vào:

```bash
model = "tên-mô-hình-của-bạn"
model_provider = "aicentos"

[model_providers.aicentos]
name = "aicentos"
base_url = "https://aicentos.com/v1"
env_key = "AICENTOS_API_KEY"
wire_api = "responses"
```

Thay `tên-mô-hình-của-bạn` bằng tên mô hình được liệt kê trong "Model Square" của Console, có thể tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list).

### Khởi động Codex

```bash
codex
```

Gửi một yêu cầu đơn giản, xác nhận Provider hoạt động bình thường.

## Xử lý sự cố

Khi yêu cầu thất bại, đối chiếu output terminal của Codex và nhật ký mức sử dụng trong Console để xử lý sự cố. Các nguyên nhân thường gặp:

* Tên mô hình ghi sai (lấy "Model Square" làm chuẩn).
* Định dạng Base URL không đúng (chỉ điền đến `/v1`, đừng thêm thừa đường dẫn).
* Biến môi trường không được terminal hiện tại đọc vào (mở lại terminal hoặc `source` file cấu hình).

---

# Command Code

Nguồn: https://docs.aicentos.com/vi/clients/command-code

Language: vi

> Dùng aicentos trong Command Code —— thêm nhà cung cấp BYOK qua providers.json

Command Code là agent lập trình trong terminal, mặc định dùng nhà cung cấp tích hợp sẵn, đồng thời hỗ trợ BYOK: đăng ký một nhà cung cấp tùy chỉnh trong `~/.commandcode/providers.json`, trỏ baseURL về aicentos là được.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho Command Code tại trang "API Key" trong Console (khuyến nghị đặt tên `command-code` để dễ theo dõi mức sử dụng):

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền khi hết số dư: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| File cấu hình | `~/.commandcode/providers.json`              |
| baseURL       | `https://aicentos.com/v1`                    |
| apiKey        | `$AICENTOS_API_KEY`                          |
| Mô hình       | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

### 1. Thiết lập biến môi trường

```bash
export AICENTOS_API_KEY="sk-API-Key-của-bạn"
```

Ghi vào `~/.zshrc` hoặc `~/.bashrc` để lưu lâu dài.

### 2. Sửa providers.json

Sửa `~/.commandcode/providers.json`, thêm một mục dưới đối tượng `provider`:

```json
{
  "provider": {
    "aicentos": {
      "name": "aicentos",
      "api": "openai-completions",
      "baseURL": "https://aicentos.com/v1",
      "apiKey": "$AICENTOS_API_KEY",
      "models": {
        "gpt-4o": {}
      }
    }
  }
}
```

Giải thích các trường:

| Trường    | Mô tả                                                                                      |
| --------- | ------------------------------------------------------------------------------------------ |
| `name`    | Tên hiển thị, xuất hiện trong `/connect` và `/model`                                       |
| `api`     | `openai-completions` (mặc định) hoặc `anthropic-messages`                                  |
| `baseURL` | Bắt buộc, địa chỉ gốc API, cần có `/v1`                                                    |
| `apiKey`  | Hỗ trợ `$VAR`, `{env:VAR}`, `!command`, hoặc điền `false` nghĩa là endpoint không xác thực |
| `models`  | Bắt buộc, `{}` là đủ, model ID cần khớp với endpoint                                       |

Thay model ID trong `models` bằng tên trong "Model Square" của Console, có thể tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list).

### 3. Chọn nhà cung cấp

Sau khi vào Command Code:

* Chạy `/connect`, chọn `aicentos` và hoàn tất xác nhận key;
* Chạy `/model`, chọn mô hình muốn dùng.

Lưu ý: **sau khi sửa `providers.json` cần mở lại `/model`** cấu hình mới mới được nạp.

## Kiểm tra

Sau khi chọn mô hình, gửi một prompt đơn giản:

```
Trả lời trong một câu: 1+1 bằng mấy
```

Trả về bình thường nghĩa là kết nối thành công. Cũng có thể trong `/connect` nhấn `u` vào nhà cung cấp, để nó gọi `/models` của endpoint làm mới danh sách mô hình.

## Lưu ý

* Command Code mặc định đi theo Chat Completions tương thích OpenAI, do đó `api` điền `openai-completions` là được.
* Nếu muốn dùng các mô hình dòng Claude, cần tạo thêm một mục nhà cung cấp với `api: "anthropic-messages"` — hai giao thức nối đường dẫn khác nhau (OpenAI SDK thêm `/chat/completions`, Anthropic SDK thêm `/v1/messages`), cùng một baseURL không thể phục vụ đồng thời cả hai.
* `baseURL` bắt buộc phải có `/v1`, Command Code sẽ tự nối các đường dẫn phía sau.
* Dán key dạng văn bản thuần trực tiếp vào `apiKey` sẽ bị từ chối, hãy dùng dạng `$VAR`.
* Thứ tự xử lý sự cố: có thấy mô hình trong `/model` không → biến môi trường có hiển thị trong terminal khởi động không → baseURL có dừng ở `/v1` không → số dư có đủ không.

## Liên kết liên quan

* Tài liệu BYOK chính thức: [https://commandcode.ai/docs/byok](https://commandcode.ai/docs/byok)

---

# GitHub Copilot

Nguồn: https://docs.aicentos.com/vi/clients/copilot

Language: vi

> Trong GitHub Copilot Chat, kết nối endpoint OpenAI tương thích của aicentos bằng key tự mang (BYOK)

GitHub Copilot trong VS Code cung cấp khả năng tự mang key (BYOK), có thể trỏ yêu cầu hội thoại về endpoint OpenAI tương thích tùy chỉnh. Đặt endpoint thành aicentos, điền Key tạo trong Console, là có thể dùng các mô hình aicentos tích hợp trong Copilot Chat / Agent.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Copilot tại trang "API Key" trong Console (khuyến nghị đặt tên `copilot-vscode` hoặc `copilot-work` để dễ theo dõi mức sử dụng).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Đồng thời xác nhận VS Code và extension GitHub Copilot Chat trên máy đã cập nhật lên phiên bản hỗ trợ endpoint tùy chỉnh; các phiên bản cũ hơn chỉ có BYOK của các nhà cung cấp tích hợp sẵn, không có mục "endpoint tùy chỉnh" chung.

## Cấu hình cần điền

| Trường       | Giá trị                                                                 |
| ------------ | ----------------------------------------------------------------------- |
| Provider     | Custom Endpoint (phiên bản cũ là OpenAI Compatible)                     |
| Base URL     | `https://aicentos.com/v1`                                               |
| Loại API     | Chat Completions (tương ứng `https://aicentos.com/v1/chat/completions`) |
| API Key      | Key tạo trong Console                                                   |
| Model ID     | tên mô hình trong "Model Square" của Console                            |
| Tool Calling | `true` (bắt buộc bật nếu muốn dùng ở chế độ Agent)                      |

## Các bước thiết lập

### Cách một: giao diện đồ hoạ

* Mở view Chat của VS Code.
* Nhấn vào bộ chọn mô hình phía trên ô nhập, chọn **Manage Language Models** (phiên bản cũ là **Manage Models...**).
* Nhấn **Add Models**, trong danh sách nhà cung cấp chọn **Custom Endpoint** (phiên bản cũ là **OpenAI Compatible**).
* Nhập tên nhóm và API Key.
* Loại API chọn **Chat Completions**.
* Theo hướng dẫn bổ sung thông tin mô hình: `id` điền tên mô hình trong Console, `url` điền `https://aicentos.com/v1/chat/completions`.
* Sau khi lưu, quay lại Chat, trong dropdown mô hình chọn mô hình vừa thêm.

### Cách hai: settings.json

Trong command palette thực hiện **Preferences: Open User Settings (JSON)**, thêm vào:

```json
{
  "github.copilot.chat.customOAIModels": {
    "aicentos-gpt": {
      "name": "aicentos GPT",
      "url": "https://aicentos.com/v1/chat/completions",
      "toolCalling": true,
      "vision": false,
      "maxInputTokens": 128000,
      "maxOutputTokens": 16384
    }
  }
}
```

Key ở lớp ngoài cùng của object (như `aicentos-gpt`) chính là model ID bạn thấy trong bộ chọn mô hình, phải là duy nhất.

Tài liệu chính thức tham khảo: [https://code.visualstudio.com/docs/copilot/customization/language-models](https://code.visualstudio.com/docs/copilot/customization/language-models)

## Kiểm tra

Sau khi lưu cài đặt, tạo một hội thoại mới trong Chat, trước tiên test nhẹ bằng một câu prompt đơn giản, trả về bình thường là đã thông, rồi mới chính thức dùng chế độ Agent / Edit.

## Lưu ý

* BYOK chỉ tác dụng với **Chat / Agent / Edit**, không bao gồm gợi ý code nội tuyến (Tab completion); tìm kiếm ngữ nghĩa, embedding và các khả năng khác vẫn đi dịch vụ tích hợp sẵn của Copilot.
* Muốn dùng ở chế độ **Agent**, mô hình phải hỗ trợ **tool calling**, `toolCalling` cần đặt là `true`; nếu không mô hình đó sẽ không xuất hiện trong bộ chọn mô hình.
* Trường `url` phải điền đầy đủ `https://aicentos.com/v1/chat/completions`, đừng chỉ điền đến `/v1`.
* `github.copilot.chat.customOAIModels` là cách viết cũ, phiên bản mới đã đổi sang `chatLanguageModels.json` kết hợp `customendpoint`; lấy mục nhập thực tế theo phiên bản VS Code hiện tại của bạn.
* Khi dùng GitHub Copilot Business / Enterprise, quản trị viên có thể tắt BYOK qua chính sách.
* Sau khi thêm mô hình mà chưa hiện ngay, khởi động lại VS Code một lần.
* Khi gặp lỗi, lần lượt kiểm tra: Key có khoảng trắng thừa không, tên mô hình có khớp Console không, số dư tài khoản có đủ không, loại API có chọn đúng không. Không đủ số dư có thể tới [https://aicentos.com/wallet](https://aicentos.com/wallet) để nạp tiền.

---

# Craft Agent

Nguồn: https://docs.aicentos.com/vi/clients/craft-agent

Language: vi

> Dùng aicentos trong Craft Agent —— kết nối OpenAI tương thích tùy chỉnh, dùng chung cho bản desktop và craft-cli

Kết nối LLM của Craft Agent hỗ trợ loại `Custom`, mô tả chính thức là "URL bất kỳ, endpoint tương thích OpenAI hoặc tương thích Anthropic bất kỳ". Trỏ Base URL về aicentos, cả bản desktop lẫn `craft-cli` đều dùng được.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Craft Agent trong Console (khuyến nghị đặt tên `craft-agent`) để dễ xem mức sử dụng theo Key.

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Cài bản desktop:

```bash
curl -fsSL https://thecraftagents.com/install-app.sh | bash
```

Cũng hỗ trợ headless server và cách dùng thuần dòng lệnh.

## Cấu hình cần điền

| Trường       | Giá trị                                                                                         |
| ------------ | ----------------------------------------------------------------------------------------------- |
| Loại kết nối | Custom (tùy chỉnh)                                                                              |
| Giao thức    | `openai-completions`, hoặc `anthropic-messages`                                                 |
| Base URL     | `https://aicentos.com/v1` (tương thích OpenAI) / `https://aicentos.com` (tương thích Anthropic) |
| API Key      | Key tạo trong Console                                                                           |
| Mô hình      | tên mô hình trong "Model Square" của Console                                                    |

## Các bước thiết lập

Bản desktop: mở kết nối LLM trong phần cài đặt, thêm một kết nối mới, chọn loại Custom, điền theo bảng trên.

Cách viết tương đương trên dòng lệnh:

```bash
export AICENTOS_API_KEY="sk-API-Key-của-bạn"
craft-cli run --provider openai \
  --base-url https://aicentos.com/v1 \
  --api-key "$AICENTOS_API_KEY" \
  --model tên-mô-hình-của-bạn \
  "Xin chào"
```

Cũng có thể sửa trực tiếp file cấu hình `~/.craft-agent/config.json`:

```json
{
  "llmConnections": [
    {
      "providerType": "pi_compat",
      "baseUrl": "https://aicentos.com/v1",
      "customEndpoint": { "api": "openai-completions" },
      "models": [{ "id": "tên-mô-hình-của-bạn" }],
      "defaultModel": "tên-mô-hình-của-bạn"
    }
  ]
}
```

Khóa không ghi vào cấu hình dạng văn bản thuần, mà lưu ở `credentials.enc` trong cùng thư mục. Chỉ cần điền một lần qua giao diện, đừng sửa tay file này.

## Kiểm tra

```bash
craft-cli run --provider openai \
  --base-url https://aicentos.com/v1 \
  --api-key "$AICENTOS_API_KEY" \
  --model tên-mô-hình-của-bạn \
  "Giới thiệu bản thân trong một câu"
```

Trả về bình thường là thông. Sau đó quay lại Console xem mức sử dụng, xác nhận yêu cầu được ghi vào Key này.

## Lưu ý

* `providerType` giữ là `pi_compat`, đây là định danh endpoint tùy chỉnh của nó; đổi sang tên provider tích hợp sẵn sẽ đi theo mô hình chính thức.
* `models` phải điền tay, nó không tự kéo danh sách mô hình. Tên phải trùng khớp hoàn toàn với "Model Square" trong Console (tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)).
* Khi dùng endpoint tương thích Anthropic, Base URL là `https://aicentos.com`, không kèm `/v1`, đổi `--provider` thành `anthropic`.
* Vị trí menu của bản desktop thay đổi theo phiên bản, khi không tìm thấy thì lấy cách viết trong `config.json` làm chuẩn.

## Liên kết liên quan

* [Tài liệu Craft Agents](https://thecraftagents.com/docs)
* [Kho craft-agents](https://github.com/craft-ai-agents/craft-agents-oss)

---

# Crush

Nguồn: https://docs.aicentos.com/vi/clients/crush

Language: vi

> Dùng aicentos trong Crush —— thêm provider tùy chỉnh qua crush.json

Crush là agent lập trình terminal do Charmbracelet phát hành, viết bằng Go, hỗ trợ khai báo bất kỳ provider tùy chỉnh nào tương thích OpenAI trong `crush.json`. Trỏ base\_url về aicentos, là có thể dùng các mô hình aicentos tích hợp ngay trong TUI.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho Crush tại trang "API Key" trong Console (khuyến nghị đặt tên `crush` để dễ theo dõi mức sử dụng):

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền khi hết số dư: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Xác nhận đã cài Crush:

```bash
crush --version
```

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| File cấu hình | `~/.config/crush/crush.json`                 |
| type          | `openai-compat`                              |
| base\_url     | `https://aicentos.com/v1`                    |
| api\_key      | `$AICENTOS_API_KEY`                          |
| Mô hình       | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

### 1. Thiết lập biến môi trường API Key

```bash
export AICENTOS_API_KEY="sk-API-Key-của-bạn"
```

Muốn lưu lâu dài thì ghi vào `~/.zshrc` hoặc `~/.bashrc`, rồi `source` một lần.

### 2. Sửa crush.json

File cấu hình toàn cục nằm ở `~/.config/crush/crush.json` (trên Windows là `%USERPROFILE%\AppData\Local\crush\crush.json`); `.crush.json` hoặc `crush.json` ở thư mục gốc dự án sẽ ghi đè cấu hình toàn cục.

Ghi vào:

```json
{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "aicentos": {
      "type": "openai-compat",
      "base_url": "https://aicentos.com/v1",
      "api_key": "$AICENTOS_API_KEY",
      "models": [
        {
          "id": "gpt-4o",
          "name": "GPT-4o",
          "context_window": 128000,
          "default_max_tokens": 8192,
          "can_reason": true
        }
      ]
    }
  }
}
```

`models[].id` phải khớp hoàn toàn với model ID phía endpoint, hãy lấy "Model Square" của Console làm chuẩn, có thể tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list).

### 3. Chọn mô hình

Sau khi khởi động `crush`, trong TUI nhấn `Ctrl+L` (hoặc nhập `/model`), xác nhận thấy được `aicentos` và các mô hình của nó.

## Kiểm tra

Dùng chế độ không tương tác để xác minh nhanh:

```bash
crush run "Trả lời trong một câu: 1+1 bằng mấy"
```

Khi cần xem log yêu cầu, thêm `--debug`. Nếu gặp 404, kiểm tra `base_url` đã có `/v1` chưa.

## Lưu ý

* **Đừng điền `openai` vào `type`**. `openai` dành cho proxy thực sự đi qua OpenAI (hoặc Azure OpenAI); khi trỏ về endpoint tương thích của bên thứ ba bắt buộc phải điền `openai-compat`, nếu không sẽ gặp lỗi nhận diện mô hình hoặc lỗi API.
* `base_url` điền đến `/v1` là đủ, đừng có dấu gạch chéo ở cuối.
* `api_key` hỗ trợ mở rộng `$VAR` và `$(command)`, khuyến nghị giữ key trong biến môi trường hoặc file key, đừng ghi cứng dạng văn bản thuần.
* Nếu kết nối đến endpoint giao thức Anthropic (`type` là `anthropic`), `base_url` nên dừng ở `/api`, Crush sẽ tự thêm `/v1/messages`, và cần khai báo thêm `anthropic-version` trong `extra_headers`.
* Lỗi đã biết: khi dùng provider tùy chỉnh, số đếm token và thống kê chi phí trong TUI có thể hiển thị 0, điều này không ảnh hưởng đến yêu cầu thực tế và việc tính phí.
* Khi cần bật đầu ra suy luận, mô hình phong cách OpenAI dùng `"can_reason": true` kết hợp `"reasoning_effort"`; mô hình phong cách Anthropic dùng `"think": true`.

## Liên kết liên quan

* Tài liệu Provider tùy chỉnh: [https://github.com/charmbracelet/crush](https://github.com/charmbracelet/crush)

---

# Cursor

Nguồn: https://docs.aicentos.com/vi/clients/cursor

Language: vi

> Dùng aicentos trong Cursor —— kết nối qua cài đặt OpenAI tương thích tùy chỉnh

Cursor hỗ trợ API OpenAI tương thích tùy chỉnh, trỏ Base URL về aicentos, điền API Key, là có thể dùng các mô hình aicentos tích hợp trong Chat / Composer.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Cursor tại trang "API Key" trong Console (khuyến nghị đặt tên `cursor-desktop` hoặc `cursor-work` để dễ theo dõi mức sử dụng).

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Mô hình  | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

* Mở cài đặt Cursor (Settings).
* Vào khu vực **Models** hoặc **API Keys**.
* Tìm tùy chọn **OpenAI API Key** / cài đặt OpenAI tương thích tùy chỉnh / ghi đè **Base URL**.
* Điền API Key bạn tạo trong Console của aicentos.
* Đặt Base URL thành: `https://aicentos.com/v1`
* Nếu cần thêm mô hình thủ công, điền tên mô hình trong Console (tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)).
* Lưu và nhấn **Verify**, hoặc trực tiếp tạo một hội thoại mới để thử.

## Kiểm tra

Sau khi lưu, trước tiên test nhẹ bằng một câu prompt đơn giản, xác nhận đã thông rồi mới chính thức dùng Composer / Chat.

## Lưu ý

* API Key tùy chỉnh thường chỉ có hiệu lực với các mô hình hội thoại tiêu chuẩn.
* **Tab completion** và một số khả năng **Agent** vẫn có thể đi dịch vụ tích hợp sẵn của Cursor.
* Khi Verify thất bại, kiểm tra: Base URL có đúng không (chỉ điền đến `/v1`), Key có khoảng trắng thừa không, mô hình có khả dụng không, số dư tài khoản có đủ không, đã chọn provider OpenAI tùy chỉnh chưa.

---

# Devin CLI

Nguồn: https://docs.aicentos.com/vi/clients/devin-cli

Language: vi

> Dùng aicentos trong Devin CLI —— kết nối qua cấu hình OpenAI tương thích

Devin CLI là client dòng lệnh của Devin, hỗ trợ chỉ định địa chỉ API OpenAI tương thích qua biến môi trường hoặc file cấu hình. Trỏ Base URL về aicentos, điền API Key, là có thể dùng các mô hình aicentos tích hợp ngay trong terminal.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Devin CLI tại trang "API Key" trong Console (khuyến nghị đặt tên `devin-cli` để dễ theo dõi mức sử dụng).

## Các bước cài đặt

Cần cài trước Node.js 18+ và npm:

```bash
node -v
npm -v
```

Cài toàn cục bằng npm:

```bash
npm install -g devin-cli
```

Sau khi cài xong, xác minh:

```bash
devin --version
```

## Các bước thiết lập

Hỗ trợ hai cách: biến môi trường và file cấu hình, biến môi trường có độ ưu tiên cao hơn.

### Cách một: biến môi trường (khuyến nghị)

```bash
export DEVIN_BASE_URL="https://aicentos.com/v1"
export DEVIN_API_KEY="your_api_key_here"
```

Muốn hiệu lực vĩnh viễn thì ghi vào `~/.zshrc` hoặc `~/.bashrc`, rồi thực hiện `source ~/.zshrc`.

### Cách hai: file cấu hình

Sửa `~/.devin/config.json`:

```json
{
  "apiKey": "your_api_key_here",
  "baseURL": "https://aicentos.com/v1",
  "model": "gpt-4o"
}
```

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Mô hình  | tên mô hình trong "Model Square" của Console |

## Kiểm tra

Sau khi cấu hình xong, chạy trực tiếp:

```bash
devin
```

Trong phiên hội thoại tương tác, gửi một câu prompt đơn giản, nhận được phản hồi bình thường tức là kết nối thành công. Nếu báo lỗi xác thực, kiểm tra `DEVIN_API_KEY` có đúng không, `DEVIN_BASE_URL` có kèm hậu tố `/v1` không, số dư tài khoản có đủ không.

## Lưu ý

* Base URL chỉ điền đến `/v1`, đừng bổ sung thành đường dẫn đầy đủ `/v1/chat/completions`
* Khi biến môi trường và file cấu hình cùng tồn tại, lấy biến môi trường làm chuẩn
* Khuyến nghị trước tiên dùng `GET /v1/models` xác nhận các mô hình nhìn thấy được, rồi mới điền Model ID

---

# Devin Desktop

Nguồn: https://docs.aicentos.com/vi/clients/devin-desktop

Language: vi

> Dùng aicentos trong Devin Desktop —— kết nối qua cài đặt OpenAI tương thích tùy chỉnh

Devin Desktop là client desktop của Devin, hỗ trợ địa chỉ API OpenAI tương thích tùy chỉnh. Trỏ Base URL về aicentos, điền API Key, là có thể dùng các mô hình aicentos tích hợp ngay trong client.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Devin Desktop tại trang "API Key" trong Console (khuyến nghị đặt tên `devin-desktop` để dễ theo dõi mức sử dụng).

## Các bước cài đặt

Tới trang chính thức của Devin tải gói cài đặt tương ứng với nền tảng:

* macOS: tải `.dmg` và kéo vào "Ứng dụng"
* Windows: tải trình cài `.exe` và chạy
* Linux: tải `.AppImage` hoặc `.deb` và cài theo cách của bản phân phối

Cài xong khởi động ứng dụng, đăng nhập rồi vào giao diện cài đặt.

## Các bước thiết lập

* Mở **Settings** (Cài đặt).
* Vào khu vực **Models** hoặc **AI Provider**.
* Tìm tùy chọn **OpenAI Compatible** / **Custom Provider** / ghi đè **Base URL**.
* Điền API Key bạn tạo trong Console của aicentos.
* Đặt Base URL thành: `https://aicentos.com/v1`
* Nếu cần thêm mô hình thủ công, điền tên mô hình trong "Model Square" của Console.
* Lưu cài đặt.

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Mô hình  | tên mô hình trong "Model Square" của Console |

## Kiểm tra

Sau khi lưu, tạo một hội thoại mới hoặc tác vụ code, dùng một câu prompt đơn giản để thử, xác nhận có thể trả về kết quả bình thường tức là kết nối thành công.

## Lưu ý

* Tên mục cài đặt có thể khác nhau giữa các phiên bản, mấu chốt là tìm được tùy chọn Base URL có thể sửa
* Base URL chỉ điền đến `/v1`, đừng viết thành đường dẫn đầy đủ `/v1/chat/completions`
* Nếu phiên bản chỉ hỗ trợ mô hình tích hợp sẵn chính thức, không thể sửa Base URL, thì không thể kết nối trực tiếp tới gateway này
* Khi Verify thất bại, kiểm tra: Key có khoảng trắng thừa không, mô hình có khả dụng không, số dư tài khoản có đủ không

---

# Droid

Nguồn: https://docs.aicentos.com/vi/clients/droid

Language: vi

> Dùng aicentos trong Factory Droid —— đăng ký mô hình tùy chỉnh qua settings.json (BYOK)

Droid là agent lập trình dòng lệnh do Factory phát hành, hỗ trợ BYOK: đăng ký mô hình tùy chỉnh trong `~/.factory/settings.json`, trỏ `baseUrl` về aicentos là được. Droid yêu cầu cửa sổ ngữ cảnh của mô hình ít nhất 64k, lưu ý khi chọn mô hình.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho Droid tại trang "API Key" trong Console (khuyến nghị đặt tên `droid` để dễ theo dõi mức sử dụng):

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền khi hết số dư: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| File cấu hình | `~/.factory/settings.json`                   |
| provider      | `generic-chat-completion-api`                |
| baseUrl       | `https://aicentos.com/v1`                    |
| apiKey        | `${AICENTOS_API_KEY}`                        |
| Mô hình       | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

### 1. Thiết lập biến môi trường API Key

```bash
export AICENTOS_API_KEY="sk-API-Key-của-bạn"
```

Ghi vào `~/.zshrc` hoặc `~/.bashrc` để lưu lâu dài.

### 2. Sửa settings.json

Sửa `~/.factory/settings.json`, thêm mảng `customModels`:

```json
{
  "customModels": [
    {
      "model": "gpt-4o",
      "displayName": "GPT-4o (aicentos)",
      "baseUrl": "https://aicentos.com/v1",
      "apiKey": "${AICENTOS_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192
    }
  ]
}
```

Các trường quan trọng:

| Trường        | Mô tả                                                                      |
| ------------- | -------------------------------------------------------------------------- |
| `model`       | Model ID thực tế gửi đến endpoint, cần khớp với "Model Square" của Console |
| `displayName` | Tên hiển thị trong bộ chọn mô hình, có thể tự đặt                          |
| `baseUrl`     | Địa chỉ API, nên có `/v1`                                                  |
| `apiKey`      | Hỗ trợ mở rộng `${VAR_NAME}`                                               |
| `provider`    | `anthropic` / `openai` / `generic-chat-completion-api`                     |

### 3. Chọn mô hình

Sau khi khởi động `droid`, chạy `/model`, chọn mô hình vừa đăng ký. **Sau khi sửa cấu hình, cần khởi động lại `droid` trong terminal mới** file mới được đọc lại.

## Kiểm tra

Sau khi chọn mô hình, gửi một yêu cầu đơn giản:

```
Trả lời trong một câu: 1+1 bằng mấy
```

Trả về bình thường nghĩa là kết nối thành công.

## Lưu ý

* **`provider` khuyến nghị điền `generic-chat-completion-api`**, nó đi giao thức OpenAI Chat Completions, cũng là lựa chọn đúng cho phần lớn kịch bản BYOK. Điền `openai` sẽ đi Responses API, và ở một số gateway giá trị này sẽ bỏ qua `base_url` trỏ thẳng đến `api.openai.com`; điền `anthropic` thì đi `/v1/messages`.
* **Dọn biến môi trường trước**. Nếu trong shell đã export `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` hoặc `ANTHROPIC_API_KEY`, chúng sẽ ghi đè file cấu hình, khiến yêu cầu vòng qua gateway bạn đã cấu hình. Trước khi kết nối nên `unset` các biến này.
* Droid đọc đồng thời `~/.factory/settings.json` và bản cũ `~/.factory/config.json`, file trước có ưu tiên cao hơn. Tên trường bản cũ là dạng snake\_case `custom_models` / `model_display_name` / `base_url` / `api_key`, và **không hỗ trợ** mở rộng `${VAR_NAME}`, khuyến nghị thống nhất dùng `settings.json`.
* Cửa sổ ngữ cảnh của mô hình ít nhất 64k, mô hình local quá nhỏ có thể hoạt động bất thường.
* Factory chỉ chạy benchmark cho giao diện chính thức Anthropic / OpenAI, tính tương thích của mô hình tùy chỉnh không được bảo đảm; đã biết subagent đôi khi sẽ fallback về giao diện chính thức của Anthropic.
* Thứ tự xử lý sự cố: có thấy mô hình trong `/model` không → biến môi trường có bị ANTHROPIC\_\* ghi đè không → baseUrl có `/v1` không → số dư có đủ không.

## Liên kết liên quan

* Tài liệu BYOK chính thức: [https://docs.factory.ai/model-independence/byok](https://docs.factory.ai/model-independence/byok)

---

# DSH 大肥魚

Nguồn: https://docs.aicentos.com/vi/clients/dsh

Language: vi

> Kết nối mô hình aicentos vào DeepSeek Harness (DSH), nuôi chú cá tự lướt Bilibili và Douyin, rồi đưa nó vào nhóm QQ

DSH (DeepSeek Harness) là framework Agent mã nguồn mở của DeepSeek. Bản desktop DSH Desktop đóng gói runtime, plugin và phiên làm việc vào một bộ cài duy nhất. « 大肥魚 » (cá béo) là plugin do cộng đồng phát triển tên `dsh-bili-whale`: một chú cá AI tự thức dậy theo nhịp sinh hoạt, lướt Bilibili, thực sự hiểu video, viết hai cuốn nhật ký và tag bạn vào những video đáng xem.

Trang này gồm bốn phần: nối DSH với aicentos, nuôi chú cá Bilibili, chuyển sang bản Douyin, và cuối cùng đưa nó vào tin nhắn riêng cùng nhóm QQ bằng plugin chính thức. Các plugin lần lượt do cộng đồng và Tencent duy trì, không liên kết với Bilibili, Douyin hay DeepSeek.

## Chuẩn bị

| Hạng mục           | Yêu cầu  | Ghi chú                                                                                            |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------- |
| DSH Desktop        | Bắt buộc | Tải bộ cài macOS / Windows từ trang chính thức; đã kèm runtime                                     |
| Node.js            | 18+      | Chỉ cần khi khởi động DSH bằng dòng lệnh; bộ công cụ plugin là `.mjs`, cần node thật               |
| ffmpeg             | Tùy chọn | Chỉ dùng cho việc trích khung hình; không có vẫn hiểu video qua phụ đề, danmaku, bình luận nổi bật |
| Tài khoản Bilibili | Một      | Tài khoản chú cá dùng, đăng nhập để lấy cookie; nên dùng tài khoản phụ                             |
| API Key aicentos   | Một      | Nên tạo Key riêng (đặt tên `dsh`) để theo dõi mức dùng theo dự án                                  |

* Bảng điều khiển: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền vào ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Cấu hình cần điền

| Trường       | Giá trị                                                      |
| ------------ | ------------------------------------------------------------ |
| Provider ID  | `aicentos`                                                   |
| Display name | `aicentos`                                                   |
| Base URL     | `https://aicentos.com/v1`                                    |
| API protocol | `openai-completions`                                         |
| API Key      | Key đã tạo trong bảng điều khiển                             |
| Model        | Tên mô hình trong «Quảng trường mô hình» của bảng điều khiển |

## Các bước thiết lập

### Cài DSH Desktop

Mở [https://www.dshdesktop.com/](https://www.dshdesktop.com/) , chọn bộ cài theo hệ điều hành (Windows, macOS chip M, macOS Intel) rồi nhấp đúp để cài. Lần khởi động đầu, làm theo hướng dẫn: cấu hình mô hình → tạo phiên, trò chuyện bình thường là xong.

### Kết nối aicentos trong DSH

Nên cấu hình qua giao diện:

1. Mở **Settings → Models**, bấm **Add a custom provider**.
2. Điền Provider ID, Display name, Base URL, API protocol, API Key theo bảng trên.
3. Trong **Model catalog** bấm **Fetch available models**, chọn các mô hình cần dùng; nếu không tải được thì nhập ID mô hình thủ công.
4. Bấm **Save**, quay lại khung trò chuyện và chọn mô hình ở ô chọn phía trên.

Cũng có thể sửa trực tiếp `~/.dsh/settings.yaml`:

```yaml
agent-default-model:
  provider: aicentos
  model: 你的模型名

llm-pi-ai:
  providers:
    aicentos:
      api: openai-completions
      baseURL: https://aicentos.com/v1
      apiKeyEnv: AICENTOS_API_KEY
      models:
        - id: 你的模型名
```

Sau đó đặt biến môi trường rồi khởi động:

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
```

API Key được lưu cục bộ trong `$DSH_HOME/.credentials.yaml`; giao diện không bao giờ hiển thị dạng văn bản thuần.

### Cài plugin chú cá

Không cần clone thủ công, chỉ cần gửi một dòng trong khung trò chuyện DSH:

```bash
帮我安装这个插件，插件地址：https://github.com/Alterssss/dsh-bili-whale
```

Cài xong hãy tải lại trang DSH, mở **Cài đặt → Nuôi cá** (养鱼) ở thanh bên trái để thấy trang cấu hình plugin. Nếu không thấy mục «Nuôi cá», hãy thoát hoàn toàn DSH rồi mở lại: plugin được lắp khi khởi động, không khởi động lại thì coi như chưa cài.

### Cấp toàn quyền cho phiên

Đây là bước dễ bỏ sót nhất. Phiên của cô ấy nằm trong **Không gian làm việc → Chưa phân nhóm** ở thanh bên trái (không mở thư mục đó thì không thấy). Mở phiên, chuyển quyền sang **Toàn quyền truy cập** (`danger-full-access`), nếu không sau khi thức dậy cô ấy không chạy được lệnh, không đăng được bình luận, không viết được nhật ký.

### Đăng nhập tài khoản Bilibili

Trong **Cài đặt → Nuôi cá → Đăng nhập Bilibili**, bấm **Đăng nhập bằng mã QR** rồi xác nhận bằng app Bilibili trên điện thoại. Mã QR có hiệu lực khoảng 3 phút; hủy hoặc hết hạn đều không thay thế trạng thái đăng nhập cũ.

Cũng có thể dán cookie thủ công: đăng nhập trên trình duyệt bằng tài khoản của chú cá, nhấn F12, chọn **Application → Cookies → `https://www.bilibili.com`**, sao chép `SESSDATA`, `bili_jct`, `buvid3`, dán lần lượt rồi bấm **Ghi thông tin xác thực**.

Đừng lấy cookie bằng `document.cookie`. `SESSDATA` là HttpOnly nên script không đọc được; làm theo cách đó sẽ chỉ nhận được cookie thiếu thành phần và bị kẹt ở bước kiểm tra.

### Kiểm tra phụ thuộc

Bấm **Kiểm tra phụ thuộc** trên trang cài đặt. Nó thực sự gửi một yêu cầu tới Bilibili để xác minh trạng thái đăng nhập, rồi kiểm tra từng mục cookie, ffmpeg, Node, thư mục dữ liệu, nhịp sinh hoạt. Phải xanh toàn bộ («tất cả khả dụng ✓») mới đạt.

Nếu báo thiếu ffmpeg, không cần tự tìm hướng dẫn: hãy gửi «cài ffmpeg trên máy này» trong khung trò chuyện DSH để nó tự xử lý, cài xong chạy lại kiểm tra.

Sửa xong nhất định phải bấm **Lưu**. Ô nhập chỉ thay đổi cục bộ, bấm lưu mới ghi xuống đĩa; trang cũng nhắc «có thay đổi chưa lưu = chưa có hiệu lực». Lưu là có hiệu lực ngay; chỉ khi thay mã nguồn hoặc phiên bản plugin mới cần khởi động lại DSH.

### Thiết lập nhân vật và nhịp sinh hoạt

* **Cô ấy là ai**: tên nhân vật, cách gọi bạn, cách cô ấy tự xưng.
* **Nhân vật của cô ấy**: nội dung ghi vào `~/.bili-ai/persona.md`, viết xong bấm **Tiêm nhân vật** (giới hạn 20000 ký tự, khi tiêm chỉ lấy 3000 ký tự đầu, đính kèm mỗi lần đánh thức và lắng nghe).
* **Bạn (chủ nhân)**: điền `mid` của bạn, cả tag và tin nhắn riêng đều dựa vào đó.
* **Cách chia sẻ**: tag bạn ở phần bình luận, hoặc tin nhắn riêng Bilibili.
* **Khung giờ sinh hoạt**: mặc định 20:00–24:00, thức dậy ở một thời điểm ngẫu nhiên trong khung, không phải đúng giờ tròn.

Plugin không có sẵn nhân vật nào, mặc định là trợ lý trung tính: không gọi bạn là «chủ nhân», không làm nũng. Muốn cô ấy thành «大肥魚», hãy viết rõ thân phận và xuất xứ, giọng điệu, điều cô ấy quan tâm và những việc tuyệt đối không làm.

## Kiểm tra

Trước hết chạy tự kiểm tra bằng dòng lệnh, nó kiểm tra một lượt cấu hình, thông tin xác thực, trạng thái đăng nhập, thư mục dữ liệu và phụ thuộc:

```bash
node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs selftest
```

Trên Windows thay đường dẫn bằng `%USERPROFILE%\.dsh\plugins\dsh-bili-whale\tools\bili.mjs`:

```powershell
node "$env:USERPROFILE\.dsh\plugins\dsh-bili-whale\tools\bili.mjs" selftest
```

Từng mục được đánh dấu và dòng cuối «全部通过 ✓ 可以用了» là đã sẵn sàng. Các lệnh thường dùng:

```bash
node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs deps           # kiểm tra phụ thuộc
node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs dm --status    # hạn mức tin nhắn riêng + theo dõi lẫn nhau
node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs traffic status # giá trị bảo vệ yêu cầu
```

Muốn xem cô ấy chạy ngay một vòng: đổi khung giờ sinh hoạt thành một khoảng hai phút tính từ bây giờ, lưu lại rồi chờ cô ấy thức (kiểm tra → chọn chủ đề → hiểu nội dung → viết hai cuốn nhật ký → gửi cho bạn). Cũng có thể yêu cầu trực tiếp trong khung trò chuyện để cô ấy thức và lướt Bilibili một lần.

Cuối cùng mở trang mức sử dụng trong bảng điều khiển aicentos để xác nhận yêu cầu được ghi vào Key bạn đã tạo cho DSH.

## Kết nối Douyin

Bản Douyin là một dự án khác với cùng ý tưởng: `dsh-douyin-scroll`. Nó không xem hình ảnh, chỉ đọc mô tả, thẻ, tác giả, thời lượng, chỉ số tương tác và bình luận nổi bật, chọn vài video mỗi ngày và viết báo cáo Markdown.

### Cài đặt

```bash
git clone https://github.com/NEWJO123/dsh-douyin-scroll.git
cd dsh-douyin-scroll
node selfcheck.mjs
```

Khi kiểm tra sơ bộ đều đạt, cài vào profile `web` rồi khởi động lại DSH một lần:

```bash
dsh plugin --profile web add "link:$PWD"
```

Sau khi khởi động lại, mở **Cài đặt → Lướt Douyin** (刷抖音).

### Cấu hình lần đầu

1. Bấm **Cài phụ thuộc chính**: nó tạo venv riêng và cài `curl_cffi`, `httpx` (khoảng 30 giây, xem tiến trình trong `install.log`).
2. Đăng nhập: chạy `node tools/qr-login.mjs start` để quét mã, hoặc dán cookie từ phiên Douyin đã đăng nhập trong trình duyệt vào trang cài đặt.
3. Điền «lướt gì»: từ khóa, danh mục, tác giả chỉ định, số video mỗi ngày, số ứng viên mỗi vòng, rồi bấm **Chạy một vòng ngay**.

Cookie lưu trên máy tại `$DSH_HOME/douyin-duty/douyin_cookie.txt`, không vào log và không tải lên máy chủ nào.

### Khả năng và giới hạn

| Hạng mục        | Chi tiết                                                                                                                   |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Căn cứ đánh giá | Mô tả, thẻ, tác giả, thời lượng, tỷ lệ tương tác, bình luận nổi bật; không xem hình, không nhận dạng giọng nói             |
| Nguồn ứng viên  | Luồng đề xuất chỉ đọc và bảng xu hướng; web Douyin không có API tìm kiếm dùng được, từ khóa chỉ để chú thích trong báo cáo |
| Báo cáo         | Ghi vào `out/<ngày>.md`; tùy chọn thông báo Windows hoặc webhook                                                           |
| Gửi             | Tin nhắn riêng, thẻ chia sẻ, bình luận mặc định đều tắt và đều cần `confirm`                                               |
| Nhóm chat       | Quan sát của tác giả là «trong nhóm có thể không gửi được»; tài khoản khác có thể khác                                     |

URL dạng văn bản thuần không mở được trong Douyin, chỉ thẻ chia sẻ mới bấm được. Gửi tin nhắn, thẻ, bình luận cần cài Chrome (chỉ tìm `chrome.exe`, không dùng Edge); lấy ứng viên và viết báo cáo thì không cần. Bình luận thường xuyên sẽ bị kiểm soát tần suất, và độ chính xác thấp hơn bản Bilibili: không có phụ đề nên chỉ đọc được phản ứng của khán giả.

## Kết nối nhóm QQ

QQ Bot có plugin chính thức `@tencent-connect/dsh-qqbot`, cài vào profile `qqbot` riêng; sau khi quét mã liên kết, nó trò chuyện được trong tin nhắn riêng và nhóm QQ.

```bash
npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot
npx @deepseek-ai/dsh --profile qqbot
```

Lần khởi động đầu, quét mã QR theo hướng dẫn, không cần nhập khóa thủ công. Sau khi liên kết:

* **Tách phiên**: mỗi cuộc trò chuyện riêng và mỗi nhóm có ngữ cảnh riêng, không lẫn nhau, và tự khôi phục sau khi khởi động lại.
* **Đổi mô hình trong chat**: đổi trực tiếp trong cuộc trò chuyện, ngữ cảnh cũ vẫn giữ nguyên, không phải bắt đầu lại.
* **Chế độ yên tĩnh**: đặt thành chỉ trả lời khi được @ để không làm phiền nhóm.

Mô hình được cấu hình trong profile `qqbot`: mở **Settings → Models → Add a custom provider** ở đó và điền aicentos theo bảng phía trên. Nếu muốn quản lý nhiều kênh IM một chỗ, tham khảo bundle cộng đồng `dsh-im` — một bundle cho mười kênh, hỗ trợ nhiều bot và trả lời dạng streaming.

Hội thoại trong nhóm được đọc vào ngữ cảnh và gửi cho mô hình, nên đừng để nó xử lý tài khoản hay khóa trong nhóm; thông tin liên kết lưu trong profile cục bộ, đừng đồng bộ cả thư mục profile lên kho công khai.

## Thú cưng trên desktop và dọn bình luận

Hai plugin tùy chọn, là dự án khác với chú cá:

| Mục đích                                | Dự án                                                                                  | Cách cài                                                                                                                              |
| --------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Chú cá động trên desktop                | [https://github.com/QCYTSN/dsh-dafeiyu](https://github.com/QCYTSN/dsh-dafeiyu)         | Cũng gửi URL cho DSH để nó cài; một cửa sổ gốc trong suốt xuất hiện, kéo được, đổi hoạt ảnh theo trạng thái tác vụ                    |
| Ẩn tài khoản nghi là AI trong bình luận | [https://github.com/liyupi/dafeiyu-cleaner](https://github.com/liyupi/dafeiyu-cleaner) | Tiện ích trình duyệt: tải zip trong Releases, giải nén, mở `chrome://extensions`, bật chế độ nhà phát triển, tải tiện ích đã giải nén |

Tiện ích dọn dẹp chỉ ẩn bình luận trong trình duyệt của bạn, không xóa bình luận của ai, không tự báo cáo, tài khoản bị đánh giá sai có thể khôi phục. Tỷ lệ nhận diện theo bộ quy tắc ngoại tuyến khoảng 85%, con số đo trong một mục bình luận và có thể không đúng ở cộng đồng khác.

## Lưu ý

* **Đừng bật bình luận tự động vội.** Mặc định đang tắt; khi bật, mỗi vòng chỉ đăng 1 bình luận, tối đa 20, mỗi video chỉ một lần. Dù vậy, việc đăng tràn lan vẫn thành «thảm họa cá» với người khác. Nên bắt đầu bằng tin nhắn riêng Bilibili gửi cho chính mình.
* **Kênh tin nhắn riêng cần hai tài khoản.** Chọn tin nhắn riêng Bilibili cần hai tài khoản khác nhau và theo dõi lẫn nhau (`relation.attribute === 6`). Chỉ có một tài khoản thì xem video, viết nhật ký, tạo báo cáo vẫn dùng được, còn tin nhắn riêng thì không.
* **Dùng tài khoản phụ để cấp quyền.** Plugin nói bằng chính tài khoản của bạn, đừng đưa cookie tài khoản chính cho plugin bên thứ ba và đừng mua tài khoản không rõ nguồn gốc.
* **Gặp kiểm soát rủi ro là dừng ngay.** Khi gặp 412 / 429, captcha hay giới hạn tần suất, plugin tạm dừng 5–30 phút và báo lại; đừng thử lại liên tục, endpoint có chữ ký cũng không bảo đảm vượt qua giới hạn của nền tảng.
* **Chọn mô hình rẻ.** Mỗi ngày cô ấy lọc 5 video, đọc sâu 2–3 video và viết hai cuốn nhật ký, một vòng là nhiều yêu cầu. Nên chọn trong aicentos mô hình có đơn giá thấp, ngữ cảnh đủ dùng (xem [mô hình được hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)) và tạo Key riêng cho DSH để tính chi phí.
* **Chế độ không giao diện không chạy được.** Plugin phải chạy trên DSH có giao diện web, nếu không sẽ dừng ở `pending (waiting for services: sessionController, webServer, connection)`.
* Plugin là bản công khai của một công cụ cá nhân, không liên kết với Bilibili hay DeepSeek; bạn dùng chính tài khoản của mình và tự chịu trách nhiệm, hãy tuân thủ quy định cộng đồng của nền tảng.

## Liên kết liên quan

* [Kho plugin dsh-bili-whale](https://github.com/Alterssss/dsh-bili-whale)
* [Kho plugin dsh-douyin-scroll](https://github.com/NEWJO123/dsh-douyin-scroll)
* [Tài liệu chính thức QQ Bot](https://bot.qq.com/wiki/agent-qqbot/)
* [Trang chính thức DSH Desktop](https://www.dshdesktop.com/)
* [Mã nguồn DSH Desktop](https://github.com/dataelement/dsh-desktop)
* [Lịch sử thay đổi plugin](https://github.com/Alterssss/dsh-bili-whale/blob/main/CHANGELOG.md)
* [Mô hình aicentos hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)

---

# Freebuff

Nguồn: https://docs.aicentos.com/vi/clients/freebuff

Language: vi

> Freebuff không cần API Key, cũng không có cấu hình endpoint tùy chỉnh —— giải thích lý do và phương án thay thế

Điểm bán của Freebuff là "không cần đăng ký gói, không cần hạn mức, không cần API Key", mô hình đến từ danh mục tích hợp sẵn, chi phí do hệ thống tài khoản của chính nó gánh. Vì vậy nó **không có mục cấu hình Base URL và Key**, không thể kết nối aicentos.

## Vì sao không thể kết nối trực tiếp

README chính thức ghi rõ `No subscription, credits, or API key required`, trong cấu hình cũng không có các trường kiểu `baseUrl`, `apiKey`.

Bản desktop của nó có thể host Claude Code, Codex đã cài sẵn trên máy, và tái sử dụng tài khoản provider của chính các công cụ đó —— nhưng đó là **CLI được host** quyết định mô hình, không phải cấu hình mô hình của Freebuff. Muốn đi đường này để dùng aicentos, phải cấu hình ở phía CLI được host (xem [Claude Code](https://docs.aicentos.com/vi/clients/claude-code), [Codex CLI](https://docs.aicentos.com/vi/clients/codex-cli)).

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Mô hình  | tên mô hình trong "Model Square" của Console |

Bảng trên là tham số chung phía aicentos, dùng cho phương án thay thế dưới đây.

## Phương án thay thế

* Cần agent lập trình trong terminal: [Craft Agent](https://docs.aicentos.com/vi/clients/craft-agent), [Gajae Code](https://docs.aicentos.com/vi/clients/gajae-code), [Oh My Pi](https://docs.aicentos.com/vi/clients/oh-my-pi).
* Muốn thử trước bằng hạn mức miễn phí: dùng hạn mức dùng thử của Console, xác nhận mô hình phù hợp rồi mới đổi sang client hỗ trợ endpoint tùy chỉnh.
* Chỉ muốn dùng vỏ desktop của nó để host CLI khác: cấu hình aicentos ở phía Claude Code / Codex CLI là được.

## Kiểm tra

Sau khi đổi sang một client thay thế bất kỳ, gửi một câu prompt xác nhận kết nối thông, rồi quay lại Console đối chiếu mức sử dụng.

## Lưu ý

* "Miễn phí" nghĩa là mô hình không chọn được, cũng không đổi được nhà cung cấp, đừng tìm mục cài đặt theo hướng "có thể cấu hình".
* Tài liệu chính thức đề cập một số khu vực bị hạn chế, hoặc bị giới hạn tốc độ khi bật VPN.

## Liên kết liên quan

* [Freebuff CLI](https://freebuff.com/cli)
* [Kho freebuff](https://github.com/CodebuffAI/freebuff)

---

# Fx

Nguồn: https://docs.aicentos.com/vi/clients/fx

Language: vi

> Dùng aicentos trong Fx —— thêm kết nối mô hình tùy chỉnh qua settings.json cấp người dùng

Fx là agent lập trình của Vercel Labs, viết bằng Zig thành một binary gốc duy nhất, độc lập mô hình. Kết nối mô hình tùy chỉnh được định nghĩa trong `~/.fx/settings.json` cấp người dùng, trỏ base URL về aicentos là được.

**Nói trước một cái bẫy dễ dính:** `.fx.json` trong thư mục gốc dự án là chuyện khác, nó cố ý không cho phép phần lớn các trường (kể cả mô hình), để tránh repo được clone về làm thay mô hình hoặc endpoint của bạn. **Endpoint tùy chỉnh bắt buộc phải ghi trong `~/.fx/settings.json`**, ghi trong `.fx.json` sẽ không có hiệu lực.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho Fx tại trang "API Key" trong Console (khuyến nghị đặt tên `fx` để dễ theo dõi mức sử dụng):

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền khi hết số dư: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Xác nhận đã cài Fx:

```bash
curl -fsSL https://fx.sh/setup.sh | bash
fx --version
```

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| File cấu hình | `~/.fx/settings.json`                        |
| Base URL      | `https://aicentos.com/v1`                    |
| API Key       | Key tạo trong Console                        |
| Mô hình       | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

### 1. Sửa thiết lập cấp người dùng

Trong `~/.fx/settings.json`, đăng ký một kết nối theo định dạng "kết nối mô hình tùy chỉnh". Cấu trúc trường của đối tượng kết nối lấy tài liệu chính thức làm chuẩn:

* Trang tài liệu: [https://fx.sh/docs](https://fx.sh/docs)
* README: [https://github.com/vercel-labs/fx](https://github.com/vercel-labs/fx)

Điền địa chỉ API trong kết nối thành:

```
https://aicentos.com/v1
```

API Key điền cái đã tạo trong Console, tên mô hình lấy "Model Square" của Console làm chuẩn.

### 2. Chỉ định dùng kết nối này

Fx cho phép khi khởi động chỉ định provider và mô hình:

```bash
fx provider local FX_MODEL=gpt-4o fx ask "Trả lời trong một câu: 1+1 bằng mấy"
```

Cũng có thể chỉ định qua biến môi trường:

```bash
export FX_MODEL="gpt-4o"
```

### 3. Xác nhận provider hiện tại

Fx ghi nhớ lựa chọn theo provider, lần khởi động sau tiếp tục dùng provider lần trước.

## Kiểm tra

Trước dùng một prompt không có tác dụng phụ để xác minh kết nối:

```bash
fx ask "Trả lời trong một câu: 1+1 bằng mấy"
```

Trả về bình thường nghĩa là kết nối thành công. Nếu báo lỗi xác thực, ưu tiên kiểm tra base URL có `/v1` không, API Key có khoảng trắng thừa không.

## Lưu ý

* **Đừng sửa `.fx.json`**. File cấp dự án chỉ cho phép vài trường như `provider_order`, `provider_strict`, không có trường `model`, cũng không dùng để cấu hình endpoint tùy chỉnh.
* `provider_order` / `provider_strict` là tham số định tuyến của Vercel AI Gateway, **chỉ có hiệu lực với yêu cầu Gateway, kết nối mô hình tùy chỉnh sẽ bỏ qua chúng**, đừng trông chờ dùng chúng để chuyển upstream.
* Hỗ trợ của Fx chính thức cho kết nối mô hình tùy chỉnh vẫn đang tiếp tục hoàn thiện, bản đầu có thể cần build mới hơn mới nhận diện được; sau khi nâng cấp, chạy thử một lần lệnh kiểm tra ở trên rồi mới dùng chính thức.
* Script cài binary này sẽ tải từ mạng, trước khi chạy hãy tự xác nhận nguồn đáng tin cậy.

## Liên kết liên quan

* Trang chủ dự án: [https://github.com/vercel-labs/fx](https://github.com/vercel-labs/fx)

---

# Gajae Code

Nguồn: https://docs.aicentos.com/vi/clients/gajae-code

Language: vi

> Dùng aicentos trong Gajae Code (gjc) —— thêm một provider tương thích OpenAI vào models.yml

Provider của Gajae Code được định nghĩa trong `~/.gjc/agent/models.yml`, các trường là `baseUrl` / `api` / `apiKey`, thêm một đoạn là có thể trỏ về aicentos.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Gajae Code trong Console (khuyến nghị đặt tên `gajae-code`), sau đó cài CLI:

```bash
curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/gajae-code/v0.15.3/scripts/install.sh -o gjc-install.sh
sh gjc-install.sh
gjc --version
```

## Cấu hình cần điền

| Trường                    | Giá trị                                         |
| ------------------------- | ----------------------------------------------- |
| Tên provider              | tự đặt, ví dụ `aicentos`                        |
| `baseUrl`                 | `https://aicentos.com/v1`                       |
| `api`                     | `openai-completions`                            |
| `apiKey` hoặc `apiKeyEnv` | ghi trực tiếp Key, hoặc ghi tên biến môi trường |
| `models[].id`             | tên mô hình trong "Model Square" của Console    |

## Các bước thiết lập

Chỉnh sửa `~/.gjc/agent/models.yml`:

```yaml
providers:
  aicentos:
    baseUrl: https://aicentos.com/v1
    api: openai-completions
    apiKeyEnv: AICENTOS_API_KEY
    discovery:
      type: openai-models-list
    models:
      - id: tên-mô-hình-của-bạn
        contextWindow: 128000
        maxTokens: 8192
```

Trỏ mô hình mặc định về đó:

```yaml
modelBindings:
  modelRoles:
    default: aicentos/tên-mô-hình-của-bạn:high
```

Sau đó export Key rồi khởi động:

```bash
export AICENTOS_API_KEY="sk-API-Key-của-bạn"
gjc
```

Đoạn `discovery` giúp nó tự kéo danh sách mô hình; nếu bạn muốn tự kiểm soát các mô hình hiển thị, bỏ đoạn này, chỉ giữ `models`.

## Kiểm tra

Khởi động `gjc`, xác nhận trong bộ chọn mô hình có các mô hình dưới `aicentos`, gửi một câu prompt xác nhận trả về được. Khi danh sách trống, trước tiên kiểm tra thụt lề của `models.yml` và đoạn `discovery`.

## Lưu ý

* `models.yml` kiểm tra nghiêm ngặt, trường không xác định sẽ báo lỗi ngay. Đừng chép kiểu viết gạch dưới như `api_key`, `base_url` từ công cụ khác, ở đây yêu cầu camelCase `baseUrl`, `apiKey`.
* `contextWindow` và `maxTokens` điền theo mô hình thực tế, ghi quá lớn sẽ bị phía trên từ chối.
* Trong `modelRoles.default`, `:high` là hậu tố cường độ suy luận, đổi sang mức khác hoặc bỏ đi tùy nhu cầu.
* Dự án tự mô tả là experimental, sau khi nâng cấp các trường có thể thay đổi, lấy `docs/models.md` trong kho làm chuẩn.

## Liên kết liên quan

* [Kho gajae-code](https://github.com/Yeachan-Heo/gajae-code)

---

# Gemini CLI

Nguồn: https://docs.aicentos.com/vi/clients/gemini-cli

Language: vi

> Dùng aicentos trong Gemini CLI —— cấu hình gateway tùy chỉnh qua biến môi trường

Gemini CLI là công cụ dòng lệnh do Google chính thức phát hành, hỗ trợ cấu hình gateway tùy chỉnh qua biến môi trường để kết nối dịch vụ Codex Proxy, cho phép trò chuyện tương tác với các mô hình Gemini ngay trong terminal.

## Chuẩn bị

Gemini CLI cài toàn cục qua npm, cần chuẩn bị sẵn môi trường Node.js 18+ và npm trước.

### Cài Node.js

* Truy cập trang tải chính thức của Node.js: [https://nodejs.org/en/download](https://nodejs.org/en/download)
* macOS/Windows: tải và cài bản LTS
* Linux: cài theo cách của bản phân phối được hướng dẫn trên trang
* macOS (người dùng Homebrew): chạy `brew install node`

### Kiểm tra cài đặt

```bash
node -v
npm -v
```

## Cài đặt Gemini CLI

Cài toàn cục Gemini CLI bằng npm:

```bash
npm install -g @google/gemini-cli
```

Xác minh cài đặt:

```bash
gemini --version
```

## Cấu hình biến môi trường

Gemini CLI hỗ trợ kết nối gateway tùy chỉnh qua ba biến môi trường sau:

| Biến môi trường          | Mô tả                                                              |
| ------------------------ | ------------------------------------------------------------------ |
| `GOOGLE_GEMINI_BASE_URL` | Địa chỉ gốc dịch vụ gateway, thay thế endpoint mặc định của Google |
| `GEMINI_API_KEY`         | API Key của bạn                                                    |
| `GEMINI_MODEL`           | Mô hình dùng mặc định                                              |

### Ví dụ cấu hình

```bash
export GOOGLE_GEMINI_BASE_URL="https://aicentos.com"
export GEMINI_API_KEY="your_api_key_here"
export GEMINI_MODEL="gemini-2.0-flash"
```

### Lưu ý

* `GOOGLE_GEMINI_BASE_URL` điền địa chỉ gốc dịch vụ, không cần kèm đường dẫn API cụ thể
* Thử tạm thời: chạy trực tiếp các lệnh export trên trong phiên shell hiện tại
* Hiệu lực vĩnh viễn: thêm các câu export vào `~/.zshrc` hoặc `~/.bashrc`, rồi chạy `source ~/.zshrc` để có hiệu lực

## Khởi động Gemini CLI

Sau khi cấu hình xong, chạy trực tiếp lệnh sau để khởi động:

```bash
gemini
```

Sau khi khởi động là có thể trò chuyện tương tác với các mô hình Gemini ngay trong terminal.

## Xác minh kết nối

Mở một hội thoại trong Gemini CLI, nếu nhận được phản hồi bình thường nghĩa là kết nối thành công.

### Xử lý sự cố thường gặp

* Nếu gặp lỗi xác thực, hãy xác nhận `GEMINI_API_KEY` có đúng không
* Kiểm tra `GOOGLE_GEMINI_BASE_URL` có trỏ đúng địa chỉ dịch vụ không

## Lưu ý

* Dịch vụ hiện tại đã hỗ trợ giao diện tương thích Gemini, có thể dùng trực tiếp cho Gemini CLI
* Cấu hình biến môi trường nên thêm vào file cấu hình shell để có hiệu lực vĩnh viễn
* Gemini CLI tự nối đường dẫn API, không cần thêm đường dẫn API cụ thể vào BASE\_URL

## Liên kết liên quan

* Tài liệu chính thức: [https://docs.aicentos.com/clients/gemini-cli.html](https://docs.aicentos.com/clients/gemini-cli.html)

---

# Goose

Nguồn: https://docs.aicentos.com/vi/clients/goose

Language: vi

> Dùng aicentos trong Goose —— khai báo provider tương thích OpenAI tùy chỉnh

Goose là agent lập trình mã nguồn mở của Block, hỗ trợ hai cách trỏ đến một endpoint tương thích OpenAI: tái sử dụng provider `openai` tích hợp sẵn và ghi đè host, hoặc khai báo một provider tùy chỉnh độc lập. Khuyến nghị cách sau, thông tin endpoint tập trung hơn, cũng tiện để giữ đồng thời nhiều bộ cấu hình.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho Goose tại trang "API Key" trong Console (khuyến nghị đặt tên `goose` để dễ theo dõi mức sử dụng):

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền khi hết số dư: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Cấu hình cần điền

| Trường                  | Giá trị                                          |
| ----------------------- | ------------------------------------------------ |
| File provider tùy chỉnh | `~/.config/goose/custom_providers/aicentos.json` |
| engine                  | `openai`                                         |
| base\_url               | `https://aicentos.com/v1/chat/completions`       |
| api\_key\_env           | `AICENTOS_API_KEY`                               |
| Mô hình                 | tên mô hình trong "Model Square" của Console     |

## Các bước thiết lập

### 1. Thiết lập biến môi trường API Key

```bash
export AICENTOS_API_KEY="sk-API-Key-của-bạn"
```

Ghi vào `~/.zshrc` hoặc `~/.bashrc` để lưu lâu dài. **Đừng ghi key vào config.yaml**, trang chính thức khuyến nghị rõ ràng dùng biến môi trường hoặc keychain hệ thống.

### 2. Khai báo provider tùy chỉnh

Tạo mới `~/.config/goose/custom_providers/aicentos.json` (trên Windows là `%APPDATA%\Block\goose\config\custom_providers\`):

```json
{
  "name": "aicentos",
  "engine": "openai",
  "display_name": "aicentos",
  "description": "Các mô hình do aicentos tích hợp",
  "api_key_env": "AICENTOS_API_KEY",
  "base_url": "https://aicentos.com/v1/chat/completions",
  "models": [
    {
      "name": "gpt-4o",
      "context_limit": 128000
    }
  ],
  "supports_streaming": true,
  "dynamic_models": true
}
```

Các trường bắt buộc là `name`, `engine`, `display_name`, `base_url`, `models`, trong đó `engine` nhận giá trị `openai` / `anthropic` / `ollama`.

Tên mô hình lấy "Model Square" của Console làm chuẩn, có thể tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list).

### 3. Đặt làm mặc định trong config.yaml

Sửa `~/.config/goose/config.yaml`:

```yaml
GOOSE_PROVIDER: aicentos
GOOSE_MODEL: gpt-4o
```

Khi khởi động, Goose sẽ quét thư mục `custom_providers/` và tự động đăng ký, sau đó cũng có thể chuyển đổi trong giao diện đồ hoạ.

## Kiểm tra

Trước dùng phiên không tương tác để xác minh:

```bash
goose run -t "Trả lời trong một câu: 1+1 bằng mấy"
```

Trả về bình thường nghĩa là kết nối thành công.

## Lưu ý

* **`base_url` phải ghi đến đường dẫn đầy đủ** (ở đây có `/v1/chat/completions`), khác với cách viết của phần lớn client. Nếu cần chỉ định đường dẫn tường minh, bản mới còn hỗ trợ trường `base_path`, độ ưu tiên của nó cao hơn việc phân tích URL.
* **Biến môi trường có độ ưu tiên cao hơn config.yaml**. Nếu trong shell đã export `OPENAI_HOST`, nó sẽ âm thầm ghi đè cấu hình trong file, khi xử lý sự cố chạy `env | grep -i openai` trước.
* Chỉ khi đã chọn provider, Goose mới khởi động bình thường. Nếu đã ghi cấu hình trong `config.yaml` nhưng chưa từng chạy `goose configure`, có thể báo `No provider configured` — đây là hiểu lầm phổ biến, mục cấu hình vốn là định dạng YAML, không phải `.env`.
* Khi `dynamic_models: true`, Goose sẽ gọi `/v1/models` của endpoint để kéo danh sách mô hình; nếu chỉ muốn hiển thị các mô hình chỉ định, xoá trường này hoặc đặt thành `false`.
* Một cách làm đơn giản khác là tái sử dụng provider tích hợp sẵn: đặt `GOOSE_PROVIDER: openai` trong config.yaml, rồi dùng `OPENAI_HOST` cộng `OPENAI_BASE_PATH` để ghép endpoint. Cách này đỡ tốn công hơn, nhưng liên kết chặt với biến môi trường hơn, dễ dính vấn đề ghi đè nêu trên.
* Thứ tự xử lý sự cố: tên provider có khớp hoàn toàn với tên file JSON không → `base_url` có chứa đường dẫn đầy đủ không → biến môi trường có hiển thị không → số dư có đủ không.

## Liên kết liên quan

* Tài liệu Provider tùy chỉnh: [https://block.github.io/goose/docs/api/providers/custom](https://block.github.io/goose/docs/api/providers/custom)

---

# Grok Build

Nguồn: https://docs.aicentos.com/vi/clients/grok-build

Language: vi

> Kết nối aicentos trong Grok Build —— tự định nghĩa model provider qua config.toml

Grok Build là terminal coding Agent của xAI, mặc định gọi giao diện chính thức của xAI, nhưng nó hỗ trợ khai báo endpoint OpenAI tương thích bất kỳ dạng `[model.*]` trong `~/.grok/config.toml`. Trỏ endpoint về aicentos, là có thể dùng cùng một Key gọi các mô hình dòng grok và các mô hình của nhà cung cấp khác.

## Chuẩn bị

* Cài Grok Build (script chính thức):

  ```bash
  curl -fsSL https://x.ai/cli/install.sh | bash
  ```

* Tạo một Key chuyên dụng trong Console của aicentos (khuyến nghị đặt tên `grok-build`).

## Cấu hình cần điền

| Trường          | Giá trị                                                                        |
| --------------- | ------------------------------------------------------------------------------ |
| base\_url       | `https://aicentos.com/v1`                                                      |
| api\_backend    | `chat_completions` (giá trị mặc định)                                          |
| env\_key        | `AICENTOS_API_KEY`                                                             |
| model           | model ID trong "Model Square" của Console, ví dụ `grok-4.7`, `claude-opus-4-8` |
| context\_window | điền theo mô hình đã chọn, ví dụ `200000`                                      |

## Các bước thiết lập

* Ghi Key vào biến môi trường shell (ghi vào `~/.zshrc` hoặc `~/.bashrc` rồi `source` để có hiệu lực):

  ```bash
  export AICENTOS_API_KEY="your_api_key_here"
  ```

* Sửa `~/.grok/config.toml`, thêm một mô hình tùy chỉnh:

  ```toml
  [models]
  default = "aicentos-grok"

  [model.aicentos-grok]
  base_url          = "https://aicentos.com/v1"
  env_key           = "AICENTOS_API_KEY"
  api_backend       = "chat_completions"
  context_window    = 200000
  max_completion_tokens = 8192
  description       = "aicentos gateway - grok-4.7"
  ```

  `<name>` trong `[model.<name>]` chính là model ID; nếu muốn kết nối nhiều mô hình, ví dụ `grok-4.7` và `claude-opus-4-8`, thì lần lượt viết thêm một đoạn `[model.grok-4.7]`, `[model.claude-opus-4-8]`.

* Khởi động Grok Build, dùng bộ chọn mô hình hoặc lệnh để chuyển:

  ```bash
  grok
  /model aicentos-grok
  ```

## Kiểm tra

Trước tiên liệt kê xem mô hình có được nhận diện không:

```bash
grok models
```

Rồi gửi một câu prompt nhẹ (ví dụ `grok -p "giới thiệu thư mục hiện tại trong một câu" -m aicentos-grok`) xác nhận có thể trả về bình thường.

## Lưu ý

* Grok Build **không có tham số dòng lệnh `--base-url`**, endpoint tùy chỉnh chỉ có thể chỉ định qua file cấu hình hoặc biến môi trường.
* `api_backend` mặc định đã là `chat_completions`; nếu ghi rõ thành `responses` hoặc `messages`, cần xác nhận gateway hỗ trợ endpoint tương ứng, nếu không sẽ thất bại.
* Thứ tự phân giải thông tin xác thực: `api_key` trong cấu hình mô hình → biến môi trường do `env_key` chỉ định → token phiên đã đăng nhập → `XAI_API_KEY` toàn cục. Ở đây dùng `env_key` tham chiếu tên biến của bạn là được, sẽ không lẫn sang tài khoản chính thức của xAI.
* Nếu mô hình thêm mới bỏ qua `context_window`, Grok Build mặc định xử lý theo 200,000; khuyến nghị điền rõ theo mô hình đã chọn.
* Sau khi nối endpoint tùy chỉnh sẽ không còn phụ thuộc gói đăng ký xAI, nhưng mô hình được chọn vẫn do phía aicentos tính phí, trước tiên vào [trang Ví](https://aicentos.com/wallet) xác nhận số dư.

---

# Grok CLI

Nguồn: https://docs.aicentos.com/vi/clients/grok-cli

Language: vi

> Dùng aicentos trong Grok CLI —— kết nối qua biến môi trường hoặc file cấu hình

Grok CLI là một công cụ dòng lệnh, dùng giao diện tương thích OpenAI, có thể trực tiếp trỏ địa chỉ API tùy chỉnh về làm dịch vụ backend của nó.

## Chuẩn bị

Cần cài trước Node.js 18+ và npm.

Khuyến nghị cài từ trang tải chính thức của Node.js: [https://nodejs.org/en/download](https://nodejs.org/en/download)

* macOS/Windows: tải và cài bản LTS
* Linux: cài theo cách của bản phân phối

Người dùng macOS cũng có thể dùng Homebrew:

```bash
brew install node
```

Sau khi cài xong, xác nhận:

```bash
node -v
npm -v
```

## Cài đặt Grok CLI

Cài toàn cục bằng npm:

```bash
npm install -g @vibe-kit/grok-cli
```

Sau khi cài xong, kiểm tra:

```bash
grok --version
```

## Cấu hình kết nối

Grok CLI cung cấp ba cách cấu hình, thứ tự ưu tiên: tham số dòng lệnh > biến môi trường > file cấu hình.

### Cách 1: Biến môi trường (khuyến nghị)

Thiết lập các biến môi trường sau:

```bash
export GROK_BASE_URL="https://aicentos.com/v1"
export GROK_API_KEY="your_api_key_here"
```

Thử tạm thời thì chỉ cần chạy export trong shell hiện tại. Muốn hiệu lực vĩnh viễn, thêm các câu lệnh trên vào `~/.zshrc` hoặc `~/.bashrc`, rồi chạy `source ~/.zshrc` để có hiệu lực.

### Cách 2: File cấu hình

Sửa `~/.grok/user-settings.json`:

```json
{
  "apiKey": "your_api_key_here",
  "baseURL": "https://aicentos.com/v1",
  "defaultModel": "gpt-4o"
}
```

### Cách 3: Tham số dòng lệnh

Khi khởi động, chỉ định qua tham số:

```bash
grok --base-url https://aicentos.com/v1
```

## Khởi động và sử dụng

Sau khi cấu hình xong, chạy trực tiếp:

```bash
grok
```

Sau khi khởi động, mở hội thoại trong Grok CLI, nếu nhận được phản hồi bình thường nghĩa là kết nối thành công.

## Xác minh và xử lý sự cố

Nếu gặp lỗi xác thực, hãy kiểm tra:

* `GROK_API_KEY` có đúng không
* `GROK_BASE_URL` / `baseURL` có trỏ đúng địa chỉ dịch vụ không (cần có hậu tố `/v1`)

Sau khi xác nhận cấu hình không sai, khởi động lại là được.

## Lưu ý

* Grok CLI dùng giao diện tương thích OpenAI, cấu hình đơn giản trực tiếp
* Ba cách cấu hình có thể chọn linh hoạt, khuyến nghị dùng cách biến môi trường
* Địa chỉ API bắt buộc phải chứa hậu tố `/v1`
* Hỗ trợ tùy chỉnh mô hình mặc định

## Liên kết liên quan

* Tài liệu chính thức: [https://docs.aicentos.com/clients/grok-cli.html](https://docs.aicentos.com/clients/grok-cli.html)

---

# Hermes Agent

Nguồn: https://docs.aicentos.com/vi/clients/hermes-agent

Language: vi

> Dùng aicentos trong Hermes Agent —— chỉ định endpoint OpenAI tương thích qua biến môi trường

Hermes Agent đọc thông tin kết nối của dịch vụ mô hình qua biến môi trường. Trỏ Base URL về aicentos, là có thể cho toàn bộ các yêu cầu suy luận của Agent đi qua các mô hình aicentos tích hợp.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Hermes Agent tại trang "API Key" trong Console (khuyến nghị đặt tên `hermes-agent` để dễ theo dõi mức sử dụng).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)
* Trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

## Cấu hình cần điền

| Trường            | Giá trị                                      |
| ----------------- | -------------------------------------------- |
| OPENAI\_BASE\_URL | `https://aicentos.com/v1`                    |
| OPENAI\_API\_KEY  | Key tạo trong Console                        |
| Model             | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

Cấu hình trong cùng một shell chạy Agent:

```bash
export OPENAI_BASE_URL="https://aicentos.com/v1"
export OPENAI_API_KEY="sk-key-của-bạn"
export OPENAI_MODEL="gpt-4o"
```

Rồi khởi động Hermes Agent theo cách bình thường. Muốn lưu lâu dài, hãy ghi các `export` ở trên vào `~/.zshrc` hoặc `~/.bashrc`, và `source` lại một lần.

Nếu Hermes Agent có file cấu hình riêng, cũng có thể chỉ định base\_url / api\_key / model trong đó, hiệu lực tương đương; khi cả hai cùng tồn tại, lấy độ ưu tiên của chính nó làm chuẩn (thường biến môi trường cao hơn).

## Kiểm tra

Sau khi khởi động, kích hoạt một lần suy luận đơn giản nhất (ví dụ cho nó trả lời một câu hỏi kiến thức phổ thông), xác nhận có nhận được phản hồi. Rồi kiểm tra trang mức sử dụng trong Console, xác nhận yêu cầu thực sự được ghi vào Key bạn tạo cho Hermes Agent.

## Lưu ý

* Biến môi trường phải nhìn thấy được trong phiên shell khởi động Agent, ghi vào shell khác sẽ không có hiệu lực.
* Nếu bạn triển khai bằng Docker, nhớ truyền biến vào qua `-e` hoặc `environment` của compose, đừng chỉ ghi trên máy chủ.
* Base URL chỉ điền đến `/v1`.
* Một số framework Agent ưu tiên đọc `OPENAI_API_BASE`, nếu các biến ở trên không có hiệu lực, bổ sung thêm một biến cùng tên nhưng khác cách viết rồi thử lại.
* Khuyến nghị tạo Key riêng cho Agent, để tiện thống kê mức sử dụng theo dự án.

---

# Hindsight

Nguồn: https://docs.aicentos.com/vi/clients/hindsight

Language: vi

> Cấu hình mô hình aicentos cho dịch vụ bộ nhớ Hindsight —— bốn biến môi trường là xong, tương thích OpenAI

Hindsight là hệ thống bộ nhớ agent mã nguồn mở, cung cấp dịch vụ tự lưu trữ, giao diện HTTP / MCP, SDK và CLI. Bản thân nó không phải client trò chuyện, nhưng **việc tinh lọc bộ nhớ cần dùng một LLM**, và LLM đó có thể trỏ về aicentos.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Hindsight trong Console (khuyến nghị đặt tên `hindsight`).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Máy chủ Hindsight cần PostgreSQL 14 trở lên. `pg0` đi kèm chỉ phù hợp cho phát triển, môi trường sản xuất hãy kết nối instance của riêng bạn.

```bash
pip install hindsight-api
```

## Cấu hình cần điền

| Biến môi trường              | Giá trị                                      |
| ---------------------------- | -------------------------------------------- |
| `HINDSIGHT_API_LLM_PROVIDER` | `openai`                                     |
| `HINDSIGHT_API_LLM_BASE_URL` | `https://aicentos.com/v1`                    |
| `HINDSIGHT_API_LLM_API_KEY`  | Key tạo trong Console                        |
| `HINDSIGHT_API_LLM_MODEL`    | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

Ghi vào môi trường khởi động là được, không cần sửa mã:

```bash
export HINDSIGHT_API_LLM_PROVIDER="openai"
export HINDSIGHT_API_LLM_BASE_URL="https://aicentos.com/v1"
export HINDSIGHT_API_LLM_API_KEY="sk-API-Key-của-bạn"
export HINDSIGHT_API_LLM_MODEL="tên-mô-hình-của-bạn"

hindsight-api
```

Khi triển khai bằng Docker, đặt các biến này vào `environment` của compose. Lưu ý image chính thức không chứa `llama.cpp`, đừng mong chạy mô hình cục bộ trong container.

## Kiểm tra

```bash
curl -fsSL https://hindsight.vectorize.io/get-cli | bash
hindsight health
```

Sau khi dịch vụ khởi động, ghi một bản ghi bộ nhớ rồi truy xuất lại, nếu đi thông được nghĩa là gọi LLM bình thường. Cũng có thể xem trực tiếp mức sử dụng trong Console: mỗi lần Hindsight tinh lọc bộ nhớ đều phát sinh một yêu cầu.

## Lưu ý

* `BASE_URL` phải kết thúc bằng `/v1`, và phía trên phải phục vụ được `/chat/completions`; ghi thành `https://aicentos.com` sẽ 404.
* Khi chưa cấu hình LLM Key, dịch vụ sẽ từ chối khởi động, đây là kiểm tra bắt buộc của nó, không phải Key điền sai.
* Tinh lọc bộ nhớ là xử lý hàng loạt chạy nền, mức sử dụng tăng theo số bản ghi bộ nhớ, khuyến nghị cấp riêng một Key cho Hindsight để dễ quan sát.
* `HINDSIGHT_API_LLM_PROVIDER` điền `openai` nghĩa là dùng giao thức tương thích OpenAI, không có nghĩa là chỉ dùng được mô hình OpenAI.

## Liên kết liên quan

* [Cấu hình mô hình Hindsight](https://hindsight.vectorize.io/developer/models)
* [Kho hindsight](https://github.com/vectorize-io/hindsight)

---

# Jcode

Nguồn: https://docs.aicentos.com/vi/clients/jcode

Language: vi

> Dùng aicentos trong Jcode —— chỉ định endpoint OpenAI tương thích qua file cấu hình

Jcode hỗ trợ chỉ định dịch vụ API OpenAI tương thích qua file cấu hình. Trỏ Base URL về aicentos, điền API Key, là có thể dùng các mô hình aicentos tích hợp trong Jcode.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Jcode tại trang "API Key" trong Console (khuyến nghị đặt tên `jcode` để dễ theo dõi mức sử dụng).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)
* Trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| Provider | OpenAI Compatible                            |
| Base URL | `https://aicentos.com/v1`                    |
| API Key  | Key tạo trong Console                        |
| Model    | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

* Mở file cấu hình của Jcode (thường nằm trong thư mục cấu hình người dùng, dạng `~/.jcode/config.json`).
* Thêm một mục provider OpenAI tương thích.
* `baseURL` / `baseUrl` điền: `https://aicentos.com/v1`
* `apiKey` điền Key tạo trong Console.
* `model` điền tên mô hình trong "Model Square" của Console (tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)).
* Sau khi lưu, khởi động lại Jcode để cấu hình có hiệu lực.

Cấu trúc tham khảo:

```json
{
  "provider": "openai",
  "baseUrl": "https://aicentos.com/v1",
  "apiKey": "sk-key-của-bạn",
  "model": "gpt-4o"
}
```

Nếu phiên bản của bạn đặt cấu hình ở `~/.config/jcode/config.json`, sửa file cùng tên dưới đường dẫn đó là được.

## Kiểm tra

Sau khi khởi động lại, tạo một phiên hội thoại mới, gửi một câu prompt đơn giản, trả về bình thường tức là kết nối thành công.

## Lưu ý

* Cách đặt tên mục cấu hình (`baseUrl` / `base_url`) có thể khác nhau giữa các phiên bản, lấy tên trường trong mẫu cấu hình cục bộ của bạn làm chuẩn.
* Base URL chỉ điền đến `/v1`, đừng bổ sung thành đường dẫn API đầy đủ.
* Nếu phiên bản Jcode không cung cấp mục nhập Base URL tùy chỉnh, thì phiên bản đó không thể kết nối endpoint bên thứ ba, hãy đổi sang client khác hỗ trợ Base URL tùy chỉnh.
* Đừng commit Key vào kho mã nguồn, khi cần có thể tham chiếu qua biến môi trường.

---

# Junie

Nguồn: https://docs.aicentos.com/vi/clients/junie

Language: vi

> Kết nối aicentos trong Junie CLI qua model profile tùy chỉnh

Junie là coding agent của JetBrains, có hai hình thái: plugin IDE và Junie CLI. **Chỉ Junie CLI hỗ trợ trỏ về endpoint tùy chỉnh**: nó kết nối tới dịch vụ OpenAI tương thích bất kỳ qua JSON profile trong `$JUNIE_HOME/models/`. Plugin IDE hiện không thể trỏ về endpoint tùy chỉnh.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Junie tại trang "API Key" trong Console (khuyến nghị đặt tên `junie-cli`).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Cấu hình cần điền

| Trường                         | Giá trị                                                |
| ------------------------------ | ------------------------------------------------------ |
| `baseUrl`                      | `https://aicentos.com/v1/chat/completions`             |
| `apiType`                      | `OpenAICompletion`                                     |
| `apiKey`                       | Key tạo trong Console (hỗ trợ tham chiếu `${ENV_VAR}`) |
| `id`                           | tên mô hình trong "Model Square" của Console           |
| `displayName` / `providerName` | tự đặt, ví dụ `aicentos`                               |

Lưu ý: profile của Junie ngược với đa số client, `baseUrl` cần điền **endpoint đầy đủ**, phải kết thúc bằng `/chat/completions`, Junie không tự nối đường dẫn.

## Các bước thiết lập

* Tạo file profile (tên file bỏ `.json` chính là định danh profile):
  * Cấp người dùng: `~/.junie/models/aicentos.json` (`$JUNIE_HOME` mặc định là `~/.junie`)
  * Cấp dự án: `<gốc dự án>/.junie/models/aicentos.json` (cần dự án đã được tin cậy)
* Ghi nội dung sau:

```json
{
  "id": "gpt-5",
  "baseUrl": "https://aicentos.com/v1/chat/completions",
  "apiType": "OpenAICompletion",
  "apiKey": "${AICENTOS_API_KEY}",
  "displayName": "aicentos GPT",
  "providerName": "aicentos",
  "fasterModel": { "id": "gpt-5-mini" }
}
```

* Xuất biến môi trường:

```bash
export AICENTOS_API_KEY="sk-Key-aicentos-của-bạn"
```

* Khi khởi động chỉ định profile, hoặc trong giao diện tương tác dùng `/model` để chọn:

```bash
junie --model custom:aicentos
```

## Kiểm tra

Sau khi khởi động, trước tiên test nhẹ bằng một câu prompt đơn giản, xác nhận có thể trả về kết quả bình thường rồi mới chính thức dùng quy trình agentic.

## Lưu ý

* **Plugin JetBrains IDE không hỗ trợ endpoint tùy chỉnh**, bộ profile này chỉ có hiệu lực trong Junie CLI.
* `baseUrl` phải là endpoint đầy đủ (kèm `/v1/chat/completions`), điều này khác với nhiều client chỉ cần điền Base URL.
* `${VAR}` trong `apiKey` và `extraHeaders` được phân giải khi nạp profile; biến môi trường chưa thiết lập sẽ khiến việc nạp profile thất bại.
* Profile cấp dự án chịu giới hạn tin cậy dự án, dự án chưa tin cậy sẽ báo `Unknown custom model profile`.
* Mô hình nhỏ khó đảm nhiệm các tác vụ gọi công cụ nhiều bước và ngữ cảnh dài của Junie, khuyến nghị chọn mô hình có năng lực mạnh hơn.
* Xem thêm giải thích tại trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

---

# Kilo CLI

Nguồn: https://docs.aicentos.com/vi/clients/kilo-cli

Language: vi

> Kết nối aicentos trong công cụ dòng lệnh Kilo qua file cấu hình

Kilo CLI khai báo Provider và mô hình qua một file cấu hình JSON / JSONC, hỗ trợ dùng `@ai-sdk/openai-compatible` trỏ về endpoint OpenAI tương thích bất kỳ, nên có thể kết nối thẳng aicentos.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho công cụ dòng lệnh tại trang "API Key" trong Console (khuyến nghị đặt tên `kilo-cli`).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Đồng thời xác nhận đã cài toàn cục Kilo CLI:

```bash
npm install -g @kilocode/cli
```

## Cấu hình cần điền

| Trường                                 | Giá trị                                               |
| -------------------------------------- | ----------------------------------------------------- |
| Gói provider (`npm`)                   | `@ai-sdk/openai-compatible`                           |
| `options.baseURL`                      | `https://aicentos.com/v1`                             |
| `options.apiKey`                       | Key tạo trong Console (có thể tham chiếu `{env:VAR}`) |
| Tham chiếu mô hình (`model` lớp ngoài) | dạng `provider/model`, ví dụ `aicentos/gpt-5`         |
| `limit.context` / `limit.output`       | điền theo mô hình đã chọn                             |

## Các bước thiết lập

* Tạo mới hoặc sửa file cấu hình toàn cục:
  * `~/.config/kilo/kilo.json` (hoặc `kilo.jsonc`); khi đã thiết lập `XDG_CONFIG_HOME` thì lấy thư mục đó làm chuẩn.
  * `./kilo.jsonc` cấp dự án sẽ ghi đè các mục cùng tên trong cấu hình toàn cục.
* Ghi nội dung sau:

```json
{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "aicentos/gpt-5",
  "provider": {
    "aicentos": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "aicentos",
      "options": {
        "baseURL": "https://aicentos.com/v1",
        "apiKey": "{env:AICENTOS_API_KEY}"
      },
      "models": {
        "gpt-5": {
          "name": "GPT-5",
          "limit": { "context": 128000, "output": 16384 }
        }
      }
    }
  }
}
```

* Xuất biến môi trường:

```bash
export AICENTOS_API_KEY="sk-Key-aicentos-của-bạn"
```

* Chạy `kilo` trong thư mục dự án, hoặc trong giao diện tương tác dùng `/model` để chuyển mô hình.

## Kiểm tra

Sau khi khởi động, trước tiên test nhẹ bằng một câu prompt đơn giản, xác nhận có thể trả về kết quả bình thường rồi mới chính thức sử dụng.

## Lưu ý

* `options.baseURL` chỉ điền đến `https://aicentos.com/v1`, đừng bổ sung thành `/v1/chat/completions` đầy đủ.
* Cú pháp thay thế biến môi trường `{env:VAR}` **chỉ có hiệu lực trong file cấu hình toàn cục**; `kilo.jsonc` cấp dự án vì lý do an toàn sẽ không phân giải `{env:...}`.
* Mô hình tùy chỉnh phải khai báo rõ `limit.context` và `limit.output`, nếu không độ dài ngữ cảnh sẽ được xử lý là 0, tính năng tự nén sẽ mất tác dụng.
* Nếu gateway không cung cấp giao diện danh sách `/v1/models`, tự động dò tìm mô hình sẽ thất bại, khai báo thủ công theo cách viết ở trên là được.
* Xem thêm giải thích tại trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

---

# Kilo Code

Nguồn: https://docs.aicentos.com/vi/clients/kilo-code

Language: vi

> Thêm Custom Provider trong tiện ích Kilo Code với Base URL và API Key của aicentos

Kilo Code chính thức hỗ trợ provider OpenAI Compatible, có thể kết nối trực tiếp tới dịch vụ hiện tại.

## Cài đặt

Trang cài đặt chính thức: [https://marketplace.visualstudio.com/items?itemName=kilocode.kilo-code](https://marketplace.visualstudio.com/items?itemName=kilocode.kilo-code)

Nếu bạn dùng VS Code, cách cài trực tiếp nhất là:

```bash
code --install-extension kilocode.kilo-code
```

Nếu bạn dùng Windsurf, VSCodium hoặc môi trường tương thích Open VSX, có thể cài theo phiên bản chợ extension tương ứng trong tài liệu chính thức của Kilo.

## Mở cài đặt

Trong panel Kilo Code, nhấn nút cài đặt để vào phần cấu hình provider.

## Cấu hình cần điền

Đặt API Provider thành OpenAI Compatible, rồi điền:

* Base URL: [https://aicentos.com/v1](https://aicentos.com/v1)
* API Key: Key của bạn dạng codex\_... hoặc sk-...
* Model ID: gpt-5-codex-mini

Nếu danh sách mô hình không tự xuất hiện mô hình này, cũng có thể nhập trực tiếp bằng tay.

## Kiểm tra

Sau khi lưu, trực tiếp tạo một tác vụ mới, xác nhận Kilo Code có thể kết nối bình thường và trả về nội dung.

## Lưu ý

* Tài liệu chính thức của Kilo Code dùng cấu hình provider OpenAI Compatible
* Kilo Code còn hỗ trợ thêm điền URL endpoint đầy đủ, nhưng với dịch vụ hiện tại là không cần thiết
* Ở đây khuyến nghị dùng trực tiếp Base URL, đừng bổ sung thêm thành đường dẫn đầy đủ /chat/completions
* Tài liệu chính thức tham khảo: [https://kilo.ai/docs/ai-providers/openai-compatible](https://kilo.ai/docs/ai-providers/openai-compatible)

---

# Kilo

Nguồn: https://docs.aicentos.com/vi/clients/kilo

Language: vi

> Kết nối aicentos trong Kilo qua provider OpenAI tương thích tùy chỉnh

Kilo hỗ trợ provider tùy chỉnh, có thể trỏ yêu cầu hội thoại và Agent về endpoint OpenAI tương thích bất kỳ. Chỉ cần thêm một Custom Provider trong cài đặt, điền Base URL và Key của aicentos là được.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Kilo tại trang "API Key" trong Console (khuyến nghị đặt tên `kilo`).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Cấu hình cần điền

| Trường            | Giá trị                                      |
| ----------------- | -------------------------------------------- |
| Provider ID / tên | tự đặt, ví dụ `aicentos`                     |
| Loại API          | OpenAI Compatible (Chat Completions)         |
| Base URL          | `https://aicentos.com/v1`                    |
| API Key           | Key tạo trong Console                        |
| Model ID          | tên mô hình trong "Model Square" của Console |
| Context Window    | điền theo mô hình đã chọn                    |
| Max Output Tokens | điền theo mô hình đã chọn                    |

## Các bước thiết lập

* Mở bảng cài đặt của Kilo (biểu tượng bánh răng).
* Vào **Providers**, kéo xuống cuối danh sách, chọn **Custom provider** (Provider tùy chỉnh).
* Provider ID và Display name điền thoải mái, ví dụ `aicentos`.
* Loại API chọn **OpenAI Compatible (Chat Completions)**.
* Base URL điền `https://aicentos.com/v1`.
* Điền API Key tạo trong Console.
* Thêm Model ID thủ công, điền tên mô hình trong Console.
* Sau khi lưu, trong bộ chọn mô hình chọn mô hình dưới provider này.

## Kiểm tra

Sau khi lưu cài đặt, tạo một tác vụ mới, trước tiên test nhẹ bằng một câu prompt đơn giản, xác nhận có thể trả về nội dung bình thường rồi mới chính thức dùng chế độ Agent.

## Lưu ý

* Nếu gateway không cung cấp giao diện danh sách `/v1/models`, tự động dò tìm mô hình sẽ thất bại, điền Model ID thủ công là được.
* Base URL chỉ điền đến `https://aicentos.com/v1`, đừng bổ sung thành `/v1/chat/completions` đầy đủ.
* Với mô hình tùy chỉnh, khuyến nghị thiết lập rõ Context Window và Max Output Tokens; nếu thiếu, độ dài ngữ cảnh sẽ được xử lý là 0, khiến tính năng tự nén mất tác dụng, hội thoại tăng lên vô hạn.
* Tài liệu chính thức: [https://kilo.ai/docs/ai-providers/openai-compatible](https://kilo.ai/docs/ai-providers/openai-compatible)
* Xem thêm giải thích tại trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

---

# Kimchi

Nguồn: https://docs.aicentos.com/vi/clients/kimchi

Language: vi

> Dùng aicentos trong Kimchi —— đổi địa chỉ suy luận bằng llmEndpoint, kèm giải thích giới hạn năng lực

Kimchi là agent lập trình trong terminal, đồng thời cung cấp extension VS Code và bản desktop Studio. Trong cấu hình của nó có trường `llmEndpoint`, mặc định trỏ về `https://llm.kimchi.dev`, đổi nó là có thể gửi yêu cầu suy luận đi nơi khác.

Cần nói trước: **tài liệu chính thức chỉ mô tả `llmEndpoint` là địa chỉ suy luận, không cam kết nó có thể trỏ tới bất kỳ gateway tương thích OpenAI của bên thứ ba nào**. Cách làm dưới đây dùng được trong cộng đồng, nhưng thuộc dạng "cấu hình theo ngữ nghĩa của trường", không phải đường BYOK được hỗ trợ chính thức, có thể mất tác dụng sau khi nâng cấp.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Kimchi trong Console (khuyến nghị đặt tên `kimchi`), sau đó cài CLI:

```bash
brew install getkimchi/tap/kimchi
```

Hoặc dùng script cài đặt:

```bash
curl -fsSL https://github.com/getkimchi/kimchi/releases/latest/download/install.sh | bash
```

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| `llmEndpoint` | `https://aicentos.com/v1`                    |
| `apiKey`      | Key tạo trong Console                        |
| Mô hình       | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

File cấu hình ở `~/.config/kimchi/config.json`, cũng có thể đặt `.kimchi/config.json` ở cấp dự án để ghi đè:

```json
{
  "apiKey": "sk-API-Key-của-bạn",
  "llmEndpoint": "https://aicentos.com/v1"
}
```

Mô hình tùy chỉnh được đăng ký trong `models.json`, định dạng giống các provider tự dựng như vLLM, LM Studio. Đặc tả trường chính thức chưa công bố đầy đủ, khuyến nghị chạy thông với mô hình mặc định trước, rồi mới cân nhắc thêm mục tùy chỉnh.

Sửa xong khởi động lại `kimchi`.

## Kiểm tra

Sau khi khởi động, gửi một câu prompt trong phiên. Nếu báo 401, trước tiên xác nhận Key không có khoảng trắng thừa; nếu báo 404, kiểm tra `llmEndpoint` có chỉ ghi đến `/v1` không.

Rồi quay lại Console xem mức sử dụng —— **đây là bước then chốt**: nếu mức sử dụng không tăng, nghĩa là yêu cầu hoàn toàn không đi qua `llmEndpoint` mà rơi về endpoint mặc định, lúc đó đường này không khả thi với phiên bản hiện tại.

## Lưu ý

* Kimchi cần đăng nhập tài khoản của chính nó, `apiKey` và trạng thái đăng nhập tài khoản là hai việc khác nhau, đừng chỉ làm một nửa.
* Mô hình bên ngoài mặc định được xử lý theo mức `standard`, `vision: false`, mô hình đa phương thức ở đây sẽ không mang theo hình ảnh.
* Mô hình mặc định do harness của chính nó tự chọn, có thể bạn không chỉ định trực tiếp được một tên mô hình cụ thể trên aicentos.
* Chính thức chưa đưa đường này vào tài liệu, thuộc dạng "dùng được nhưng không bảo đảm", môi trường sản xuất hãy chuẩn bị phương án dự phòng.

## Liên kết liên quan

* [Tài liệu Kimchi CLI](https://docs.kimchi.dev/docs/kimchi-cli)
* [Kho kimchi](https://github.com/getkimchi/kimchi)

---

# Kimi

Nguồn: https://docs.aicentos.com/vi/clients/kimi

Language: vi

> Dùng aicentos trong Kimi Code CLI —— đăng ký provider OpenAI tương thích qua config.toml

Kimi Code CLI cho phép đăng ký dịch vụ OpenAI tương thích bất kỳ thành provider. Trỏ `base_url` về aicentos, điền API Key, là có thể gọi trực tiếp các mô hình aicentos tích hợp ngay trong giao diện terminal.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Kimi Code tại trang "API Key" trong Console (khuyến nghị đặt tên `kimi-cli` để dễ theo dõi mức sử dụng).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)
* Trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

File cấu hình mặc định nằm ở `~/.kimi/config.toml`, khi chạy Kimi Code lần đầu sẽ tự động được tạo.

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| Loại provider | `openai_legacy` (giao thức Chat Completions) |
| base\_url     | `https://aicentos.com/v1`                    |
| api\_key      | Key tạo trong Console                        |
| model         | tên mô hình trong "Model Square" của Console |

Nếu phía aicentos đi giao thức Responses, đổi loại thành `openai_responses` là được.

## Các bước thiết lập

Mở `~/.kimi/config.toml`, bổ sung một provider tùy chỉnh và một bí danh mô hình:

```toml
default_model = "aicentos-gpt-4o"

[providers.aicentos]
type = "openai_legacy"
base_url = "https://aicentos.com/v1"
api_key = "sk-key-của-bạn"

[models.aicentos-gpt-4o]
provider = "aicentos"
model = "gpt-4o"
max_context_size = 128000
```

* Tên provider (`aicentos`) và bí danh mô hình (`aicentos-gpt-4o`) đều có thể tự đặt, trong `default_model` ghi là bí danh, không phải model ID phía máy chủ.
* Nếu bí danh có dấu `.` (ví dụ `gpt-4.1`), trong TOML bắt buộc phải thêm dấu ngoặc kép: `[models."gpt-4.1"]`, nếu không dấu `.` sẽ bị coi là ký tự phân tách bảng.
* Nếu không muốn viết TOML bằng tay, trong TUI nhập `/provider` để mở trình quản lý nhà cung cấp, nhấn Enter ở dòng `[ Add New Platform ]`, thêm theo wizard.

Cũng có thể chỉ dùng biến môi trường (có hiệu lực với loại `openai_legacy` / `openai_responses`):

```bash
export OPENAI_BASE_URL="https://aicentos.com/v1"
export OPENAI_API_KEY="sk-key-của-bạn"
```

## Kiểm tra

Khởi động `kimi`, trong TUI gửi một câu prompt đơn giản, trả về bình thường tức là kết nối thành công. Dùng `/model` xác nhận hiện đang chọn đúng bí danh vừa cấu hình.

## Lưu ý

* Thông tin xác thực của provider được phân giải theo thứ tự: trường `api_key` > bảng con `[providers.<name>.env]` > báo lỗi khi khởi động; ngoài `openai_legacy` / `openai_responses`, thông tin xác thực trong file cấu hình sẽ không được tự động bổ sung từ biến môi trường shell.
* `type = "kimi"` là dành cho endpoint chính thức của Moonshot, khi kết nối aicentos hãy dùng `openai_legacy` hoặc `openai_responses`.
* Đừng điền `max_context_size` thấp hơn cửa sổ thực tế của mô hình, điền nhỏ sẽ sớm kích hoạt nén ngữ cảnh.
* Base URL chỉ điền đến `/v1`, đừng bổ sung thành đường dẫn đầy đủ `/v1/chat/completions`.
* Tên mô hình lấy "Model Square" trong Console làm chuẩn (tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)).

---

# Kiro

Nguồn: https://docs.aicentos.com/vi/clients/kiro

Language: vi

> Kiro hiện chưa hỗ trợ Base URL tùy chỉnh —— giải thích nguyên nhân giới hạn và các phương án thay thế khả thi

**Kiro hiện chưa hỗ trợ Base URL tùy chỉnh, không thể kết nối trực tiếp tới aicentos.**

Kiro là IDE agentic do AWS ra mắt (dựa trên Code OSS), mô hình của nó thống nhất đi qua dịch vụ đi kèm của riêng nó, tầng dưới là Amazon Bedrock. Chính thức chưa mở mục cấu hình "endpoint mô hình tùy chỉnh" hay "tự mang API Key (BYOK)", các yêu cầu tính năng tương ứng của cộng đồng cũng vẫn chưa được thực hiện.

## Chuẩn bị

Không cần tạo API Key aicentos cho Kiro —— phiên bản hiện tại không có chỗ nào để điền Key tùy chỉnh.

Thông tin tham khảo:

* Console: [https://aicentos.com](https://aicentos.com)
* Trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

Nếu bạn đã kết nối trên client khác, có thể trước tiên xác nhận client đó có hỗ trợ endpoint tùy chỉnh không.

## Cấu hình cần điền

| Trường   | Giá trị                                                    |
| -------- | ---------------------------------------------------------- |
| Base URL | không có mục cấu hình này                                  |
| API Key  | không có mục cấu hình này                                  |
| Mô hình  | chỉ có thể chọn từ danh sách mô hình tích hợp sẵn của Kiro |

## Các bước thiết lập

Không thể cấu hình. Trong cài đặt của Kiro chỉ có chuyển đổi mô hình (lệnh `/model` hoặc bộ chọn mô hình) và trường `model` của Agent tùy chỉnh, mà `model` chỉ khớp với model ID khả dụng do máy chủ Kiro trả về, không thể trỏ về endpoint bên ngoài.

## Phương án thay thế

Kiro không hỗ trợ endpoint tùy chỉnh, vì vậy có mấy đường sau để chọn:

* **Dùng client hỗ trợ sẵn Base URL tùy chỉnh**: ví dụ Cursor, Windsurf, Cline, Roo Code, Zed Agent..., đều có thể điền thẳng `https://aicentos.com/v1`. Xem các tài liệu khác dưới mục "Kết nối client".
* **Dùng tiếp mô hình tích hợp sẵn trong Kiro**: mô hình tích hợp sẵn của Kiro do AWS cung cấp, không liên quan tới aicentos, không thể gộp chung tính phí.
* **Chờ chính thức hỗ trợ BYOM / BYOK**: có thể theo dõi tiến độ trong các yêu cầu tính năng của repo chính thức Kiro, hiện vẫn chưa triển khai.
* **Tình huống gateway nội bộ doanh nghiệp**: kể cả đã triển khai LLM proxy nội bộ, Kiro cũng không thể cấu hình trỏ về nó, cũng cần chờ chính thức hỗ trợ.

Không khuyến nghị dùng các thủ đoạn vòng ngoại không chính thức như sửa hosts, cài chứng chỉ tự ký hay vá IDE —— các cách làm này sẽ phá vỡ cơ chế cập nhật của Kiro, và cũng tồn tại rủi ro an toàn cũng như tuân thủ.

## Kiểm tra

Không có endpoint tùy chỉnh để kiểm tra. Nếu muốn xác minh kết nối của aicentos, có thể dùng bất kỳ client nào hỗ trợ Base URL tùy chỉnh, hoặc gọi trực tiếp:

```bash
curl https://aicentos.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{"model":"gpt-5","messages":[{"role":"user","content":"hi"}],"stream":false}'
```

## Lưu ý

* Nhấn mạnh lần nữa: **phiên bản hiện tại của Kiro không hỗ trợ Base URL tùy chỉnh, không thể kết nối aicentos**.
* Tài liệu này sẽ được cập nhật theo thay đổi năng lực chính thức của Kiro.
* Tài liệu chính thức: [https://kiro.dev/docs](https://kiro.dev/docs)

---

# LM Studio

Nguồn: https://docs.aicentos.com/vi/clients/lm-studio

Language: vi

> LM Studio là máy chủ suy luận cục bộ chứ không phải client —— giải thích vai trò đúng của nó và cách làm thay thế

LM Studio thường bị coi là "một client trò chuyện nữa", thực ra hướng là ngược lại: nó là **trình chạy mô hình cục bộ**, mở ra một giao diện tương thích OpenAI (mặc định `http://localhost:1234/v1`) để người khác kết nối tới. Nó không có chỗ "điền một Base URL từ xa", nên không thể dùng làm client kết nối aicentos.

## Vì sao không thể kết nối trực tiếp

* Định vị chính thức là `Serve local models on OpenAI-like endpoints`, vai trò máy chủ, không phải bên tiêu thụ.
* Bản desktop và CLI `lms` đều không có mục cấu hình endpoint cho provider bên thứ ba.
* Năng lực cloud của nó (LM Studio Secure Cloud, LM Link) là kênh tính toán do chính thức lưu trữ, không nhận endpoint bên thứ ba tùy chỉnh.

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Mô hình  | tên mô hình trong "Model Square" của Console |

Bảng trên là tham số chung phía aicentos, dùng cho phương án thay thế dưới đây.

## Phương án thay thế

### Phương án 1: Dùng ngược lại —— để client kết nối LM Studio

Nếu bạn muốn chạy mô hình cục bộ, giữ LM Studio làm máy chủ, và điền Base URL của [Cherry Studio](https://docs.aicentos.com/vi/clients/cherry-studio), [Chatbox](https://docs.aicentos.com/vi/clients/chatbox), [Cline](https://docs.aicentos.com/vi/clients/cline) thành `http://localhost:1234/v1`. Chuỗi này không liên quan tới aicentos, nhưng đó là cách dùng đúng của LM Studio.

### Phương án 2: Muốn mô hình của aicentos thì đổi frontend

[Cherry Studio](https://docs.aicentos.com/vi/clients/cherry-studio), [Chatbox](https://docs.aicentos.com/vi/clients/chatbox), [LobeChat](https://docs.aicentos.com/vi/clients/lobechat) đều là client trò chuyện trên desktop, hỗ trợ nhiều provider cùng tồn tại: một mục điền aicentos, một mục điền LM Studio cục bộ, chuyển đổi ngay trong cùng giao diện.

### Phương án 3: Dùng lẫn cục bộ và cloud

Dùng các client như Cherry Studio gắn đồng thời hai provider, tác vụ đơn giản đi cục bộ, tác vụ phức tạp đi aicentos, chuyển đổi theo nhu cầu là được.

## Kiểm tra

Khi dùng LM Studio làm máy chủ, trước tiên `lms server start`, rồi dùng `curl http://localhost:1234/v1/models` xác nhận giao diện còn sống, sau đó gửi một câu prompt trong client.

## Lưu ý

* Đừng tìm ô nhập Base URL trong LM Studio, nó chỉ hiển thị địa chỉ mà nó đang lắng nghe.
* Ngữ cảnh và tốc độ của mô hình cục bộ bị giới hạn bởi VRAM của máy, tác vụ ngữ cảnh dài khuyến nghị đi aicentos.
* Đừng nhầm hai hướng: **máy chủ điền cổng, client điền endpoint**.

## Liên kết liên quan

* [Giao diện tương thích OpenAI của LM Studio](https://lmstudio.ai/docs/api/openai-api)
* [lms CLI](https://github.com/lmstudio-ai/lms)

---

# LobeChat

Nguồn: https://docs.aicentos.com/vi/clients/lobechat

Language: vi

> Dùng aicentos trong LobeChat —— kết nối qua cài đặt OpenAI tương thích tùy chỉnh

LobeChat là một nền tảng trò chuyện AI mã nguồn mở, hỗ trợ giao diện OpenAI tương thích, có thể kết nối trực tiếp tới dịch vụ hiện tại qua bảng cài đặt.

## Mở cài đặt

Nhấn vào biểu tượng **Cài đặt (Settings)** ở góc dưới bên trái, vào trang **Mô hình ngôn ngữ (Language Model)**.

## Chọn provider OpenAI

Trong danh sách provider, nhấn **OpenAI** để mở rộng bảng cấu hình.

## Cấu hình cần điền

Điền các thông tin sau trong bảng cấu hình:

* **API Key (apiKey)**: Key của bạn dạng `codex_...` hoặc `sk-...`
* **Địa chỉ proxy API (baseURL)**: `https://aicentos.com/v1`

## Chọn mô hình và xác minh

Chọn trong dropdown mô hình, hoặc nhập tay `gpt-5-codex-mini`. Tạo một cuộc hội thoại, xác nhận có phản hồi bình thường là được.

## Lưu ý

* Địa chỉ proxy API cần điền đường dẫn gốc của dịch vụ có kèm `/v1`, tức là `https://aicentos.com/v1`
* LobeChat hỗ trợ cấu hình đồng thời nhiều provider và chuyển đổi theo phiên hội thoại
* Bản tự lưu trữ có thể hoàn tất cấu hình qua biến môi trường `OPENAI_API_KEY` và `OPENAI_PROXY_URL`, chi tiết xem tài liệu biến môi trường chính thức

## Liên kết liên quan

* Tài liệu chính thức: [https://lobehub.com/docs/usage/providers/openai](https://lobehub.com/docs/usage/providers/openai)

---

# MiMo Code

Nguồn: https://docs.aicentos.com/vi/clients/mimo-code

Language: vi

> Dùng aicentos trong MiMo Code —— kết nối endpoint OpenAI tương thích qua lớp tương thích

MiMo Code hỗ trợ chỉ định `base_url` OpenAI tương thích trong cấu hình. Trỏ nó về aicentos và điền API Key, là có thể cho MiMo Code đi qua các mô hình của aicentos.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho MiMo Code tại trang "API Key" trong Console (khuyến nghị đặt tên `mimo-code` để dễ theo dõi mức sử dụng).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)
* Trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

MiMo Code là công cụ CLI, cách cài phổ biến là cài toàn cục bằng npm; nếu gói phát hành bạn nhận được là tarball, giải nén xong đưa file thực thi vào `PATH` là được.

```bash
npm install -g mimo-code
mimo --version
```

## Cấu hình cần điền

| Trường    | Giá trị                                      |
| --------- | -------------------------------------------- |
| API Key   | Key tạo trong Console                        |
| base\_url | `https://aicentos.com/v1`                    |
| model     | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

Khuyến nghị dùng biến môi trường, độ tương thích tốt nhất:

```bash
export MIMO_BASE_URL="https://aicentos.com/v1"
export MIMO_API_KEY="sk-key-của-bạn"
export AICENTOS_API_KEY="$MIMO_API_KEY"
export MIMO_MODEL="gpt-4o"
```

Muốn hiệu lực vĩnh viễn, ghi vào `~/.zshrc` hoặc `~/.bashrc` rồi thực hiện `source ~/.zshrc`.

Nếu thích file cấu hình, sửa `~/.mimo/config.json`:

```json
{
  "baseUrl": "https://aicentos.com/v1",
  "apiKey": "sk-key-của-bạn",
  "model": "gpt-4o"
}
```

Lưu ý các phiên bản khác nhau có thể khác nhau về cách đặt tên mục cấu hình (`base_url` / `baseUrl`) và tiền tố biến môi trường (`MIMO_` / `MIMOCODE_`). Nếu tên biến ở trên không có hiệu lực, dùng `mimo --help` hoặc tài liệu chính thức xác nhận tên thực tế phiên bản hiện tại đọc vào, đừng thử đi thử lại.

## Kiểm tra

Sau khi cấu hình, chạy trực tiếp `mimo`, gửi một câu prompt đơn giản. Nếu báo lỗi xác thực, ưu tiên kiểm tra tên biến môi trường có được phiên bản hiện tại nhận diện không, `base_url` có chỉ viết đến `/v1` không, Key có khoảng trắng thừa không.

## Lưu ý

* Một số phiên bản khi khởi động sẽ kiểm tra `base_url` với endpoint chính thức tích hợp sẵn, nếu phát hiện cấu hình bị bỏ qua, chuyển sang cách biến môi trường thường có thể qua được.
* Base URL chỉ điền đến `/v1`.
* Khuyến nghị trước tiên dùng `curl https://aicentos.com/v1/models -H "Authorization: Bearer $AICENTOS_API_KEY"` xác nhận mô hình nhìn thấy được, rồi mới điền tên mô hình.
* Khi biến môi trường và file cấu hình cùng tồn tại, độ ưu tiên giữa các phiên bản không nhất quán, khuyến nghị chỉ giữ một cách cấu hình.

---

# MiniMax Code

Nguồn: https://docs.aicentos.com/vi/clients/minimax-code

Language: vi

> Dùng aicentos trong MiniMax Code (mcode) —— dùng provider add để thêm một provider tương thích OpenAI

MiniMax Code là CLI lập trình chính thức của MiniMax (lệnh `mcode`), có sẵn TUI, thực thi headless, ACP và TypeScript SDK. Nó hỗ trợ BYOK: có thể dùng `mcode provider add` để gắn bất kỳ endpoint tương thích OpenAI nào.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho MiniMax Code trong Console (khuyến nghị đặt tên `minimax-code`), sau đó cài đặt:

```bash
curl -fsSL https://filecdn.minimax.chat/public/install.sh | bash
```

Cũng có thể cài qua npm:

```bash
npm install -g @minimax-ai/code@latest
mcode --version
```

## Cấu hình cần điền

| Trường          | Giá trị                                      |
| --------------- | -------------------------------------------- |
| Tên provider    | tự đặt, ví dụ `aicentos`                     |
| `--base-url`    | `https://aicentos.com/v1`                    |
| `--api-format`  | `openai-completions`                         |
| `--model`       | tên mô hình trong "Model Square" của Console |
| `--api-key-env` | `MCODE_PROVIDER_API_KEY`                     |

## Các bước thiết lập

Một lệnh đăng ký và chuyển sang:

```bash
export MCODE_PROVIDER_API_KEY="sk-API-Key-của-bạn"

mcode provider add \
  --name aicentos \
  --base-url https://aicentos.com/v1 \
  --api-format openai-completions \
  --model tên-mô-hình-của-bạn \
  --api-key-env MCODE_PROVIDER_API_KEY \
  --use
```

`--use` nghĩa là đăng ký xong chuyển ngay sang provider này. Nó sẽ ghi cấu hình vào đoạn `custom_provider` trong `config.yaml` của profile hiện tại (thư mục dữ liệu mặc định `~/.minimax`), cách viết tương đương:

```yaml
custom_provider:
  aicentos:
    options:
      apiKey: sk-API-Key-của-bạn
      baseURL: https://aicentos.com/v1
    models:
      tên-mô-hình-của-bạn: {}
```

Lưu ý khóa ở đây là `baseURL` (URL viết hoa), không phải `base-url`.

## Kiểm tra

```bash
mcode exec "Giới thiệu bản thân trong một câu"
```

Headless trả về được nghĩa là cấu hình có hiệu lực. Sau đó vào TUI chạy một vòng tác vụ thực tế, cuối cùng quay lại Console đối chiếu mức sử dụng.

## Lưu ý

* Mô hình tùy chỉnh phải chỉ rõ giới hạn ngữ cảnh và đầu ra (`--context-limit`, `--output-limit`), nếu không nó cắt theo giá trị mặc định, file dài dễ bị cắt cụt.
* Script cài một lệnh không hỗ trợ Alpine / musl, môi trường này đổi sang cài bằng npm.
* Khi muốn dùng giao thức tương thích Anthropic để làm trung chuyển, yêu cầu vẫn kèm `x-api-key`, nếu phía trên chỉ nhận `Authorization` thì cần tự thêm một lớp chuyển đổi.
* Provider được lưu **theo profile**, sau khi đổi profile cần xác nhận lại mục nào đang có hiệu lực.

## Liên kết liên quan

* [Bắt đầu nhanh với MiniMax Code](https://agent.minimax.io/docs/cli/quick-start)
* [Kho minimax-code](https://github.com/MiniMax-AI/minimax-code)

---

# Mux

Nguồn: https://docs.aicentos.com/vi/clients/mux

Language: vi

> Dùng aicentos trong Mux —— thêm provider OpenAI tương thích tùy chỉnh

Mux hỗ trợ thêm provider OpenAI tương thích tùy chỉnh. Trỏ Base URL về aicentos, là có thể dùng các mô hình aicentos tích hợp trong phiên hội thoại của Mux.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Mux tại trang "API Key" trong Console (khuyến nghị đặt tên `mux` để dễ theo dõi mức sử dụng).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)
* Trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| Loại provider | OpenAI Compatible                            |
| Base URL      | `https://aicentos.com/v1`                    |
| API Key       | Key tạo trong Console                        |
| Model         | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

* Mở cài đặt Mux, vào khu vực Providers / Models.
* Chọn thêm provider tùy chỉnh, loại chọn **OpenAI Compatible**.
* Điền API Key.
* Base URL điền: `https://aicentos.com/v1`
* Model điền tên mô hình trong "Model Square" của Console (tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)).
* Lưu, và đặt nó thành provider mà phiên hội thoại hiện tại sử dụng.

## Kiểm tra

Tạo một phiên hội thoại mới, gửi một câu prompt đơn giản. Trả về bình thường tức là kết nối thành công. Nếu danh sách mô hình không tự xuất hiện mô hình bạn điền, nhập Model ID bằng tay rồi thử lại một lần.

## Lưu ý

* Base URL chỉ điền đến `/v1`, đừng bổ sung thành đường dẫn đầy đủ `/v1/chat/completions`.
* Tên mục cài đặt có thể hơi khác nhau giữa các phiên bản, nhưng cấu hình OpenAI tương thích luôn xoay quanh ba trường Base URL, API Key, Model.
* Nếu Base URL điền sai, Key có khoảng trắng thừa hoặc không đủ số dư, thường biểu hiện là lỗi 401 / 403 / 402, đối chiếu từng mục là được.
* Nếu phiên bản Mux của bạn chỉ cung cấp vài lựa chọn công ty cố định, không thể tự định nghĩa Base URL, tức là phiên bản đó không hỗ trợ endpoint bên thứ ba, lúc này hãy đổi sang client khác hỗ trợ Base URL tùy chỉnh.

---

# NativeTavern

Nguồn: https://docs.aicentos.com/vi/clients/nativetavern

Language: vi

> Kết nối NativeTavern với API tương thích OpenAI của aicentos bằng Base URL và API Key

# NativeTavern

NativeTavern là phiên bản ứng dụng di động gốc của SillyTavern, hỗ trợ nền tảng iOS và Android, có thể kết nối API tùy chỉnh qua giao diện OpenAI tương thích.

## Cài ứng dụng

Tải và cài NativeTavern từ cửa hàng ứng dụng của nền tảng tương ứng:

* iOS: App Store
* Android: Google Play

## Cấu hình kết nối API

1. Mở ứng dụng NativeTavern
2. Vào **Cài đặt** hoặc **Settings**
3. Chọn **API Configuration**
4. Chọn loại API là **OpenAI** hoặc **OpenAI Compatible**

## Cấu hình cần điền

Điền trong trang cấu hình:

* **API URL**: `https://aicentos.com/v1`
* **API Key**: điền API Key của bạn (như `codex_...` hoặc `sk-...`)
* **Model**: chọn hoặc nhập model ID (như `gpt-6-astra`)

## Kiểm tra kết nối

1. Sau khi lưu cài đặt, quay lại giao diện chính
2. Tạo hoặc chọn một nhân vật
3. Gửi tin nhắn để kiểm tra kết nối có bình thường không

## Lưu ý

* Ứng dụng di động có thể cần kết nối mạng ổn định
* API URL chỉ cần điền đến `/v1`, không cần đường dẫn đầy đủ
* Hỗ trợ phần lớn tính năng của SillyTavern

## Liên kết liên quan

NativeTavern là một phần của hệ sinh thái SillyTavern, để biết thêm thông tin có thể truy cập cộng đồng SillyTavern.

---

# NextChat

Nguồn: https://docs.aicentos.com/vi/clients/nextchat

Language: vi

> Dùng aicentos trong NextChat —— kết nối qua cài đặt OpenAI tương thích tùy chỉnh

NextChat là một ChatGPT Web client mã nguồn mở được sử dụng rộng rãi, hỗ trợ giao diện OpenAI tương thích tùy chỉnh.

## Cấu hình giao diện UI - Mở cài đặt

Nhấn vào biểu tượng **Cài đặt (Settings)** ở góc dưới bên trái

## Cấu hình giao diện UI - Bật giao diện tùy chỉnh

Trong bảng cài đặt tìm công tắc **Giao diện tùy chỉnh (Custom Endpoint)**, bật lên sẽ hiện ra ô nhập

## Cấu hình giao diện UI - Điền thông tin kết nối

Điền các thông tin sau:

| Trường         | Nội dung điền                              |
| -------------- | ------------------------------------------ |
| OpenAI API Key | Key của bạn dạng `codex_...` hoặc `sk-...` |
| API proxy URL  | `https://aicentos.com/v1`                  |

## Cấu hình giao diện UI - Xác minh

Sau khi lưu, tạo hội thoại để xác minh có trả về bình thường không

## Cấu hình triển khai tự lưu trữ

Với bản tự lưu trữ, cấu hình qua biến môi trường:

```bash
OPENAI_API_KEY=codex_your_api_key
BASE_URL=https://aicentos.com/v1
```

Sau khi cấu hình, khởi động lại dịch vụ là có hiệu lực.

## Mô hình tùy chỉnh

Trong dropdown **Mô hình (Model)** của bảng cài đặt, có thể nhập tay `gpt-5-codex-mini` hoặc tên mô hình khả dụng khác.

Bản tự lưu trữ còn có thể dùng biến môi trường `CUSTOM_MODELS` để đặt trước danh sách mô hình, ví dụ:

```bash
CUSTOM_MODELS=gpt-5-codex-mini
```

## Lưu ý

* API proxy URL điền đường dẫn gốc của dịch vụ có kèm `/v1`, tức là `https://aicentos.com/v1`
* Mô hình khả dụng lấy theo danh sách trả về của `GET /v1/models`

## Liên kết liên quan

* GitHub: [https://github.com/ChatGPTNextWeb/NextChat](https://github.com/ChatGPTNextWeb/NextChat)

---

# Oh My Pi

Nguồn: https://docs.aicentos.com/vi/clients/oh-my-pi

Language: vi

> Dùng aicentos trong Oh My Pi (omp) —— thêm một provider openai-completions vào models.yml

Oh My Pi là bản fork của Pi, viết lại phần lõi bằng Rust, lệnh là `omp`. Nó định nghĩa provider qua `~/.omp/agent/models.yml`, chỉ cần ghi rõ các trường `baseUrl` / `api` / `apiKey` là có thể trỏ về aicentos.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Oh My Pi trong Console (khuyến nghị đặt tên `oh-my-pi`).

Khi chạy cần bun 1.4.4 trở lên:

```bash
curl -fsSL https://omp.sh/install | sh
```

Cũng có thể cài qua Homebrew hoặc npm:

```bash
brew install can1357/tap/omp
# hoặc
bun install -g @oh-my-pi/pi-coding-agent
```

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| Tên provider  | tự đặt, ví dụ `aicentos`                     |
| `baseUrl`     | `https://aicentos.com/v1`                    |
| `api`         | `openai-completions`                         |
| `apiKey`      | Key tạo trong Console                        |
| `models[].id` | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

Chỉnh sửa `~/.omp/agent/models.yml`:

```yaml
providers:
  aicentos:
    baseUrl: https://aicentos.com/v1
    api: openai-completions
    apiKey: sk-API-Key-của-bạn
    models:
      - id: tên-mô-hình-của-bạn
        contextWindow: 128000
```

Đặt nó làm mặc định trong `~/.omp/agent/config.yml`:

```yaml
modelRoles:
  default: aicentos/tên-mô-hình-của-bạn
```

Khi không muốn ghi Key vào file, đổi `apiKey` thành tham chiếu biến môi trường, và `export AICENTOS_API_KEY="sk-API-Key-của-bạn"` trước khi khởi động.

## Kiểm tra

```bash
omp models aicentos
```

Liệt kê được mô hình vừa cấu hình nghĩa là provider đã nhận. Rồi vào TUI gửi một câu xác nhận trả về được, cuối cùng quay lại Console đối chiếu mức sử dụng.

## Lưu ý

* `api` phải là `openai-completions` (hoặc tên giao thức khác mà nó biết), ghi `openai` sẽ bị coi là giao thức không xác định.
* Nó mặc định tắt nhiều công cụ, khi kết nối thành công nhưng "không làm được gì" thì xem công tắc công cụ trước, không phải vấn đề endpoint.
* Mở repo là tải cấu hình cấp dự án và hook, trước khi kết nối hãy xác nhận repo đáng tin.
* Môi trường Alpine cần cài thêm `libstdc++`, `libgcc`.

## Liên kết liên quan

* [Tài liệu provider của Oh My Pi](https://omp.sh/docs/providers)
* [Kho oh-my-pi](https://github.com/can1357/oh-my-pi)

---

# OpenClaw

Nguồn: https://docs.aicentos.com/vi/clients/openclaw

Language: vi

> Dùng aicentos trong OpenClaw —— kết nối qua Provider tùy chỉnh

OpenClaw là công cụ dòng lệnh trợ lý lập trình AI, hỗ trợ kết nối đến các dịch vụ API tương thích OpenAI qua Provider tùy chỉnh. Trang chính thức khuyến nghị dùng trình hướng dẫn `openclaw onboard` để hoàn tất cấu hình, cũng có thể tự viết file cấu hình thủ công.

## Chuẩn bị

Đảm bảo hệ thống đáp ứng các yêu cầu sau:

* Node.js phiên bản 22+
* Hệ điều hành macOS / Linux / Windows
* Nếu build từ mã nguồn, cần cài thêm pnpm

### Cài Node.js

**macOS (dùng Homebrew):**

```bash
brew install node
```

**Hệ điều hành khác:**

Truy cập trang chủ Node.js để tải bản LTS: [https://nodejs.org/en/download](https://nodejs.org/en/download)

### Kiểm tra cài đặt

```bash
node -v
npm -v
```

**Lưu ý:** Người dùng Windows nên chạy OpenClaw trong môi trường WSL2.

## Cài đặt OpenClaw

Dùng script cài đặt chính thức (khuyến nghị):

### macOS / Linux

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```

### Windows PowerShell

```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```

Script cài đặt sẽ tự động phát hiện và cài bổ sung các phụ thuộc còn thiếu. Nếu bạn đã tự quản lý môi trường Node, cũng có thể cài bằng `npm` hoặc `pnpm` (xem tài liệu chính thức).

## Chạy trình hướng dẫn cấu hình

Chạy lệnh hướng dẫn:

```bash
openclaw onboard
```

Trong trình hướng dẫn, lần lượt điền các thông tin sau:

* **Loại Provider**: chọn `Custom Provider`
* **Compatibility**: chọn `OpenAI-compatible`
* **Base URL**: `https://aicentos.com/v1`
* **API Key**: điền API Key của bạn
* **Model ID**: tham khảo tên mô hình trong "Model Square" của Console
* **Endpoint ID**: khuyến nghị điền `aicentos`

**Lưu ý:** API Key điền trực tiếp dạng văn bản thuần là được, không cần đổi thêm sang biến môi trường `OPENAI_API_KEY`.

## Đặt mô hình mặc định

Sau khi hoàn tất trình hướng dẫn, đặt mô hình mặc định thành:

```text
aicentos/gpt-4o
```

Như vậy khi dùng về sau sẽ tự động dùng mô hình đã cấu hình.

## Cấu hình thủ công (tùy chọn)

Nếu không dùng trình hướng dẫn, có thể trực tiếp viết file cấu hình provider của OpenClaw:

```json
{
  "models": {
    "providers": {
      "aicentos": {
        "baseUrl": "https://aicentos.com/v1",
        "apiKey": "your_api_key_here",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-4o", "name": "gpt-4o" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "aicentos/gpt-4o" }
    }
  }
}
```

Trong cấu hình có thể ghi trực tiếp API Key dạng văn bản thuần, hoặc dùng tham chiếu biến môi trường (nếu bạn thích cách SecretRef hơn).

## Kiểm tra cấu hình

Kiểm tra trạng thái mô hình để xác nhận kết nối thành công:

```bash
openclaw models list
openclaw models status
```

Nếu thấy `aicentos/gpt-4o` và trạng thái hiển thị bình thường, nghĩa là cấu hình kết nối thành công.

## Lưu ý

* OpenClaw chính thức hỗ trợ tính năng Provider tùy chỉnh, có thể chọn chế độ OpenAI-compatible hoặc Anthropic-compatible
* Với dịch vụ hiện tại, khuyến nghị ưu tiên dùng chế độ OpenAI-compatible
* Điền trực tiếp API Key là cách làm mặc định; tham chiếu biến môi trường chỉ là phương án tùy chọn
* Nếu muốn dùng công cụ tự ghi cấu hình, có thể cân nhắc công cụ `cc-switch`
* Tài liệu chính thức còn cung cấp các cách cài đặt và cấu hình khác, có thể chọn theo nhu cầu thực tế

## Liên kết liên quan

* Tài liệu chính thức: [https://docs.openclaw.ai/install/index](https://docs.openclaw.ai/install/index)

---

# OpenCode

Nguồn: https://docs.aicentos.com/vi/clients/opencode

Language: vi

> Dùng aicentos trong OpenCode —— kết nối provider tùy chỉnh qua file cấu hình

OpenCode hỗ trợ provider tùy chỉnh, có thể kết nối đến dịch vụ Codex Proxy thông qua file cấu hình.

## Chuẩn bị

Trang chủ OpenCode cung cấp script cài đặt chính thức, đồng thời có các cách cài npm, bun, brew\...

* Nếu bạn dùng trực tiếp script cài đặt chính thức, thường không cần tự cấu hình npm trước
* Nếu bạn định cài qua npm, hãy cài Node.js và npm trước
* Nếu bạn định cài qua bun, thì cần cài bun trước

### Cài Node.js (cách npm)

Trang tải chính thức của Node.js là: [https://nodejs.org/en/download](https://nodejs.org/en/download)

* macOS / Windows: tải và cài bản LTS
* Linux: cài theo cách của bản phân phối được hướng dẫn trên trang đó

Nếu trên macOS bạn đã cài Homebrew, cũng có thể chạy thẳng:

```bash
brew install node
```

Lệnh này cài đồng thời cả Node.js và npm.

Nên trước tiên xác nhận lệnh tương ứng khả dụng theo cách cài bạn chọn. Ví dụ với cách npm có thể kiểm tra trước:

```bash
node -v
npm -v
```

**Lưu ý:** Nếu bạn dùng môi trường dòng lệnh trên Windows, hiện trang chính thức khuyến nghị ưu tiên dùng trong WSL.

## Cài đặt

Khuyến nghị dùng trực tiếp lệnh cài đặt do trang chủ OpenCode cung cấp:

```bash
curl -fsSL https://opencode.ai/install | bash
```

Trang chủ OpenCode đồng thời cung cấp các cách cài npm, bun, brew\...

## Thiết lập API Key

Dùng cách kết nối hoặc xác thực riêng của OpenCode:

```bash
opencode auth login
```

Hoặc chạy /connect trong giao diện tương tác, lưu dịch vụ này như một provider tùy chỉnh.

Nếu bạn quen dùng biến môi trường hơn, chỉ cần để opencode.json đọc tên biến chung chính thức, ví dụ:

```bash
export OPENAI_API_KEY="your_api_key_here"
```

## Cấu hình opencode.json

Tạo opencode.json trong thư mục gốc của dự án hoặc thư mục cấu hình toàn cục:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aicentos": {
      "npm": "@ai-sdk/openai",
      "name": "aicentos",
      "options": {
        "baseURL": "https://aicentos.com/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "gpt-4o": {
          "name": "gpt-4o"
        }
      }
    }
  },
  "model": "aicentos/gpt-4o"
}
```

## Kiểm tra

Sau khi khởi động OpenCode, thực hiện:

```
/models
```

Thấy các mô hình dưới aicentos là được.

## Lưu ý

* Thứ tự khuyến nghị: trước là cấu hình file thủ công (opencode.json), tiếp là biến môi trường, cuối cùng mới là công cụ cc-switch ([https://github.com/farion1231/cc-switch/releases](https://github.com/farion1231/cc-switch/releases))
* Nếu bạn đi theo /v1/responses, tài liệu chính thức OpenCode khuyến nghị dùng @ai-sdk/openai
* Chỉ khi kết nối của bạn chỉ hỗ trợ /v1/chat/completions mới đổi sang @ai-sdk/openai-compatible
* Không cần định nghĩa thêm biến riêng của dự án như CODEX\_PROXY\_API\_KEY

## Liên kết liên quan

* Trang web chính thức: [https://opencode.ai/](https://opencode.ai/)

---

# OpenCodeReview

Nguồn: https://docs.aicentos.com/vi/clients/opencodereview

Language: vi

> Dùng aicentos trong OpenCodeReview (OCR) —— kết nối review code qua provider tùy chỉnh

OpenCodeReview (tên lệnh `ocr`) là CLI review code AI mã nguồn mở của Alibaba: đọc Git diff rồi gọi mô hình lớn đưa ra ý kiến review. Nó tích hợp sẵn provider OpenAI tương thích, cũng hỗ trợ gateway OpenAI tương thích tùy chỉnh, có thể chuyển yêu cầu sang aicentos.

## Chuẩn bị

Tạo một Key chuyên dụng trong Console của aicentos (khuyến nghị đặt tên `ocr-ci` để dễ theo dõi mức sử dụng). OCR chỉ hỗ trợ hai giao thức OpenAI / Anthropic, ở đây đi đường Chat Completions của OpenAI. Review code phụ thuộc vào khả năng **function calling** của mô hình, hãy chọn mô hình hỗ trợ gọi công cụ.

## Cấu hình cần điền

| Trường   | Giá trị                                                                   |
| -------- | ------------------------------------------------------------------------- |
| provider | `openai` (tích hợp sẵn, ghi đè URL của nó) hoặc provider tùy chỉnh        |
| protocol | `openai` (Chat Completions)                                               |
| URL      | `https://aicentos.com/v1`                                                 |
| API Key  | Key tạo trong Console                                                     |
| Mô hình  | tên mô hình trong "Model Square" của Console, cần hỗ trợ function calling |

## Các bước thiết lập

* Cài CLI (cần Node.js, hoặc dùng Homebrew trên macOS):

  ```bash
  npm install -g open-code-review
  ```

* Dùng lệnh phi tương tác để ghi cấu hình, cuối cùng nằm ở `~/.opencodereview/config.json`:

  ```bash
  ocr config set provider                   openai
  ocr config set model                      claude-sonnet-5
  ocr config set providers.openai.url       https://aicentos.com/v1
  ocr config set providers.openai.api_key   your_api_key_here
  ```

* Nếu thích hướng dẫn đồ hoạ, chạy trực tiếp `ocr config provider` và `ocr config model`, trong TUI chọn provider, điền Key, chọn mô hình, đi xong sẽ tự chạy một lần kiểm tra kết nối.

## Kiểm tra

Trước tiên xác minh riêng endpoint:

```bash
ocr llm test
```

Thông qua rồi, thực hiện một lần review thực tế trong bất kỳ Git repo nào:

```bash
ocr review
```

## Lưu ý

* URL chỉ điền đến `/v1`, đừng bổ sung thành `/chat/completions` đầy đủ.
* Bộ phân giải cấu hình cần đủ **URL, Key, mô hình** ba thứ; chỉ `export` biến môi trường là chưa đủ, phần thiếu vẫn phải ghi vào config.json, nếu không sẽ trả về 401.
* Cũng có thể dùng biến môi trường ghi đè tạm thời, độ ưu tiên cao nhất: `OCR_LLM_URL` / `OCR_LLM_TOKEN` / `OCR_LLM_MODEL`.
* Trường của provider tích hợp sẵn là `providers.<name>.url`, provider tùy chỉnh ở `custom_providers.<name>.url`, đừng viết lẫn hai map này.
* Khi không đủ số dư tài khoản sẽ biểu hiện là 401 / 403, trước tiên vào [trang Ví](https://aicentos.com/wallet) xác nhận số dư.
* Repo chính thức: `https://github.com/alibaba/open-code-review`

---

# Orca

Nguồn: https://docs.aicentos.com/vi/clients/orca

Language: vi

> Dùng aicentos trong Orca —— thêm endpoint tùy chỉnh OpenAI tương thích

Orca hỗ trợ cấu hình dịch vụ OpenAI tương thích tùy chỉnh. Trỏ Base URL về aicentos, điền API Key, là có thể dùng các mô hình aicentos tích hợp trong Orca.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Orca tại trang "API Key" trong Console (khuyến nghị đặt tên `orca` để dễ theo dõi mức sử dụng).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)
* Trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| Loại provider | OpenAI Compatible                            |
| Base URL      | `https://aicentos.com/v1`                    |
| API Key       | Key tạo trong Console                        |
| Model         | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

* Mở trang cài đặt của Orca, vào khu vực cấu hình mô hình / Provider.
* Thêm một provider mới, loại chọn tương thích OpenAI (OpenAI Compatible / Custom OpenAI).
* Base URL điền: `https://aicentos.com/v1`
* API Key điền Key tạo trong Console.
* Model điền tên mô hình trong "Model Square" của Console (tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)).
* Lưu và đặt thành mô hình mặc định.

## Kiểm tra

Tạo một hội thoại mới gửi một câu prompt đơn giản, xác nhận có thể trả về bình thường. Nếu dropdown mô hình trống trơn, đổi sang nhập Model ID bằng tay.

## Lưu ý

* Base URL chỉ điền đến `/v1`, đừng bổ sung thành đường dẫn đầy đủ `/v1/chat/completions`.
* Sau khi lưu nếu cài đặt chưa có hiệu lực ngay, khởi động lại Orca một lần.
* Nếu phiên bản Orca của bạn chỉ hỗ trợ provider chính thức tích hợp sẵn, không có mục nhập Base URL tùy chỉnh, thì phiên bản đó không thể kết nối endpoint bên thứ ba, hãy đổi sang client khác hỗ trợ Base URL tùy chỉnh.
* Các nguyên nhân kết nối thất bại thường gặp: Base URL ghi sai, Key có khoảng trắng đầu cuối, tên mô hình không tồn tại, không đủ số dư tài khoản.

---

# Paseo

Nguồn: https://docs.aicentos.com/vi/clients/paseo

Language: vi

> Dùng aicentos trong Paseo —— nó không kết nối mô hình trực tiếp, phải cấu hình trong CLI nền tảng hoặc provider env

Paseo là tầng điều phối: có bản desktop, mobile, Web và CLI `paseo`, nhưng **bản thân nó không kèm agent**, chỉ chịu trách nhiệm chạy các CLI lập trình bạn đã cài và đăng nhập sẵn (Claude Code, Codex, OpenCode, Pi...). Vì vậy "kết nối aicentos trong Paseo" thực chất là để CLI được host đi qua aicentos.

## Chuẩn bị

Trước tiên cài Paseo, và chuẩn bị ít nhất một CLI nền tảng:

```bash
npm install -g @getpaseo/cli
paseo
```

Bản desktop và bản mobile tải từ trang chủ. Lưu ý image Docker không chứa bất kỳ agent CLI nào, triển khai bằng container phải tự cài.

## Cấu hình cần điền

Provider của Paseo được định nghĩa trong `agents.providers.<id>` của `~/.paseo/config.json`, các trường là `extends`, `label`, `env`, `models`. **Nó hỗ trợ tiêm biến môi trường cho CLI nền tảng**, các ví dụ chính thức đều là giao thức tương thích Anthropic:

| Trường                   | Giá trị                                      |
| ------------------------ | -------------------------------------------- |
| `extends`                | CLI nền tảng, ví dụ `claude`                 |
| `env.ANTHROPIC_BASE_URL` | `https://aicentos.com`                       |
| `env.ANTHROPIC_API_KEY`  | Key tạo trong Console                        |
| `models`                 | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

Chỉnh sửa `~/.paseo/config.json`:

```json
{
  "agents": {
    "providers": {
      "aicentos-claude": {
        "extends": "claude",
        "label": "aicentos",
        "env": {
          "ANTHROPIC_BASE_URL": "https://aicentos.com",
          "ANTHROPIC_API_KEY": "sk-API-Key-của-bạn"
        }
      }
    }
  }
}
```

Sửa xong tải lại:

```bash
paseo reload
```

Sau đó trong Paseo chọn provider của phiên thành `aicentos`.

Nếu bạn host CLI dùng giao thức OpenAI (ví dụ Codex), đổi `env` sang biến riêng của CLI đó (`OPENAI_BASE_URL`, `OPENAI_API_KEY`), Base URL dùng `https://aicentos.com/v1`.

## Kiểm tra

```bash
paseo run --provider aicentos-claude "Giới thiệu bản thân trong một câu"
```

Trả về được là thông. Cũng có thể tạo phiên mới trực tiếp trên bản desktop, xem nhãn mô hình có hiển thị provider bạn đã cấu hình không.

## Lưu ý

* **Bản thân Paseo không có cấu hình mô hình**. Không tìm thấy ô nhập Base URL là bình thường, hãy tìm trong CLI nền tảng hoặc `env`.
* Tài liệu chính thức chỉ đưa ví dụ trường cho tương thích Anthropic, cách viết endpoint tương thích OpenAI không được quy định rõ, hãy viết theo tên biến của CLI nền tảng, lấy thực đo làm chuẩn.
* `env` sẽ ghi đè trạng thái đăng nhập đã lưu của CLI nền tảng, cấu hình sai sẽ khiến cả những phiên vốn dùng được cũng thất bại, khuyến nghị tạo provider mới thay vì sửa mục mặc định.
* Phải hoàn tất xác thực CLI nền tảng trước, Paseo không đăng nhập thay bạn.

## Liên kết liên quan

* [Tài liệu provider tùy chỉnh của Paseo](https://paseo.sh/docs/custom-providers)
* [Kho paseo](https://github.com/getpaseo/paseo)

---

# Pi

Nguồn: https://docs.aicentos.com/vi/clients/pi

Language: vi

> Dùng aicentos trong Pi —— cấu hình endpoint OpenAI tương thích tùy chỉnh

Pi hỗ trợ chỉ định địa chỉ API OpenAI tương thích tùy chỉnh. Trỏ Base URL về aicentos, điền API Key, là có thể dùng các mô hình aicentos tích hợp trong Pi.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Pi tại trang "API Key" trong Console (khuyến nghị đặt tên `pi` để dễ theo dõi mức sử dụng).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)
* Trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| Provider | OpenAI Compatible                            |
| Base URL | `https://aicentos.com/v1`                    |
| API Key  | Key tạo trong Console                        |
| Model    | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

* Mở cài đặt của Pi, tìm khu vực cấu hình API / mô hình.
* Chọn provider OpenAI tương thích tùy chỉnh.
* Base URL điền: `https://aicentos.com/v1`
* API Key điền Key tạo trong Console.
* Model điền tên mô hình trong "Model Square" của Console (tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)).
* Lưu, và trong phiên hội thoại chọn mô hình này.

## Kiểm tra

Tạo một vòng hội thoại đơn giản, xác nhận có thể trả về bình thường. Dùng `/model` hoặc trang cài đặt xác nhận mô hình hiện tại thực sự đến từ aicentos, chứ không phải provider mặc định tích hợp sẵn.

## Lưu ý

* Base URL chỉ điền đến `/v1`, đừng viết thành đường dẫn API đầy đủ.
* Nếu Pi đồng thời giữ lại provider tích hợp sẵn, chú ý chuyển về mục bạn vừa tạo, nếu không yêu cầu sẽ không đi qua aicentos.
* Nếu phiên bản Pi của bạn không cung cấp Base URL tùy chỉnh, thì không thể kết nối endpoint bên thứ ba, hãy đổi sang client khác hỗ trợ Base URL tùy chỉnh.
* Khuyến nghị tạo Key riêng cho client này, để tiện phân biệt mức sử dụng theo Key trong Console.

---

# Prime Agent

Nguồn: https://docs.aicentos.com/vi/clients/prime-agent

Language: vi

> Dùng aicentos trong Prime Agent —— hiện chỉ đi được provider dùng API-key, trường endpoint chưa được công bố chính thức

Prime Agent là agent lập trình trong terminal mã nguồn mở của Prime Intellect (viết bằng Rust, giấy phép MIT), định vị là "RLM harness có thể tự cải thiện". Nó hỗ trợ dùng API Key kết nối mô hình bên ngoài, nhưng **trường Base URL tùy chỉnh chưa có tài liệu chính thức**, nên dưới đây chia thành hai phần "đã xác nhận dùng được" và "cần tự kiểm chứng".

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Prime Agent trong Console (khuyến nghị đặt tên `prime-agent`).

```bash
curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh
```

Windows:

```powershell
irm https://app.primeintellect.ai/prime-agent/install.ps1 | iex
```

## Cấu hình cần điền

| Trường        | Giá trị                                                     |
| ------------- | ----------------------------------------------------------- |
| Cách xác thực | lần khởi động đầu dùng `/login`, chọn provider dùng API-key |
| API Key       | Key tạo trong Console                                       |
| Base URL      | `https://aicentos.com/v1` (tên trường chờ xác minh)         |
| Mô hình       | tên mô hình trong "Model Square" của Console                |

## Các bước thiết lập

Lần khởi động đầu thực hiện `/login`, chọn dùng API Key thay vì provider theo gói đăng ký. Đây là đường được tài liệu chính thức ghi rõ.

File cấu hình được biết của nó là `models.json`, chính thức chỉ công bố cách viết ghi đè mô hình:

```json
{
  "providers": {
    "provider-của-bạn": {
      "modelOverrides": {
        "tên-mô-hình-của-bạn": { "contextWindow": 128000 }
      }
    }
  }
}
```

`modelOverrides` chỉ sửa tham số mô hình, **không phải định nghĩa endpoint**. Muốn đổi endpoint, cần tìm trường endpoint trong provider đã chọn ở `/login` —— README của kho chính thức không đưa ra tên trường, khuyến nghị xem file cấu hình sinh ra sau khi khởi động có những khóa nào, rồi điền theo, đừng đoán.

## Kiểm tra

```bash
prime-agent
```

Gửi một câu prompt trong phiên. Nếu trả về lỗi xác thực, nghĩa là provider chưa chọn đúng; nếu trả về được nhưng tên mô hình không đúng, nghĩa là endpoint và mô hình được cấu hình riêng, quay lại kiểm tra `models.json`.

## Lưu ý

* **Nó không phải sandbox an toàn**, nó thực thi Python và lệnh do mô hình sinh ra với quyền người dùng của bạn, đừng chạy tác vụ lạ trên máy có thông tin xác thực sản xuất.
* Mặc định có telemetry, `PRIME_AGENT_TELEMETRY=0` để tắt.
* Mạng doanh nghiệp cần CA tùy chỉnh thì dùng `NODE_EXTRA_CA_CERTS`.
* Trường endpoint chưa được công bố chính thức, thuộc trạng thái "phải tự mò". Nếu không mò được, đổi sang [Oh My Pi](https://docs.aicentos.com/vi/clients/oh-my-pi) hoặc [Gajae Code](https://docs.aicentos.com/vi/clients/gajae-code) có trường rõ ràng.

## Liên kết liên quan

* [Kho prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)

---

# Qwen

Nguồn: https://docs.aicentos.com/vi/clients/qwen

Language: vi

> Dùng aicentos trong Qwen Code —— cấu hình provider tương thích OpenAI qua settings.json

Qwen Code hỗ trợ đăng ký bất kỳ endpoint tương thích OpenAI nào qua `modelProviders` trong `settings.json`. Trỏ `baseUrl` về aicentos, là có thể dùng các mô hình aicentos tích hợp trong Qwen Code.

## Chuẩn bị

Trước tiên, tạo một Key riêng cho Qwen Code tại trang "API Key" trong Console (khuyến nghị đặt tên `qwen-code` để dễ theo dõi mức sử dụng).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)
* Trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

Qwen Code cần Node.js 20+, cài toàn cục bằng npm:

```bash
npm install -g @qwen-code/qwen-code
qwen --version
```

## Cấu hình cần điền

| Trường    | Giá trị                                      |
| --------- | -------------------------------------------- |
| Loại auth | `openai` (giao thức tương thích OpenAI)      |
| baseUrl   | `https://aicentos.com/v1`                    |
| envKey    | Tên biến môi trường chứa Key (có thể tự đặt) |
| Model id  | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

Sửa `~/.qwen/settings.json`:

```json
{
  "env": {
    "AICENTOS_API_KEY": "sk-Key-của-bạn"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "baseUrl": "https://aicentos.com/v1",
        "envKey": "AICENTOS_API_KEY"
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "gpt-4o"
  }
}
```

* `id` là model ID thực tế gửi đến máy chủ, phải khớp với tên mô hình trong Console.
* Trong `modelProviders` không ghi key dạng văn bản thuần, `envKey` chỉ là tham chiếu "lấy key từ biến môi trường nào".
* Độ ưu tiên của key: biến môi trường hệ thống > file `.env` (`~/.qwen/.env`) > khối `env` trong `settings.json`.
* Nếu phía aicentos đi giao thức Responses, thêm `"wireApi": "responses"` cho mô hình đó; không ghi thì mặc định đi Chat Completions.

Cũng có thể hoàn toàn không sửa file cấu hình, dùng trực tiếp biến môi trường:

```bash
export OPENAI_BASE_URL="https://aicentos.com/v1"
export OPENAI_API_KEY="sk-Key-của-bạn"
export OPENAI_MODEL="gpt-4o"
```

## Kiểm tra

Khởi động `qwen`, dùng `/about` xác nhận endpoint và mô hình hiện tại có đúng không, rồi gửi một prompt đơn giản. Khi cấu hình nhiều mục provider, có thể dùng `/model` để chuyển.

## Lưu ý

* Cấu hình toàn cục đặt ở `~/.qwen/settings.json`, cấu hình cấp dự án đặt ở `.qwen/settings.json` trong thư mục gốc dự án, cái sau có độ ưu tiên cao hơn.
* `security.auth.selectedType` bắt buộc là `openai`, nếu không sẽ không đi endpoint tùy chỉnh.
* Đừng commit key dạng văn bản thuần vào kho mã nguồn, ưu tiên dùng `~/.qwen/.env` hoặc biến môi trường hệ thống.
* `wireApi` chỉ là metadata định tuyến cục bộ, không được gửi đi cùng body yêu cầu; trước khi đổi thành `responses`, hãy xác nhận trước phía aicentos có hỗ trợ `/v1/responses`.
* Base URL chỉ điền đến `/v1`, đừng bổ sung thành đường dẫn API đầy đủ.

---

# Reasonix

Nguồn: https://docs.aicentos.com/vi/clients/reasonix

Language: vi

> Dùng aicentos trong Reasonix —— kết nối qua provider tùy chỉnh trong config.toml

Reasonix là một coding Agent cục bộ (CLI/TUI, bản desktop, UI trình duyệt, cùng bản ACP cho trình soạn thảo — bốn lối vào dùng chung một engine). Nó không tích hợp sẵn provider aicentos, nhưng có thể thêm một bản ghi `[[providers]]` OpenAI tương thích vào `~/.reasonix/config.toml`, để chuyển yêu cầu sang aicentos.

## Chuẩn bị

Tạo một Key chuyên dụng trong Console của aicentos (khuyến nghị đặt tên `reasonix-cli`). Key của provider Reasonix được lưu trong `.env` toàn cục của chính nó, không đọc biến môi trường shell.

## Cấu hình cần điền

| Trường        | Giá trị                                      |
| ------------- | -------------------------------------------- |
| name          | `aicentos` (ID provider cục bộ)              |
| kind          | `openai` (Chat Completions)                  |
| base\_url     | `https://aicentos.com/v1`                    |
| api\_key\_env | `AICENTOS_API_KEY`                           |
| models        | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

* Cài Reasonix (npm hoặc Homebrew trên macOS):

  ```bash
  npm i -g reasonix
  ```

* Ghi Key vào `.env` toàn cục của Reasonix:

  ```bash
  # macOS / Linux
  echo 'AICENTOS_API_KEY=your_api_key_here' >> ~/.reasonix/.env

  # Windows：%APPDATA%\reasonix\.env
  ```

* Sửa `~/.reasonix/config.toml`, hợp nhất đoạn dưới đây (đừng xóa các provider khác đã có):

  ```toml
  default_model = "aicentos"

  [[providers]]
  name          = "aicentos"
  kind          = "openai"
  base_url      = "https://aicentos.com/v1"
  models        = ["claude-sonnet-5", "deepseek-v4-pro", "qwen3-coder-plus"]
  default       = "claude-sonnet-5"
  api_key_env   = "AICENTOS_API_KEY"
  context_window = 200000
  ```

* Vào thư mục dự án khởi động:

  ```bash
  reasonix
  ```

  Cũng có thể dùng tác vụ một lần để xác minh: `reasonix run "giải thích trong một câu thư mục hiện tại là dự án gì"`. Bản desktop thì đi qua **Settings → Model → Access → Add model service → Custom provider**.

## Kiểm tra

Sau khi khởi động gửi một câu prompt đơn giản, xác nhận có thể trả về dạng stream bình thường. Trong phiên hội thoại có thể dùng `/model` để chuyển mô hình.

## Lưu ý

* `base_url` chỉ điền đến `/v1`, Reasonix sẽ tự nối `/chat/completions`.
* Key bắt buộc phải ghi trong `~/.reasonix/.env`; `export` ra shell hay `.env` của dự án đều không được nhận diện là key provider.
* `kind` chọn `openai`; loại gốc `anthropic` tương ứng endpoint Anthropic Messages, không phù hợp ở đây.
* `default_model` điền là `name` của provider (`aicentos`), không phải tên mô hình.
* Nếu biểu mẫu provider tùy chỉnh của bản desktop yêu cầu điền địa chỉ đầy đủ, điền `https://aicentos.com/v1/chat/completions`.
* Địa chỉ dự án: `https://github.com/esengine/DeepSeek-Reasonix`

---

# Roo Code

Nguồn: https://docs.aicentos.com/vi/clients/roo-code

Language: vi

> Cấu hình nhà cung cấp OpenAI Compatible trong Roo Code với Base URL và API Key của aicentos

Roo Code chính thức hỗ trợ provider OpenAI Compatible, có thể kết nối trực tiếp tới dịch vụ hiện tại.

## Cài đặt

Trang cài đặt chính thức: [https://roocode.com/extension](https://roocode.com/extension)

Nếu bạn dùng VS Code hoặc nhánh tương thích, cách cài trực tiếp nhất là:

```bash
code --install-extension RooVeterinaryInc.roo-cline
```

Bạn cũng có thể tìm kiếm `Roo Code` trực tiếp trong chợ extension để cài plugin chính thức.

## Mở cấu hình provider

Trong panel Roo Code, mở trang cài đặt để vào phần cấu hình provider mô hình.

## Cấu hình cần điền

Đặt `API Provider` thành `OpenAI Compatible`, rồi điền:

* Base URL: `https://aicentos.com/v1`
* API Key: Key của bạn dạng `codex_...` hoặc `sk-...`
* Model ID: `gpt-5-codex-mini`

Nếu dropdown mô hình không liệt kê mô hình này, có thể nhập tên mô hình bằng tay.

## Kiểm tra

Sau khi lưu, tạo một tác vụ mới, xác nhận Roo Code có thể kết nối bình thường và bắt đầu trả lời.

## Lưu ý

* Tài liệu chính thức của Roo Code yêu cầu dùng provider `OpenAI Compatible`
* Roo Code với provider OpenAI tương thích phụ thuộc vào việc mô hình hỗ trợ tool calling gốc
* Với dịch vụ hiện tại, Base URL điền thẳng `https://aicentos.com/v1` là được
* Tài liệu chính thức tham khảo: [https://docs.roocode.com/providers/openai-compatible](https://docs.roocode.com/providers/openai-compatible)

---

# Senpi (OmO Native)

Nguồn: https://docs.aicentos.com/vi/clients/senpi

Language: vi

> Dùng aicentos trong Senpi / OmO —— vị trí thư mục cấu hình và provider openai-compatible

Senpi là fork của `pi-mono`, tên gói npm là `@code-yeongyu/senpi`, file thực thi tên `senpi`. Nó đồng thời là runtime của oh-my-openagent (viết tắt OmO), nên "OmO Native" chỉ bộ chạy trên harness senpi.

## Chuẩn bị

```bash
curl -fsSL https://get.omo.dev/install.sh | bash
omo
```

Cũng có thể cài bằng bun:

```bash
bun add -g omo-ai
```

Dự án tự mô tả là experimental, nguyên văn chính thức là đừng đặt lên pipeline sản xuất.

## Cấu hình cần điền

Thư mục cấu hình là `~/.omo/agent/`, có thể ghi đè bằng `OMO_CODING_AGENT_DIR`; các biến `SENPI_*` cũ vẫn tương thích.

| Tệp             | Vai trò                                                      |
| --------------- | ------------------------------------------------------------ |
| `models.json`   | định nghĩa provider (endpoint, giao thức, danh sách mô hình) |
| `auth.json`     | khóa                                                         |
| `settings.json` | tùy chọn như mô hình mặc định                                |

Bản thân senpi có một bộ riêng: `~/.senpi/agent/settings.json`, và `.senpi/settings.json` ở cấp dự án.

| Trường             | Giá trị                                      |
| ------------------ | -------------------------------------------- |
| Giao thức provider | `@ai-sdk/openai-compatible`                  |
| Base URL           | `https://aicentos.com/v1`                    |
| API Key            | Key tạo trong Console                        |
| Mô hình            | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

Thêm một provider trong `~/.omo/agent/models.json`, chọn giao thức thuộc loại tương thích OpenAI (ánh xạ tài liệu đưa ra là `npm: @ai-sdk/openai-compatible`):

```json
{
  "providers": {
    "aicentos": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://aicentos.com/v1",
        "apiKey": "sk-API-Key-của-bạn"
      },
      "models": {
        "tên-mô-hình-của-bạn": {}
      }
    }
  }
}
```

Khóa cũng có thể để riêng trong `auth.json`, không ghi vào `models.json`. Sau đó ghi mô hình mặc định vào `settings.json`.

## Kiểm tra

Khởi động `omo` hoặc `senpi`, xác nhận trong bộ chọn mô hình có các mô hình dưới `aicentos`, gửi một câu xác nhận trả về được.

## Lưu ý

* Đừng lẫn hai thư mục cấu hình: phía OmO ở `~/.omo/agent/`, phía senpi ở `~/.senpi/agent/`, sửa sai chỗ sẽ không có hiệu lực.
* `.senpi/settings.json` ở cấp dự án sẽ ghi đè cài đặt toàn cục, khi xử lý sự cố hãy xem thư mục dự án trước.
* Tài liệu chính thức chỉ đưa ánh xạ di chuyển, không có đoạn cấu hình đầy đủ nguyên văn, cấu trúc trên được sắp xếp theo quy ước hệ Pi, tên trường vui lòng đối chiếu với phiên bản hiện tại của `omo.dev/docs`.
* Dự án experimental, cấu trúc cấu hình có thể thay đổi sau khi nâng cấp.

## Liên kết liên quan

* [Tài liệu OmO](https://omo.dev/docs)
* [Kho senpi](https://github.com/code-yeongyu/senpi)
* [Kho oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent)

---

# SillyTavern

Nguồn: https://docs.aicentos.com/vi/clients/sillytavern

Language: vi

> Thêm aicentos làm backend tương thích OpenAI trong SillyTavern: nhập Base URL và API Key để dùng toàn bộ mô hình

# SillyTavern

SillyTavern là một ứng dụng trò chuyện nhập vai phổ biến, hỗ trợ nhiều backend mô hình AI. Qua cấu hình API OpenAI tương thích, có thể kết nối tới dịch vụ hiện tại.

## Mở cài đặt kết nối API

1. Khởi động ứng dụng SillyTavern
2. Nhấn vào biểu tượng kết nối API phía trên
3. Chọn **Chat Completion (OpenAI Compatible)**

## Cấu hình thông tin kết nối

Điền trong bảng cài đặt API:

* **API Type**: chọn `OpenAI`
* **Chat Completion Source**: chọn `OpenAI` hoặc `OpenAI Compatible`
* **API URL**: `https://aicentos.com/v1`
* **API Key**: điền API Key của bạn (như `codex_...` hoặc `sk-...`)
* **Model**: chọn hoặc điền model ID (như `gpt-6-astra`)

## Kiểm tra kết nối

1. Nhấn nút **Connect**
2. Nếu kết nối thành công, trạng thái sẽ hiển thị màu xanh
3. Có thể bắt đầu trò chuyện với nhân vật

## Lưu ý

* API URL điền đến `/v1` là được, không cần đường dẫn đầy đủ `/v1/chat/completions`
* Hỗ trợ phản hồi dạng stream, khuyến nghị bật trong cài đặt nâng cao
* Có thể nhập model ID bằng tay trong dropdown mô hình

## Tài liệu chính thức

Truy cập [tài liệu chính thức của SillyTavern](https://docs.sillytavern.app/) để biết thêm các tùy chọn cấu hình.

---

# TavernAI

Nguồn: https://docs.aicentos.com/vi/clients/tavernai

Language: vi

> Trỏ TavernAI về API tương thích OpenAI của aicentos: nhập Base URL và API Key để bắt đầu trò chuyện

# TavernAI

TavernAI là một ứng dụng trò chuyện nhập vai, hỗ trợ kết nối tới dịch vụ API tùy chỉnh qua giao diện OpenAI tương thích.

## Mở cài đặt

1. Khởi động ứng dụng TavernAI
2. Nhấn vào biểu tượng cài đặt ở góc trên bên phải
3. Tìm phần **API Settings** hoặc **AI Configuration**

## Cấu hình kết nối API

Điền trong cài đặt API:

* **API Type**: chọn `OpenAI`
* **API Endpoint**: `https://aicentos.com/v1`
* **API Key**: điền API Key của bạn (như `codex_...` hoặc `sk-...`)
* **Model**: điền model ID (như `gpt-6-astra`)

## Lưu và kiểm tra

1. Nhấn **Save** để lưu cài đặt
2. Quay lại giao diện trò chuyện
3. Gửi một tin nhắn để kiểm tra kết nối

## Lưu ý

* Giao diện TavernAI có thể hơi khác nhau giữa các phiên bản
* Đảm bảo API Endpoint được điền kết thúc bằng `/v1`
* Nếu kết nối thất bại, kiểm tra API Key có đúng không

## Liên kết liên quan

TavernAI là dự án cộng đồng, có thể tìm tài liệu và hỗ trợ liên quan trên GitHub.

---

# Trae

Nguồn: https://docs.aicentos.com/vi/clients/trae

Language: vi

> Thêm dịch vụ tương thích OpenAI trong phần cài đặt Trae, với Base URL aicentos và API Key

Tài liệu này hướng dẫn cách dùng cấu hình OpenAI tương thích tùy chỉnh trong Trae để kết nối dịch vụ hiện tại. Mục cài đặt của các phiên bản Trae có thể thay đổi, vì vậy ở đây không bám vào một đường dẫn menu duy nhất, mà nêu rõ những mục cấu hình mấu chốt bạn cần tìm.

## Mở cài đặt AI / Model

Trong cài đặt Trae, tìm các khu vực cấu hình tương ứng với các từ khóa sau:

* AI
* Models
* Provider
* OpenAI
* Custom

Nếu phiên bản hiện tại hỗ trợ kết nối OpenAI tương thích tùy chỉnh, thường sẽ có các mục nhập như nhà cung cấp mô hình, API Key và Base URL.

## Cấu hình cần điền

Điền theo dịch vụ hiện tại:

* Base URL: [https://aicentos.com/v1](https://aicentos.com/v1)
* API Key: Key của bạn dạng codex\_... hoặc sk-...
* Model ID: lấy kết quả trả về của GET /v1/models làm chuẩn; nếu chỉ muốn thử kết nối trước, có thể thử gpt-6-astra

## Kiểm tra

Sau khi lưu, tạo một hội thoại mới, tác vụ chỉnh sửa hoặc tác vụ Agent, xác nhận Trae có thể gửi yêu cầu bình thường và trả về nội dung.

## Lưu ý

* Ở đây điền là Base URL tương thích OpenAI, đừng bổ sung thêm thành đường dẫn đầy đủ /chat/completions hay /responses
* Nếu phiên bản hiện tại của bạn chỉ có thể chọn mô hình tích hợp sẵn chính thức, hoặc chỉ điền được OpenAI Key chính thức mà không sửa được Base URL, thì nó không thể kết nối trực tiếp tới gateway hiện tại
* Cách làm vững nhất là trước tiên dùng GET /v1/models xác nhận các mô hình nhìn thấy được, rồi quay lại Trae điền Model ID

---

# Unsloth

Nguồn: https://docs.aicentos.com/vi/clients/unsloth

Language: vi

> Unsloth là framework tinh chỉnh và suy luận cục bộ, không phải client trò chuyện —— giải thích lý do không kết nối được aicentos

Unsloth là framework tinh chỉnh mô hình và suy luận cục bộ mã nguồn mở, kèm ứng dụng desktop và Unsloth Studio (giao diện trình duyệt). Bảng `Connections` của nó trông giống "cài đặt nhà cung cấp mô hình", nhưng **chỉ điền được endpoint cục bộ hoặc tự dựng, nhà cung cấp cloud là một danh sách cố định**, không có mục "URL tương thích OpenAI bất kỳ", vì vậy không thể trỏ yêu cầu suy luận về aicentos.

## Vì sao không thể kết nối trực tiếp

* Trong `Settings → Connections → Add Provider` của Studio, có thể chọn là các **dịch vụ cục bộ/tự dựng** như llama.cpp, vLLM, Ollama, Base URL điền có dạng `http://localhost:8000/v1`.
* Hướng cloud là một danh sách cố định (OpenAI, Anthropic, OpenRouter, ChatGPT/Codex) + API Key, không có chỗ nhập endpoint tùy chỉnh.
* "remote OpenAI-compatible endpoint" trong tài liệu chính thức chỉ **dịch vụ suy luận do chính bạn triển khai**, không phải gateway tổng hợp bên thứ ba.
* Về hướng, nó cũng nghiêng về máy chủ: Unsloth tự cung cấp API tương thích OpenAI để người khác kết nối tới.

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Mô hình  | tên mô hình trong "Model Square" của Console |

Bảng trên là tham số chung phía aicentos, dùng cho phương án thay thế dưới đây.

## Phương án thay thế

### Phương án 1: Huấn luyện ra huấn luyện, trò chuyện ra trò chuyện

Dùng Unsloth để tinh chỉnh và suy luận cục bộ, dùng các client như [Cherry Studio](https://docs.aicentos.com/vi/clients/cherry-studio), [Chatbox](https://docs.aicentos.com/vi/clients/chatbox) để kết nối aicentos cho hội thoại hàng ngày. Hai bên không ảnh hưởng lẫn nhau.

### Phương án 2: Dựng dịch vụ cục bộ, để frontend kết nối tới

Unsloth mở ra giao diện tương thích OpenAI. Sau khi dịch vụ `unsloth` chạy cục bộ, điền Base URL của client thành địa chỉ của nó (ví dụ `http://localhost:8000/v1`), thao tác giống hệt khi điền aicentos.

### Phương án 3: Muốn so sánh hiệu quả thì đổi frontend

Muốn so sánh "mô hình tinh chỉnh cục bộ" với "mô hình phổ thông trên aicentos", dùng một client hỗ trợ nhiều provider cùng tồn tại là tiết kiệm công nhất, chuyển đổi ngay trong cùng giao diện.

## Kiểm tra

Sau khi dịch vụ cục bộ khởi động, trước tiên `curl http://localhost:8000/v1/models` xác nhận giao diện còn sống, rồi gửi một câu prompt trong client.

## Lưu ý

* Đừng coi `Connections` của Studio là bảng BYOK, nó quản lý runtime cục bộ.
* Suy luận cục bộ ngốn phần cứng, tác vụ ngữ cảnh dài và khối lượng lớn khuyến nghị đi aicentos.
* Tài liệu chính thức không có mô tả quy trình "dùng API bên thứ ba sinh dữ liệu huấn luyện", đừng lập kế hoạch pipeline theo hướng này.

## Liên kết liên quan

* [Tài liệu Unsloth Connections](https://unsloth.ai/docs/integrations/connections)
* [Kho unsloth](https://github.com/unslothai/unsloth)

---

# Warp

Nguồn: https://docs.aicentos.com/vi/clients/warp

Language: vi

> Kết nối aicentos trong Warp —— đưa Warp Agent chạy qua endpoint suy luận tùy chỉnh

Warp là môi trường phát triển Agent dạng terminal. Nó hỗ trợ **Custom inference endpoint**: chỉ cần đối phương triển khai giao diện OpenAI Chat Completions, là có thể chuyển các lượt gọi mô hình của Warp Agent sang. Trỏ endpoint về aicentos, là có thể dùng các mô hình dưới tài khoản của bạn để đưa Agent của Warp chạy.

## Chuẩn bị

* Cập nhật Warp lên phiên bản có endpoint suy luận tùy chỉnh (bản cũ chỉ có BYOK, không sửa được Base URL).
* Tạo một Key chuyên dụng trong Console của aicentos (khuyến nghị đặt tên `warp-terminal`).
* Xác nhận mô hình định dùng hỗ trợ **gọi công cụ (function calling)**, Warp Agent dựa vào nó để đọc ghi file, thực thi lệnh.

## Cấu hình cần điền

| Trường        | Giá trị                                                      |
| ------------- | ------------------------------------------------------------ |
| Endpoint name | `aicentos` (tự đặt, dùng để nhận diện trong bộ chọn mô hình) |
| Endpoint URL  | `https://aicentos.com/v1`                                    |
| API Key       | Key tạo trong Console                                        |
| Model name    | model ID trong "Model Square" của Console                    |
| Model alias   | tùy chọn, tên hiển thị trong bộ chọn mô hình                 |

## Các bước thiết lập

* Mở cài đặt Warp, tìm kiếm `inference endpoint`, hoặc vào **Settings → AI**.
* Trong khu vực **Custom inference**, nhấn **Add custom model** / **Add destination**.
* Trong hộp thoại điền Endpoint name, Endpoint URL (`https://aicentos.com/v1`), API Key.
* Tại **Model name** điền model ID, nhấn **Add model** để thêm nhiều hơn; có thể điền thêm alias để dễ nhận diện.
* Sau khi lưu, mô hình tùy chỉnh sẽ xuất hiện trong bộ chọn mô hình của Warp, được đánh dấu bằng tên endpoint của bạn.

## Kiểm tra

Trong Warp chọn mô hình vừa thêm, gửi một câu hỏi đơn giản (ví dụ "liệt kê các file trong thư mục hiện tại và giải thích cấu trúc dự án") để xác nhận có thể trả về bình thường. Mô hình endpoint tùy chỉnh sẽ hiển thị trong bộ chọn của chế độ agent, thanh công cụ và ambient agent.

## Lưu ý

* Endpoint URL điền đường dẫn gốc tương thích OpenAI (có thể nối thành `/v1/chat/completions`), đừng viết thành đường dẫn đầy đủ `/v1/chat/completions`.
* Endpoint phải truy cập được từ **mạng công cộng**: yêu cầu của Warp được chuyển tiếp qua máy chủ của nó, `localhost`, địa chỉ mạng nội bộ sẽ bị từ chối. `aicentos.com` là địa chỉ HTTPS công cộng, dùng được ngay.
* API Key và thông tin endpoint được lưu trong kho bảo mật của **thiết bị cục bộ**, máy chủ Warp chỉ dùng ngay khi có yêu cầu, không lưu lại.
* Yêu cầu đi qua endpoint tùy chỉnh **không tiêu tốn AI credits của Warp**, chi phí do phía aicentos tính theo mức sử dụng; nhưng ở gói Business / Enterprise, việc chạy Agent cục bộ vẫn tiêu tốn credits của nền tảng.
* Nếu báo `400 invalid model format`, tức là gateway của bạn yêu cầu dạng `provider/model_id`; lấy model ID do Console đưa ra làm chuẩn, khi cần bổ sung tiền tố theo định dạng đó.
* Endpoint tùy chỉnh hiện chưa thể khai báo riêng cửa sổ ngữ cảnh, phiên hội thoại quá dài có thể bị nén sớm.
* Tài liệu chính thức: `https://docs.warp.dev/agent-platform/inference/custom-inference-endpoint/`

---

# Windsurf

Nguồn: https://docs.aicentos.com/vi/clients/windsurf

Language: vi

> Nhập endpoint và API Key của aicentos trong Windsurf nếu bản của bạn hỗ trợ Base URL tùy chỉnh

Tài liệu này hướng dẫn cách dùng cấu hình OpenAI tương thích tùy chỉnh trong Windsurf để kết nối dịch vụ hiện tại. Khả năng BYOK và cấu hình mô hình tùy chỉnh của các phiên bản Windsurf không hoàn toàn giống nhau, nên ở đây phân biệt hai tình huống để nói.

## Trước tiên xác nhận phiên bản của bạn có hỗ trợ Base URL tùy chỉnh không

Trong phần mô hình, gói đăng ký hoặc cài đặt AI của Windsurf, tìm các mục nhập tương tự sau:

* `Models`
* `BYOK`
* `OpenAI`
* `Custom`
* `Base URL`

Nếu bạn chỉ có thể điền API Key chính thức, mà không có Base URL nào có thể sửa, thì phiên bản này thường chỉ đi được chế độ BYOK mà chính thức hỗ trợ, không thể đổi thẳng sang gateway hiện tại.

## Điền thông tin kết nối tùy chỉnh

Nếu phiên bản của bạn cung cấp cấu hình OpenAI tương thích tùy chỉnh, thì điền:

* Base URL: `https://aicentos.com/v1`
* API Key: Key của bạn dạng `codex_...` hoặc `sk-...`
* Model ID: lấy kết quả trả về của `GET /v1/models` làm chuẩn; nếu chỉ muốn thử kết nối trước, có thể thử `gpt-6-astra`

## Kiểm tra

Sau khi lưu cài đặt, tạo một hội thoại Cascade mới hoặc tác vụ code, xác nhận có thể trả về kết quả bình thường.

## Lưu ý

* Base URL nên điền `https://aicentos.com/v1`
* Đừng viết thành đường dẫn đầy đủ `/v1/chat/completions` hay `/v1/responses`
* Nếu phiên bản hiện tại chỉ mở BYOK chính thức, không có Base URL tùy chỉnh, thì không thể kết nối thẳng gateway này
* Trang giải thích mô hình chính thức của Windsurf: `https://docs.windsurf.com/windsurf/models`

---

# WorkBuddy

Nguồn: https://docs.aicentos.com/vi/clients/workbuddy

Language: vi

> Dùng aicentos trong WorkBuddy —— kết nối qua cấu hình OpenAI tương thích tùy chỉnh

WorkBuddy hỗ trợ cấu hình mô hình OpenAI tương thích tùy chỉnh. Trỏ Base URL về aicentos, điền API Key, là có thể cho WorkBuddy dùng các mô hình aicentos tích hợp.

## Chuẩn bị

Tạo một Key chuyên dụng trong Console của aicentos (khuyến nghị đặt tên `workbuddy` để dễ theo dõi mức sử dụng).

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| Provider | `OpenAI Compatible`                          |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Model ID | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

* Mở phần cài đặt mô hình / AI của WorkBuddy.
* Đặt Provider thành **OpenAI Compatible** (hoặc "Tùy chỉnh").
* Điền API Key bạn tạo trong Console của aicentos.
* Đặt Base URL thành: `https://aicentos.com/v1`
* Điền model ID (tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)), khi cần nhập bằng tay.
* Lưu cài đặt.

## Kiểm tra

Sau khi lưu, tạo một hội thoại mới, gửi một câu prompt đơn giản, xác nhận có thể kết nối bình thường và trả về nội dung.

## Lưu ý

* Base URL chỉ điền đến `/v1`, đừng bổ sung thành đường dẫn đầy đủ `/chat/completions`.
* Nếu phiên bản hiện tại không có Base URL có thể sửa, chỉ điền được Key chính thức, thì không thể kết nối thẳng gateway này, cần đổi sang client hỗ trợ endpoint tùy chỉnh.
* Khuyến nghị trước tiên dùng `GET /v1/models` xác nhận các mô hình nhìn thấy được, rồi quay lại WorkBuddy điền Model ID.
* Khi không đủ số dư tài khoản, yêu cầu sẽ thất bại, trước tiên vào [trang Ví](https://aicentos.com/wallet) xác nhận số dư.

---

# ZCode

Nguồn: https://docs.aicentos.com/vi/clients/zcode

Language: vi

> Dùng aicentos trong ZCode —— kết nối qua cấu hình OpenAI tương thích tùy chỉnh

ZCode hỗ trợ cấu hình mô hình OpenAI tương thích tùy chỉnh. Trỏ Base URL về aicentos, điền API Key, là có thể dùng các mô hình aicentos tích hợp trong hội thoại và tác vụ code của ZCode.

## Chuẩn bị

Tạo một Key chuyên dụng trong Console của aicentos (khuyến nghị đặt tên `zcode` để dễ theo dõi mức sử dụng).

## Cấu hình cần điền

| Trường   | Giá trị                                      |
| -------- | -------------------------------------------- |
| Provider | `OpenAI Compatible`                          |
| API Key  | Key tạo trong Console                        |
| Base URL | `https://aicentos.com/v1`                    |
| Model ID | tên mô hình trong "Model Square" của Console |

## Các bước thiết lập

* Mở cài đặt ZCode, vào khu vực cấu hình mô hình / AI.
* Tìm các tùy chọn liên quan Provider, chọn **OpenAI Compatible** (hoặc "OpenAI tùy chỉnh").
* Điền API Key bạn tạo trong Console của aicentos.
* Đặt Base URL thành: `https://aicentos.com/v1`
* Điền model ID (tham khảo [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list)); khi dropdown không có mô hình đích thì nhập trực tiếp bằng tay.
* Lưu cài đặt, nếu có nút **Verify** thì nhấn thử một lần.

## Kiểm tra

Tạo một hội thoại mới hoặc tác vụ code, gửi một câu prompt đơn giản, xác nhận có thể trả về nội dung bình thường.

## Lưu ý

* Base URL chỉ điền đến `/v1`, đừng bổ sung thành đường dẫn đầy đủ `/chat/completions` hay `/v1/responses`.
* Nếu phiên bản hiện tại chỉ chọn được mô hình tích hợp sẵn chính thức, không có Base URL có thể sửa, thì không thể kết nối thẳng gateway này, lúc này chỉ có thể đổi sang client hỗ trợ endpoint tùy chỉnh.
* Khuyến nghị trước tiên dùng `GET /v1/models` xác nhận các mô hình nhìn thấy được, rồi quay lại ZCode điền Model ID.
* Khi không đủ số dư tài khoản, yêu cầu sẽ thất bại, trước tiên vào [trang Ví](https://aicentos.com/wallet) xác nhận số dư.

---

# Zed Agent

Nguồn: https://docs.aicentos.com/vi/clients/zed-agent

Language: vi

> Kết nối aicentos trong Agent Panel của Zed qua provider OpenAI tương thích

Zed tích hợp sẵn loại provider OpenAI tương thích, khai báo endpoint, mô hình và độ dài ngữ cảnh trong `settings.json`, là có thể cho Agent Panel dùng các mô hình aicentos tích hợp.

## Chuẩn bị

Trước tiên, tạo một Key chuyên dụng cho Zed tại trang "API Key" trong Console (khuyến nghị đặt tên `zed-agent`).

* Console: [https://aicentos.com](https://aicentos.com)
* Tạo Key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Nạp tiền Ví: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Zed không ghi API Key vào `settings.json`, mà đọc biến môi trường cùng tên: Provider ID sẽ được chuyển thành chữ hoa dạng snake\_case rồi thêm hậu tố `_API_KEY`. Vì vậy khi Provider ID đặt là `aicentos`, tên biến môi trường chính là `AICENTOS_API_KEY`.

## Cấu hình cần điền

| Trường                          | Giá trị                                      |
| ------------------------------- | -------------------------------------------- |
| Provider ID                     | tự đặt, ví dụ `aicentos`                     |
| `api_url`                       | `https://aicentos.com/v1`                    |
| `available_models[].name`       | tên mô hình trong "Model Square" của Console |
| `available_models[].max_tokens` | cửa sổ ngữ cảnh của mô hình                  |
| API Key                         | biến môi trường `AICENTOS_API_KEY`           |

## Các bước thiết lập

* Mở `settings.json` của Zed (command palette thực hiện `zed: open settings`).
* Thêm cấu hình `language_models.openai_compatible`:

```json
{
  "language_models": {
    "openai_compatible": {
      "aicentos": {
        "api_url": "https://aicentos.com/v1",
        "available_models": [
          {
            "name": "gpt-5",
            "display_name": "GPT-5 (aicentos)",
            "max_tokens": 128000,
            "max_output_tokens": 16384,
            "capabilities": {
              "tools": true,
              "images": false,
              "chat_completions": true
            }
          }
        ]
      }
    }
  }
}
```

* Xuất biến môi trường (ghi vào `~/.zshrc` rồi tải lại):

```bash
export AICENTOS_API_KEY="sk-Key-aicentos-của-bạn"
```

* Mở Agent Panel, trong dropdown mô hình chọn mô hình dưới provider này.

Cũng có thể trong cài đặt Agent nhấn **Add Provider**, điền tên Provider, API URL, model ID và cửa sổ ngữ cảnh qua giao diện đồ hoạ.

## Kiểm tra

Sau khi cấu hình xong, tạo một hội thoại mới trong Agent Panel, trước tiên test nhẹ bằng một câu prompt đơn giản, xác nhận có thể trả về bình thường rồi mới chính thức dùng gọi công cụ.

## Lưu ý

* `api_url` chỉ điền đến `https://aicentos.com/v1`, đừng bổ sung thành `/chat/completions` đầy đủ; Zed sẽ tự nối.
* API Key không được viết trực tiếp vào `settings.json`, bắt buộc dùng biến môi trường (hoặc lưu vào system keychain qua giao diện cài đặt Provider); biến môi trường khác rỗng có độ ưu tiên cao hơn keychain.
* `max_tokens` là cửa sổ ngữ cảnh, khuyến nghị điền theo giá trị thực của mô hình; nếu thiếu sẽ khiến việc quản lý ngữ cảnh bất thường.
* Gọi công cụ mặc định được bật (`capabilities.tools`), nhập ảnh và gọi công cụ song song mặc định tắt, khi cần thì bật thủ công.
* Tài liệu chính thức: [https://zed.dev/docs/ai/llm-providers](https://zed.dev/docs/ai/llm-providers)
* Xem thêm giải thích tại trang tài liệu: [https://docs.aicentos.com](https://docs.aicentos.com)

---

# Giới thiệu aicentos

Nguồn: https://docs.aicentos.com/vi/introduction

Language: vi

> Một API cho mọi LLM — tổng hợp OpenAI, Anthropic, Google, xAI và các nhà cung cấp lớn khác

**aicentos** là nền tảng tổng hợp AI API dành cho lập trình viên. Một API Key để gọi các LLM từ OpenAI, Anthropic, Google, xAI, DeepSeek và các nhà cung cấp lớn khác.

Trang chủ aicentos

## Chúng tôi giải quyết vấn đề gì

Điều gì khiến việc tích hợp LLM khó khăn? Đăng ký riêng, key riêng, hóa đơn riêng, SDK riêng. aicentos làm phẳng tất cả.

| Nỗi đau              | Cách truyền thống            | aicentos                                    |
| -------------------- | ---------------------------- | ------------------------------------------- |
| Chuyển đổi mô hình   | Đổi SDK, URL, key            | **Đổi một tham số `model`**                 |
| Tài khoản nước ngoài | Thẻ / số điện thoại quốc tế  | **Tặng ¥1 khi đăng ký, nạp qua Alipay**     |
| Chuẩn API            | Mỗi nhà một chuẩn            | **Giao thức thống nhất tương thích OpenAI** |
| Minh bạch chi phí    | Xem riêng từng nơi           | **Hóa đơn và log sử dụng thống nhất**       |
| Quản lý key          | Không có phân quyền chi tiết | **Hạn mức, danh sách mô hình, giới hạn IP** |

Console gom key, số dư, mức dùng và log vào một nơi:

Tổng quan console

## Tính năng chính

### Truy cập đa nhà cung cấp

OpenAI, Anthropic, Google, xAI, Alibaba Qwen, DeepSeek, Zhipu, Moonshot, MiniMax — **tất cả phía sau một endpoint**: chat, suy luận, code, ảnh, video và embedding. Mô hình mới được tích hợp dần; cách gọi SDK hiện tại giữ nguyên.

Xem [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list) để có danh sách đầy đủ.

### Khả dụng kiểm chứng được

Mỗi mô hình có kiểm tra sức khoẻ riêng. Trên [bảng theo dõi trạng thái](https://docs.aicentos.com/status), bạn xem khả dụng 1 giờ / 24 giờ / 7 ngày, độ trễ và PING endpoint trước khi tích hợp.

### An toàn

API Key hỗ trợ **giới hạn hạn mức, danh sách mô hình, giới hạn IP, thời hạn hiệu lực**, cấp phát theo dự án hoặc thành viên để quản chi phí và thu hồi quyền.

### Thân thiện lập trình viên

Tương thích hoàn toàn **giao thức OpenAI**. Dự án OpenAI / Codex hiện có chỉ cần đổi `base_url` thành `https://aicentos.com/v1`; Claude / Anthropic và các giao thức khác dùng địa chỉ gốc `https://aicentos.com` — **di trú với 0 dòng code**.

## Phù hợp với ai

* Lập trình viên muốn dùng **Claude / GPT / Gemini** mà không cần tài khoản và thẻ quốc tế
* Nhà nghiên cứu / lập trình viên agent **thường xuyên so sánh nhiều LLM**
* Đội nhóm cần **hóa đơn / hạn mức / kiểm toán sử dụng thống nhất**
* Kỹ sư gặp **độ trễ cao / đường truyền bất ổn** đến API nước ngoài

## Số liệu nền tảng

| Chỉ số         |                   Giá trị |
| -------------- | ------------------------: |
| Thưởng đăng ký |           **¥1 tín dụng** |
| Hiệu lực số dư | **Không bao giờ hết hạn** |

## Bước tiếp theo

* [Quickstart](https://docs.aicentos.com/vi/quickstart) — ba bước đến request đầu tiên
* [Các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list) — danh sách đầy đủ
* [Bảng theo dõi trạng thái](https://docs.aicentos.com/status) — khả dụng theo thời gian thực
* [Thanh toán](https://docs.aicentos.com/vi/billing/pricing) — nạp tiền và tính theo mức dùng

---

# Tạo ảnh Nano Banana 2

Nguồn: https://docs.aicentos.com/vi/nano-banana2

Language: vi

> Gọi gemini-3.1-flash-image-preview (Nano Banana 2) qua aicentos để tạo ảnh — ví dụ định dạng Gemini gốc và định dạng tương thích OpenAI

Bài viết này đưa ra ví dụ request tạo ảnh bằng **Nano Banana 2** (`gemini-3.1-flash-image-preview`) qua aicentos, hỗ trợ hai dạng tham số: **định dạng Gemini gốc** và **định dạng tương thích OpenAI**.

Qua `imageConfig` có thể chỉ định tỷ lệ khung hình (`aspectRatio`) và độ phân giải (`imageSize`, ví dụ `2K`, `4K`).

## Định dạng Gemini gốc

Tạo ảnh 4K tỉ lệ 1:1, ví dụ request:

```bash
export AICENTOS_API_KEY="sk-thay-vào-đây"

curl --location --request POST 'https://aicentos.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent' \
--header "x-goog-api-key: $AICENTOS_API_KEY" \
--header 'content-type: application/json' \
--header 'Accept: */*' \
--data-raw '{
  "contents": [
    {
      "parts": [
        {
          "text": "Phong cách poster quảng cáo cổ điển, làm nổi bật chữ tiếng Trung, nền là họa tiết tia sáng đỏ - vàng. Ở trung tâm khung hình là một cô gái trẻ xinh đẹp được vẽ theo phong cách vintage tinh tế, mỉm cười, đằm thắm, thanh lịch và gần gũi. Chủ đề là quảng cáo khuyến mãi cho dịch vụ vẽ tranh AI mới nhất, độ phân giải 4K\n"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "image"
    ],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "4K"
    }
  }
}'
```

## Định dạng tương thích OpenAI

Tạo ảnh 2K tỉ lệ 9:16, ví dụ request:

```bash
export AICENTOS_API_KEY="sk-thay-vào-đây"

curl --location --request POST 'https://aicentos.com/v1/chat/completions' \
--header "Authorization: Bearer $AICENTOS_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "model": "gemini-3.1-flash-image-preview",
    "extra_body": {
        "imageConfig": {
            "aspectRatio": "9:16",
            "imageSize": "2K"
        }
    },
    "messages": [
        {
            "role": "system",
            "content": "{\"imageConfig\": {\"aspectRatio\": \"9:16\", \"imageSize\": \"2K\"}}"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Vẽ tranh chúc may mắn năm con Ngựa"
                }
            ]
        }
    ],
    "max_tokens": 4096,
    "temperature": 0.8
}'
```

## Mô tả tham số

* `aspectRatio`: tỷ lệ khung hình, ví dụ `1:1`, `9:16`, `16:9`.
* `imageSize`: độ phân giải, ví dụ `2K`, `4K`.
* Định dạng Gemini gốc xác thực bằng `x-goog-api-key`, định dạng tương thích OpenAI xác thực bằng `Authorization: Bearer`.
* Với định dạng tương thích OpenAI, `imageConfig` có thể đặt trong `extra_body` hoặc trong JSON của message `system`.
* Thay `sk-thay-vào-đây` trong ví dụ bằng API Key bạn đã tạo trong Console aicentos.

---

# Bắt đầu nhanh

Nguồn: https://docs.aicentos.com/vi/quickstart

Language: vi

> Tích hợp trong ba bước: đăng ký tài khoản → tạo API Key → điền Base URL và Key vào client

Tích hợp trong ba bước: **đăng ký tài khoản → tạo API Key → điền Base URL và Key vào client**.

## Bước 1: Đăng ký tài khoản

Mở [aicentos.com](https://aicentos.com/), nhấn "**Bắt đầu sử dụng**" ở góc trên bên phải để vào trang đăng ký:

Trang đăng ký

Điền **tên người dùng** và **mật khẩu**, tích đồng ý điều khoản dịch vụ rồi nhấn "Tạo tài khoản". Đăng ký được tặng ngay **¥1** tín dụng dùng thử, gọi API ngay mà không cần nạp tiền.

## Bước 2: Tạo API Key

Sau khi đăng nhập vào Console, ở menu bên trái nhấn "**API Key**", rồi nhấn "**Tạo API Key**" ở góc trên bên phải:

Trang API Key

Điền cấu hình trong hộp thoại rồi nhấn "Lưu thay đổi":

Tạo API Key

| Trường         | Mô tả                                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| Tên            | Tự đặt để phân biệt các dự án. Nên tạo riêng theo từng mục đích để thuận tiện tổng hợp chi phí và thu hồi quyền |
| Nhóm           | Chọn nhóm upstream; để trống sẽ dùng nhóm mặc định                                                              |
| Thời hạn       | Hỗ trợ "không bao giờ hết hạn" hoặc chọn 1 giờ / 1 ngày / 1 tháng                                               |
| Số lượng       | Tạo nhiều key cùng lúc, tên sẽ tự động thêm hậu tố ngẫu nhiên                                                   |
| Hạn mức vô hạn | Tắt đi thì có thể đặt giới hạn hạn mức cho key này                                                              |

Sau khi tạo xong, key sẽ xuất hiện trong danh sách dạng `sk-xxxxxxxxxxxx`, mặc định được che bớt:

Key đã tạo

Danh sách key hỗ trợ tìm kiếm theo tên và key; có thể xem nhóm, hạn mức, mô hình khả dụng, giới hạn IP... và chỉnh sửa hoặc xóa bất cứ lúc nào:

Danh sách key

> **Key chỉ hiển thị đầy đủ một lần duy nhất khi tạo**, hãy sao chép và lưu giữ ngay. Đừng hard-code vào code frontend hay commit lên repo công khai.

## Bước 3: Điền Base URL và Key vào client

### Chọn đúng Base URL trước

Đây là bước dễ sai nhất — **mỗi giao thức dùng một địa chỉ khác nhau**:

| Trường hợp sử dụng                                      | Base URL                  |
| ------------------------------------------------------- | ------------------------- |
| Codex / định dạng tương thích OpenAI                    | `https://aicentos.com/v1` |
| Claude Code / định dạng Anthropic, cùng các client khác | `https://aicentos.com`    |

> **Giao thức Anthropic chỉ điền địa chỉ gốc**, đừng tự thêm `/v1/messages`, client sẽ tự nối.

Ở trang "API Key" trong Console, bạn cũng có thể xem và sao chép trực tiếp từ menu thả xuống "**Địa chỉ API**" ở góc trên bên phải:

Địa chỉ API

### Kiểm tra kết nối

Chạy một request tối thiểu bằng curl để xác nhận Key và mạng hoạt động:

```bash
export AICENTOS_API_KEY="sk-key-của-bạn"

curl https://aicentos.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      {"role": "user", "content": "Giới thiệu bản thân trong một câu"}
    ]
  }'
```

Cũng có thể gọi danh sách mô hình trước. Chỉ cần trả về JSON là key và Base URL đều dùng được:

```bash
export AICENTOS_API_KEY="sk-key-của-bạn"

curl https://aicentos.com/v1/models \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

### Python (OpenAI SDK)

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AICENTOS_API_KEY"],
    base_url="https://aicentos.com/v1",
)

resp = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "Giới thiệu bản thân trong một câu"}],
)
print(resp.choices[0].message.content)
```

### Node.js (OpenAI SDK)

Ví dụ dùng cú pháp ESM, tên tệp phải là `.mjs`, hoặc thêm `"type": "module"` vào `package.json`:

```js
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.AICENTOS_API_KEY,
  baseURL: 'https://aicentos.com/v1',
});

const resp = await client.chat.completions.create({
  model: 'gemini-3.8-flash',
  messages: [{ role: 'user', content: 'Giới thiệu bản thân trong một câu' }],
});

console.log(resp.choices[0].message.content);
```

### Các client phổ biến

* [Tích hợp Claude Code](https://docs.aicentos.com/vi/claude-code) — import một chạm bằng CC Switch hoặc cấu hình thủ công
* [Tích hợp Codex](https://docs.aicentos.com/vi/codex) — cấu hình bằng giao diện hoặc tự viết config.toml
* [Tích hợp Cursor](https://docs.aicentos.com/vi/cursor) — tùy chỉnh cài đặt tương thích OpenAI
* [Tích hợp Cherry Studio](https://docs.aicentos.com/vi/cherry-studio) — thêm nhà cung cấp tương thích OpenAI

## Nạp tiền

Khi tín dụng tặng dùng hết, vào mục "**Ví**" ở menu bên trái của Console để nạp tiền:

Ví

Các mốc nạp và ưu đãi (**nạp từ ¥100 trở lên có chiết khấu, số tiền thực trả thấp hơn mức nạp**):

| Mức nạp              | Ưu đãi | Thực trả |
| -------------------- | ------ | -------- |
| ¥1 / ¥10 / ¥20 / ¥50 | Không  | Giá gốc  |
| ¥100                 | 1% OFF | ¥99      |
| ¥500                 | 2% OFF | ¥490     |
| ¥1,000               | 3% OFF | ¥970     |
| ¥10,000              | 5% OFF | ¥9,500   |

Cũng có thể nhập số tiền tùy ý, hoặc dùng mã đổi quà để nhận hạn mức.

Phương thức thanh toán

* **Phương thức thanh toán**: Alipay, WeChat, chuyển khoản doanh nghiệp
* **Hạn mức không bao giờ hết hạn**, tính phí theo token tiêu thụ thực tế
* Có thưởng giới thiệu: đăng ký qua link giới thiệu thì cả hai bên đều nhận thưởng, có thể chuyển vào số dư bất cứ lúc nào

## Xem mức sử dụng

Vào mục "**Dashboard**" ở menu bên trái của Console để xem chi tiết tiêu thụ:

Tổng quan Console

Bạn sẽ thấy số dư hiện tại, tổng mức dùng, số request API và xu hướng gọi theo từng mô hình:

Dashboard

## Thử ngay không cần viết code

Trong mục "**Chat**" ở đầu Console có Playground tích hợp sẵn, chọn mô hình, gửi tin nhắn và tinh chỉnh prompt ngay trong lúc trò chuyện:

Playground

## Bước tiếp theo

* Thử mô hình ngay trên trình duyệt trong [Playground](https://aicentos.com/playground), không cần viết code
* Xem [các mô hình hỗ trợ](https://docs.aicentos.com/vi/billing/models-list) — biết hỗ trợ những LLM nào
* Đọc [xử lý lỗi](https://docs.aicentos.com/vi/billing/errors) — xử lý lỗi 401, hết số dư...
* Tìm hiểu [quy tắc tính phí](https://docs.aicentos.com/vi/billing/pricing) — tính phí theo mức dùng và cảnh báo số dư

---

# Bảng theo dõi trạng thái mô hình

Nguồn: https://docs.aicentos.com/vi/status

Language: vi

> Xem khả dụng, độ trễ và PING endpoint của từng mô hình theo thời gian thực

Bảng giám sát trực tiếp hiện chỉ có trên [trang trạng thái tiếng Trung](https://docs.aicentos.com/status).

---

# Tạo video Veo

Nguồn: https://docs.aicentos.com/vi/veo-video

Language: vi

> Gọi mô hình tạo video Google Veo qua aicentos — tạo video từ văn bản, từ ảnh, khung đầu - cuối, ảnh tham chiếu

Bài viết dành cho lập trình viên, hướng dẫn cách gọi mô hình tạo video Google Veo qua aicentos. API theo định dạng tương thích OpenAI Videos API; khi tích hợp phía hạ nguồn chỉ cần đặt loại channel là `openai`.

## Mô tả năng lực mô hình

Tính phí theo thời lượng tạo video (giây). Đơn giá cụ thể lấy theo Console aicentos; khoản trừ cuối cùng dựa trên bản ghi trừ phí thực tế của hệ thống.

### Năng lực chính thức và phạm vi aicentos mở

| Mô hình                         | Số giây hỗ trợ | Độ phân giải hỗ trợ | Tỷ lệ khung hình | Âm thanh        | Ghi chú                                                                                      |
| ------------------------------- | -------------- | ------------------- | ---------------- | --------------- | -------------------------------------------------------------------------------------------- |
| `veo-3.1-generate-preview`      | 4, 6, 8        | 720p, 1080p, 4k     | 16:9, 9:16       | Có sẵn âm thanh | 1080p và 4k chỉ hỗ trợ 8 giây; khi dùng ảnh tham chiếu, khung đầu - cuối... nên chọn 8 giây. |
| `veo-3.1-fast-generate-preview` | 4, 6, 8        | 720p, 1080p, 4k     | 16:9, 9:16       | Có sẵn âm thanh | 1080p và 4k chỉ hỗ trợ 8 giây; khi dùng ảnh tham chiếu, khung đầu - cuối... nên chọn 8 giây. |

Tài liệu tham khảo:

* [Google Gemini API — tạo video Veo](https://ai.google.dev/gemini-api/video)
* [Mô tả ảnh tham chiếu của Veo](https://ai.google.dev/gemini-api/video#reference_images)
* [Mô tả khung đầu - cuối của Veo](https://ai.google.dev/gemini-api/video#first_and_last_frame)
* [Mô tả tỷ lệ khung hình của Veo](https://ai.google.dev/gemini-api/video#aspect_ratio)

### Tỷ lệ khung hình

| Mô hình                         | 16:9 ngang | 9:16 dọc | Tỷ lệ mặc định | Khuyến nghị                                                |
| ------------------------------- | ---------- | -------- | -------------- | ---------------------------------------------------------- |
| `veo-3.1-generate-preview`      | Hỗ trợ     | Hỗ trợ   | 16:9           | 4K bắt buộc dùng 8 giây; video extension tạm thời chưa mở. |
| `veo-3.1-fast-generate-preview` | Hỗ trợ     | Hỗ trợ   | 16:9           | 4K bắt buộc dùng 8 giây; video extension tạm thời chưa mở. |

Trong request có thể chỉ định tỷ lệ qua `metadata.aspectRatio` hoặc trường form `aspectRatio`:

```bash
{
  "metadata": {
    "aspectRatio": "9:16"
  }
}
```

Nếu không truyền rõ `aspectRatio`, hệ thống sẽ ưu tiên suy ra tỷ lệ từ `size`, ví dụ `1280x720` suy ra 16:9, `720x1280` suy ra 9:16. Nếu cũng không truyền `size`, upstream mặc định dùng 16:9.

### Về âm thanh

| Mô hình                         | Năng lực âm thanh chính thức | Hỗ trợ generateAudio | Khuyến nghị                                                             |
| ------------------------------- | ---------------------------- | -------------------- | ----------------------------------------------------------------------- |
| `veo-3.1-generate-preview`      | Có sẵn âm thanh              | Không hỗ trợ         | Đừng truyền `generateAudio`; cần hiệu ứng âm thanh thì viết vào prompt. |
| `veo-3.1-fast-generate-preview` | Có sẵn âm thanh              | Không hỗ trợ         | Đừng truyền `generateAudio`; cần hiệu ứng âm thanh thì viết vào prompt. |

Dòng Veo 3.1 là mô hình video có sẵn âm thanh, nhưng bảng tham số Veo của Gemini API hiện chưa mở `generateAudio` làm tham số điều khiển được. Truyền trường này có thể bị upstream trả `INVALID_ARGUMENT`.

Nếu muốn kiểm soát nội dung âm thanh, có thể mô tả lời thoại, âm thanh môi trường, hiệu ứng âm thanh hoặc phong cách nhạc trong prompt, ví dụ:

```bash
Hải đăng bên bờ biển lúc hoàng hôn, sóng biển vỗ nhẹ vào đá ngầm, xa xa có tiếng gió trầm và tiếng chim biển, ánh sáng chuẩn điện ảnh, máy quay chuyển động ổn định
```

## Năng lực đầu vào ảnh

| Năng lực                             | Veo chính thức của Google                      | API aicentos hỗ trợ | Ghi chú                                                                                                                           |
| ------------------------------------ | ---------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Tạo video từ một ảnh khởi đầu        | Hỗ trợ                                         | Hỗ trợ              | Dùng `input_reference` để tải lên 1 ảnh làm khung hình bắt đầu của video.                                                         |
| Tạo từ khung đầu - cuối / chèn khung | Dòng Veo 3.1 hỗ trợ image + lastFrame          | Hỗ trợ              | Khung đầu dùng `input_reference`, khung cuối dùng `last_frame` hoặc `lastFrame`. Khuyến nghị dòng Veo 3.1, 8 giây.                |
| Nhiều ảnh tham chiếu                 | Dòng Veo 3.1 hỗ trợ tối đa 3 referenceImages   | Hỗ trợ              | Tải lên qua `reference_image`, `reference_images` hoặc `referenceImages`; `referenceType` chỉ hỗ trợ `asset`. Khuyến nghị 8 giây. |
| Video extension                      | Veo 3.1 / Fast hỗ trợ kéo dài video Veo sẵn có | Tạm chưa hỗ trợ     | API aicentos hiện chưa mở đầu vào video chính thức.                                                                               |

* MIME type ảnh hỗ trợ `image/jpeg`, `image/png`, `image/webp`. Nên truyền tệp hoặc Base64, không nên truyền trực tiếp URL ảnh từ xa.
* Lưu ý chế độ ảnh tham chiếu: upstream hiện không hỗ trợ `negativePrompt` trong tình huống ảnh tham chiếu; nếu truyền có thể nhận về `Negative prompt is not supported in your use case`. Request dùng ảnh tham chiếu đừng truyền `negativePrompt`.
* Ghi chú triển khai: ảnh đầu vào của `predictLongRunning` cho Veo trong Gemini API dùng `bytesBase64Encoded` + `mimeType`, không phải `inlineData` của `generateContent` thông thường. aicentos sẽ chuyển ảnh upload dạng multipart sang định dạng upstream cần.

## Quy tắc tính phí

* Tính phí theo thời lượng tạo video, đơn vị là giây. Hãy dùng số giây mà mô hình hỗ trợ như bảng trên, không nên truyền số giây tùy ý.
* Nếu request không chỉ định thời lượng video, hệ thống mặc định tính phí 8 giây.
* Thứ tự ưu tiên nhận diện số giây: `metadata.durationSeconds` > `duration` > `seconds` > mặc định 8 giây.
* Thứ tự ưu tiên nhận diện độ phân giải: `metadata.resolution` > `size` > mặc định 720p.
* 720p / 1080p / 4K tính phí theo cùng một quy tắc, không phụ thu riêng theo độ phân giải.
* `aspectRatio` chỉ quyết định khung ngang hay dọc, không tính thêm phí.
* 4K chỉ hỗ trợ 8 giây.
* Đơn giá cụ thể lấy theo Console aicentos.

## Mô tả API

Hiện khuyến nghị dùng 3 endpoint sau:

| Mục đích            | Phương thức | Đường dẫn                      |
| ------------------- | ----------- | ------------------------------ |
| Tạo task            | POST        | `/v1/videos`                   |
| Truy vấn trạng thái | GET         | `/v1/videos/{task_id}`         |
| Tải kết quả         | GET         | `/v1/videos/{task_id}/content` |

Nếu muốn lấy luôn địa chỉ kết quả khi truy vấn, có thể dùng:

| Mục đích                               | Phương thức | Đường dẫn                         |
| -------------------------------------- | ----------- | --------------------------------- |
| Truy vấn trạng thái và địa chỉ kết quả | GET         | `/v1/video/generations/{task_id}` |

### Xác thực

```bash
export BASE_URL="https://aicentos.com"
export AICENTOS_API_KEY="sk-xxxxxx"
```

Mọi request đều kèm:

```bash
-H "Authorization: Bearer $AICENTOS_API_KEY"
```

### Tạo task video từ văn bản

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "Hải đăng bên bờ biển lúc hoàng hôn, máy quay tiến chậm lại gần, sóng biển vỗ nhẹ vào đá ngầm, ánh sáng chuẩn điện ảnh, máy quay chuyển động ổn định",
    "seconds": "8",
    "size": "1280x720",
    "metadata": {
      "negativePrompt": "blurry, watermark, distorted, low quality",
      "resolution": "720p",
      "aspectRatio": "16:9",
      "seed": 20260401
    }
  }'
```

Kết quả trả về điển hình:

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1775025000
}
```

### Tạo task video từ ảnh khung đầu

Hiện nay image-to-video khuyến nghị dùng `multipart/form-data`, tên trường ảnh khung đầu bắt buộc phải là `input_reference`.

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Cô gái trong khung hình quay đầu nhìn vào ống kính, gió nhẹ thổi tung tóc, ánh đèn thành phố phía sau mờ nhẹ, máy quay tiến đều" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, deformed hands" \
  -F "seed=20260401"
```

### Tạo task khung đầu - cuối

Task khung đầu - cuối cần cung cấp cả khung đầu và khung cuối. Khung đầu dùng `input_reference`, khung cuối dùng `last_frame` hoặc `lastFrame`.

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Chuyển cảnh tự nhiên từ khung cô gái đầu tiên sang khung cậu bé cuối cùng, máy quay tiến đều, ánh đèn thành phố mờ nhẹ, tóc và quần áo khẽ lay theo gió, chuyển cảnh tự nhiên chân thực" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "last_frame=@./last-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \
  -F "seed=20260402"
```

### Tạo task với ảnh tham chiếu

Task ảnh tham chiếu chỉ hỗ trợ dòng Veo 3.1, tối đa 3 ảnh và `referenceType` chỉ hỗ trợ `asset`. Tên trường có thể là `reference_image`, `reference_images` hoặc `referenceImages`. Request ảnh tham chiếu đừng truyền `negativePrompt`.

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Tham khảo ngoại hình nhân vật và không khí phố đêm trong hai ảnh, tạo một cú quay phố kiểu điện ảnh với hai người, máy quay tiến đều, ánh đèn nền mờ nhẹ, nhân vật tự nhiên nhìn vào ống kính" \
  -F "reference_image=@./ref-1.png;type=image/png" \
  -F "reference_image=@./ref-2.png;type=image/png" \
  -F "reference_type=asset" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260403"
```

JSON / Base64 cũng được hỗ trợ:

```bash
{
  "model": "veo-3.1-generate-preview",
  "prompt": "Tạo cảnh quảng cáo dựa trên ngoại hình sản phẩm trong ảnh tham chiếu",
  "duration": 8,
  "metadata": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceImages": [
      {
        "image": {
          "bytesBase64Encoded": "BASE64_IMAGE",
          "mimeType": "image/png"
        },
        "referenceType": "asset"
      }
    ]
  }
}
```

### Truy vấn trạng thái task

Trước tiên hãy lưu lại `id` hoặc `task_id` mà API tạo task trả về:

```bash
export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Sau đó truy vấn trạng thái:

```bash
curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

Khi đang xử lý, kết quả trả về điển hình:

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1775025000
}
```

Khi hoàn thành, kết quả trả về điển hình:

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025068
}
```

### Truy vấn trạng thái và địa chỉ kết quả

Nếu muốn lấy luôn địa chỉ tải được khi truy vấn, có thể gọi:

```bash
curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

Kết quả trả về điển hình:

```bash
{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}
```

### Tải video kết quả

Sau khi task hoàn thành, tải trực tiếp:

```bash
curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -o veo-result.mp4
```

## Mô tả trạng thái

Các trạng thái chính mà `GET /v1/videos/{task_id}` trả về:

| Trạng thái    | Ý nghĩa       |
| ------------- | ------------- |
| `queued`      | Đã xếp hàng   |
| `in_progress` | Đang tạo      |
| `completed`   | Đã hoàn thành |
| `failed`      | Thất bại      |

Các trạng thái chính mà `GET /v1/video/generations/{task_id}` trả về:

| Trạng thái   | Ý nghĩa     |
| ------------ | ----------- |
| `queued`     | Đã xếp hàng |
| `processing` | Đang tạo    |
| `succeeded`  | Thành công  |
| `failed`     | Thất bại    |

## Lưu ý khi tích hợp

* `prompt` là bắt buộc.
* Với image-to-video, tên trường ảnh bắt buộc phải là `input_reference`.
* Task khung đầu - cuối phải cung cấp cả khung đầu và khung cuối; khung đầu dùng `input_reference`, khung cuối dùng `last_frame` hoặc `lastFrame`.
* Task ảnh tham chiếu chỉ hỗ trợ dòng Veo 3.1, tối đa 3 ảnh và bắt buộc 8 giây.
* Request ảnh tham chiếu đừng truyền `negativePrompt`.
* Hiện image-to-video Gemini không khuyến nghị truyền trực tiếp URL ảnh từ xa; nên truyền tệp hoặc Base64.
* Nên polling `GET /v1/videos/{task_id}`, đợi `status=completed` rồi mới tải về.
* Dòng Veo 3.1 nhận 4, 6, 8 giây; khi dùng 1080p hoặc 4k bắt buộc phải truyền 8 giây. - Ngang dùng `aspectRatio=16:9`, dọc dùng `aspectRatio=9:16`; nếu không truyền, mặc định xử lý theo 16:9.
* Đừng truyền tham số `generateAudio`. Dòng Veo 3.1 là mô hình video có sẵn âm thanh, nhưng Gemini API hiện không hỗ trợ bật/tắt âm thanh qua tham số `generateAudio`; truyền trường này có thể bị upstream trả `INVALID_ARGUMENT`.
* Nếu cần kiểm soát nội dung âm thanh, hãy mô tả lời thoại, âm thanh môi trường, hiệu ứng âm thanh hoặc phong cách nhạc trong prompt.
* Veo 3.1 chính thức hỗ trợ video extension, nhưng API aicentos hiện tạm chưa mở đầu vào video chính thức.