> ## Content Index
> Fetch the complete content index at: https://blog.avis.xyz/llms.txt
> Use this file to discover other available public pages before exploring further.

# Thực hiện AI API Call trong vòng 5 phút
- URL: https://blog.avis.xyz/thuc-hien-ai-api-call-trong-vong-5-phut/
- Published: 2026-08-14T02:21:02.000Z
- Updated: 2026-08-14T02:21:02.000Z
- Description: Hướng dẫn thực hiện lệnh gọi AI API đầu tiên chỉ với API key, base URL và model ID, bắt đầu bằng bước kiểm tra kết nối miễn phí không yêu cầu tài khoản.
- Author: AVIS
- Tags: Vietnamese

Thực hiện lệnh gọi API AI đầu tiên đơn giản hơn bạn tưởng. Về cơ bản, bạn chỉ cần các trường thông tin sau: **API key, base URL và model ID**. Request gần giống so với một HTTP POST thông thường.

Nếu đã từng làm việc với REST API, phần lớn quy trình này sẽ khá quen thuộc. Những điểm cần lưu ý chủ yếu nằm ở phương thức xác thực và cấu trúc response. Trong hướng dẫn này, chúng ta sẽ thực hiện request đầu tiên, đồng thời tìm hiểu cách nhận diện và xử lý các lỗi thường gặp.

Trước tiên, bắt đầu bằng một bước kiểm tra hoàn toàn miễn phí và không yêu cầu tài khoản.

## Bước 1: Kiểm tra khả năng kết nối tới API

Thông thường, một hướng dẫn sử dụng API sẽ bắt đầu bằng việc yêu cầu người dùng đăng ký tài khoản và nạp tiền. Tuy nhiên, trước khi thực hiện các bước này, bạn có thể kiểm tra trước xem hệ thống của mình có kết nối được tới API hay không.

AVIS cung cấp các endpoint kiểm tra kết nối không yêu cầu xác thực cho cả ba API surface. Theo [tài liệu xác thực](https://docs.avis.xyz/api-reference/introduction/authentication?ref=blog.avis.xyz), các endpoint `HEAD /api/openai`, `HEAD /api/anthropic` và `HEAD /api/gemini` đều không yêu cầu authentication.

Bạn có thể kiểm tra kết nối bằng lệnh:

```bash
curl -I https://api.avis.xyz/api/openai

```

Nếu request thành công, điều đó cho thấy kết nối mạng, proxy (nếu có) và endpoint API đều đang hoạt động bình thường.

## Bước 2: Thiết lập tài khoản

Quy trình onboarding của AVIS bao gồm tạo tài khoản, xác minh danh tính (eKYC), cấu hình tài khoản, tạo API key và nạp tiền. Bạn có thể tham khảo [hướng dẫn Get Started](https://docs.avis.xyz/guide/get-started?ref=blog.avis.xyz) để thực hiện từng bước.

Trước khi bắt đầu, có hai điểm quan trọng cần lưu ý.

**AVIS sử dụng cơ chế thanh toán trả trước (prepaid).** Bạn nạp tiền vào tài khoản trước, sau đó chi phí sử dụng API sẽ được khấu trừ dần từ số dư. AVIS hỗ trợ thanh toán qua MoMo và VNPAY; số tiền thanh toán đã bao gồm 10% VAT. Chi tiết được trình bày trong [hướng dẫn nạp tiền](https://docs.avis.xyz/guide/get-started/avis-topup?ref=blog.avis.xyz).

Mô hình trả trước đặc biệt phù hợp với giai đoạn thử nghiệm, vì mức chi tiêu tối đa được giới hạn trong phạm vi số dư bạn đã nạp.

**Nên thiết lập hạn mức chi tiêu ngay khi tạo API key.** Theo [hướng dẫn API key](https://docs.avis.xyz/guide/get-started/avis-api-key?ref=blog.avis.xyz), bạn có thể thiết lập giới hạn chi tiêu theo ngày, tuần, tháng và tổng hạn mức cho từng key.

Đối với API key đầu tiên, nên đặt hạn mức ngày ở mức thấp. Điều này giúp hạn chế rủi ro phát sinh chi phí ngoài dự kiến, chẳng hạn khi một đoạn code vô tình chạy liên tục trong thời gian dài.

## Bước 3: Chọn model

Không nên cố định model ID bằng cách sao chép từ một bài viết hoặc tài liệu cũ. Danh mục model có thể được cập nhật, và một model ID không còn tồn tại có thể khiến request trả về lỗi `400`.

Bạn nên lấy danh sách model trực tiếp từ API:

```bash
curl https://api.avis.xyz/api/openai/v1/models -H "x-api-key: $AVIS_API_KEY"

```

Request này trả về danh sách model hiện có. Bạn có thể tham khảo thêm [endpoint danh sách model](https://docs.avis.xyz/api-reference/endpoints/model-list?ref=blog.avis.xyz).

Từ response, chọn một model ID và sử dụng ID đó trong request tiếp theo.

Đối với lần gọi API đầu tiên, nên lựa chọn một model text có chi phí thấp. Mục tiêu ở giai đoạn này là xác nhận toàn bộ quy trình hoạt động chính xác, thay vì tối ưu chất lượng đầu ra.

## Bước 4: Thực hiện lệnh gọi API

Base URL của AVIS là:

```
https://api.avis.xyz/api/openai/v1

```

API key được truyền thông qua header `x-api-key`. Header này được sử dụng thống nhất trên cả ba API surface.

**curl**

```bash
curl https://api.avis.xyz/api/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-api-key: $AVIS_API_KEY" \
  -d '{
    "model": "MODEL_ID_FROM_STEP_3",
    "messages": [{"role": "user", "content": "Say hello in five words."}]
  }'

```

**Python**

Nếu sử dụng Python, bạn có thể dùng package `openai` chính thức và cấu hình `base_url` trỏ tới AVIS:

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["AVIS_API_KEY"],
    base_url="https://api.avis.xyz/api/openai/v1",
)

response = client.chat.completions.create(
    model="MODEL_ID_FROM_STEP_3",
    messages=[{"role": "user", "content": "Say hello in five words."}],
)

print(response.choices[0].message.content)

```

**TypeScript**

```typescript
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.AVIS_API_KEY,
  baseURL: 'https://api.avis.xyz/api/openai/v1',
})

const response = await client.chat.completions.create({
  model: 'MODEL_ID_FROM_STEP_3',
  messages: [{ role: 'user', content: 'Say hello in five words.' }],
})

console.log(response.choices[0].message.content)

```

Trong cả hai ví dụ, API key được đọc từ biến môi trường thay vì được ghi trực tiếp trong mã nguồn. Đây là cách nên áp dụng ngay từ lần tích hợp đầu tiên.

API key cần được bảo vệ tương tự mật khẩu. Không nên đưa key vào mã nguồn phía client, repository hoặc ảnh chụp màn hình. [Hướng dẫn API key](https://docs.avis.xyz/guide/get-started/avis-api-key?ref=blog.avis.xyz) cũng khuyến nghị sử dụng key riêng cho từng ứng dụng hoặc môi trường. Khi một key bị lộ, bạn có thể thu hồi riêng key đó mà không ảnh hưởng đến các integration khác.

Nếu phát hiện hoặc nghi ngờ API key đã bị lộ, nên thu hồi và tạo key mới ngay lập tức thay vì tiếp tục sử dụng.

### Tại sao có thể sử dụng OpenAI SDK để gọi AVIS?

Ví dụ Python và TypeScript trên sử dụng SDK của OpenAI để gọi một API provider khác. Điều này khả thi nhờ tính [OpenAI-compatible API](https://docs.avis.xyz/api-reference/introduction/openai-compatibility?ref=blog.avis.xyz) của AVIS.

API này tuân theo cấu trúc request và response tương thích với SDK của OpenAI. Do đó, với một integration OpenAI hiện có, bạn có thể chuyển sang AVIS bằng cách thay đổi `baseURL` và API key mà không cần thay đổi đáng kể phần logic còn lại.

Nội dung được model sinh ra nằm tại:

```
choices[0].message.content

```

Response được thiết kế theo cấu trúc lồng nhau vì ngoài nội dung, nó còn chứa các thông tin khác như lý do kết thúc (`finish_reason`), lượng token đã sử dụng và khả năng trả về nhiều lựa chọn.

## Bước 5: Kiểm tra chi phí

Một request đơn giản thường chỉ phát sinh chi phí rất nhỏ. Tuy nhiên, việc kiểm tra số dư ngay từ lần gọi đầu tiên là một thói quen tốt, đặc biệt khi bắt đầu xây dựng ứng dụng sử dụng AI API.

Bạn có thể kiểm tra số dư bằng:

```bash
curl https://api.avis.xyz/api/compat/v1/balance \
  -H "x-api-key: $AVIS_API_KEY"

```

Bên cạnh số dư, [các endpoint theo dõi usage](https://docs.avis.xyz/api-reference/introduction/use?ref=blog.avis.xyz) cung cấp endpoint `/usage`, trong đó ghi nhận thông tin của từng lần sinh nội dung, bao gồm model, modality và `usdCost`.

Những dữ liệu này sẽ hữu ích khi bạn cần theo dõi chi phí của từng tính năng hoặc đánh giá hiệu quả sử dụng model trong ứng dụng.

## Khi API không hoạt động

Bốn mã lỗi dưới đây bao phủ phần lớn các vấn đề có thể gặp trong lần gọi API đầu tiên:

| Mã lỗi | Ý nghĩa                                                                               | Cách xử lý                                            |
| ------ | ------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| 401    | Thông tin xác thực không hợp lệ, key không tồn tại, đã bị thu hồi hoặc bị vô hiệu hóa | Kiểm tra header và đảm bảo API key được truyền đầy đủ |
| 403    | Số dư bằng 0 hoặc âm, hoặc tài khoản đã vượt giới hạn số lượng key                    | Kiểm tra số dư hoặc số lượng key                      |
| 400    | Request không hợp lệ hoặc model không tồn tại                                         | Kiểm tra request và model ID thông qua /models        |
| 429    | Đã đạt giới hạn chi tiêu được cấu hình cho key                                        | Điều chỉnh hạn mức hoặc chờ đến kỳ tiếp theo          |

Một trong những điểm dễ gây nhầm lẫn nhất là `401` và `403`.

Theo [tài liệu xác thực](https://docs.avis.xyz/api-reference/introduction/authentication?ref=blog.avis.xyz), một API key hợp lệ nhưng đã hết số dư sẽ trả về `403`, không phải `401`.

Do đó, nếu nhận được `403`, bạn nên kiểm tra số dư trước khi tạo API key mới.

AVIS cũng hỗ trợ phương thức xác thực:

```
Authorization: Bearer <key>

```

Phương thức này hữu ích với các công cụ chỉ hỗ trợ bearer token. Tuy nhiên, nếu gửi đồng thời `x-api-key` và `Authorization` với hai giá trị khác nhau, `x-api-key` sẽ được ưu tiên.

Nếu response lỗi có cấu trúc khác nhau, điều này cũng có thể là hành vi bình thường. Theo [tài liệu tham chiếu lỗi](https://docs.avis.xyz/api-reference/introduction/errors?ref=blog.avis.xyz), những lỗi xảy ra trước khi request được chuyển tới model provider sẽ sử dụng một format thống nhất. Trong khi đó, lỗi do chính provider trả về có thể được giữ nguyên theo format của provider đó.

## Bạn có thể thử gì tiếp theo?

Sau khi request đầu tiên hoạt động, có ba thử nghiệm đơn giản bạn có thể thực hiện.

1. **Stream response.** Thêm `"stream": true` vào request để nhận kết quả theo từng phần thay vì chờ toàn bộ nội dung được sinh xong. Đây là cơ chế thường được sử dụng để cải thiện cảm nhận về tốc độ phản hồi trong giao diện chat. Xem thêm [tài liệu về streaming](https://docs.avis.xyz/api-reference/introduction/streaming?ref=blog.avis.xyz).
2. **Thay đổi model.** Chọn một model ID khác từ `/models` và thay vào trường `model`. Các thành phần còn lại của request có thể giữ nguyên. Đây là cách đơn giản để bắt đầu so sánh các model.
3. **Thử tạo ảnh.** Sử dụng endpoint `POST /images/generations` với cùng base URL và API key. Bạn chỉ cần thay đổi endpoint và request body theo API tương ứng.

Video có quy trình khác biệt hơn. Đây là một tác vụ bất đồng bộ: bạn gửi một job, sau đó polling để kiểm tra kết quả thay vì chờ kết quả trực tiếp trong response ban đầu.

## Câu hỏi thường gặp

**Tôi có phải trả tiền trước khi thử API không?**

Để thực hiện một lần sinh nội dung, bạn cần có số dư vì AVIS sử dụng mô hình thanh toán trả trước. Tuy nhiên, bạn có thể kiểm tra khả năng kết nối hoàn toàn miễn phí thông qua các `HEAD` probe mà không cần API key hoặc số dư.

**Tôi có thể sử dụng OpenAI SDK để gọi AVIS không?**

Có. AVIS cung cấp API tương thích với OpenAI, vì vậy SDK của OpenAI có thể được sử dụng mà không cần thay đổi đáng kể. Trong trường hợp cơ bản, bạn chỉ cần thay đổi base URL và API key.

**Tôi đã mất API key. Tôi có thể lấy lại không?**

API key được hiển thị khi tạo và có thể được quản lý từ trang API Keys. Nếu key có khả năng đã bị lộ, nên thu hồi key đó và tạo key mới thay vì tiếp tục sử dụng.

**Tại sao nội dung nằm tại `choices[0].message.content`?**

Response không chỉ chứa nội dung được sinh ra mà còn bao gồm các thông tin như token usage, finish reason và các lựa chọn khác. Vì vậy, nội dung được đặt bên trong cấu trúc `choices` và `message`.

**Tôi nên bắt đầu với model nào?**

Nên bắt đầu bằng một model text có chi phí thấp. Mục tiêu của lần gọi đầu tiên là xác nhận integration hoạt động chính xác. Để đảm bảo sử dụng đúng model hiện tại, hãy lấy danh sách trực tiếp từ `/models` thay vì sử dụng một model ID được sao chép từ tài liệu cũ.

## Tổng kết

Để thực hiện lệnh gọi API AI đầu tiên, bạn cần ba thành phần chính: API key, base URL và model ID, sau đó gửi một HTTP POST.

Quy trình cơ bản gồm:

1. Kiểm tra kết nối bằng probe miễn phí.
2. Tạo tài khoản, tạo API key và thiết lập hạn mức chi tiêu.
3. Lấy model ID hiện tại từ `/models`.
4. Thực hiện request đầu tiên.
5. Kiểm tra số dư và usage.

Nếu gặp lỗi, hãy đặc biệt lưu ý sự khác biệt giữa `401` và `403`: `401` thường liên quan đến xác thực, trong khi `403` có thể xảy ra khi tài khoản đã hết số dư.

Sau khi request đầu tiên hoạt động, [AVIS](https://www.avis.xyz/gateway?ref=blog.avis.xyz) cho phép bạn tiếp tục thử nghiệm với hơn 300 model cho text, ảnh, video và audio thông qua cùng một key và base URL. Vì vậy, việc thử nghiệm một model mới về cơ bản chỉ yêu cầu thay đổi model ID, thay vì phải xây dựng một integration hoàn toàn mới.

*Cập nhật lần cuối: Tháng 8 năm 2026*