> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/readme.md).

# Tài liệu AVIS

Bắt đầu xây dựng với các mô hình mở.

<button type="button" class="button primary" data-action="search" data-icon="magnifying-glass">Tìm kiếm...</button>

<a href="/vi/huong-dan/get-started/start-here.md" class="button secondary" data-icon="rocket-launch">Hướng dẫn sử dụng</a><a href="/vi/tai-lieu-api/overview.md" class="button secondary" data-icon="key">Tài liệu API</a><a href="/vi/tich-hop/overview.md" class="button secondary" data-icon="code">Tích hợp</a>

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>KHÔNG GIAN SÁNG TẠO CHUYÊN NGHIỆP</strong></td><td>Tạo nên những tác phẩm táo bạo như ý tưởng và mang dấu ấn riêng như tầm nhìn của bạn với các công cụ AI.</td><td><a href="https://www.avis.net/">https://www.avis.net/</a></td><td><a href="https://1381001042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBqtOszkBUadA4v68IeIc%2Fuploads%2Fwa51Ky7qlqci8aVd12oU%2FHome-2.png?alt=media&amp;token=d64177e9-8ba6-437e-a2d4-762e6ddde994">Home-2.png</a></td></tr><tr><td><strong>MỘT KẾT NỐI TỚI TOÀN BỘ THẾ GIỚI AI</strong></td><td>Truy cập các mô hình AI mới nhất, hạ tầng bảo mật và công cụ kiểm soát đơn giản — tất cả tại một nơi.</td><td><a href="https://www.avis.net/gateway">https://www.avis.net/gateway</a></td><td><a href="https://1381001042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBqtOszkBUadA4v68IeIc%2Fuploads%2FvvN0gtprtkKLJCdM9D2a%2FFrame%201984079626.png?alt=media&amp;token=8b2ff583-741c-47f0-9d69-4dabdd3ce3c3">Frame 1984079626.png</a></td></tr></tbody></table>

{% columns %}
{% column width="50%" %}

## Bắt đầu chỉ trong vài phút

Thực hiện lệnh gọi API đầu tiên trong vòng chưa đầy 5 phút.

Hướng dẫn nhanh này trình bày các bước thiết lập cơ bản: tạo tài khoản, tạo API key và gửi request đầu tiên. Cùng một request được minh họa bằng nhiều ngôn ngữ để bạn bắt đầu với ngôn ngữ phù hợp với stack của mình.

{% hint style="info" icon="sparkle" %}
**Tùy chỉnh request đầu tiên của bạn**

Cho biết bạn đang xây dựng gì để AI điều chỉnh hướng dẫn nhanh cho phù hợp.

<button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">Bạn đang xây dựng gì?</button>
{% endhint %}

{% hint style="warning" icon="life-ring" %}
**Cần trợ giúp?**

Tìm cách khắc phục sự cố thường gặp hoặc yêu cầu hỗ trợ.

<details>

<summary>Tôi gặp lỗi 401 Unauthorized</summary>

Kiểm tra API key đã được cung cấp và còn hiệu lực.

Đảm bảo đã thay `YOUR_API_KEY` trong ví dụ bằng API key của bạn.

Kiểm tra header `Authorization` có định dạng `Bearer YOUR_API_KEY`.

</details>

<details>

<summary>Tôi gặp lỗi 400 Bad Request</summary>

Trước tiên, hãy kiểm tra body của request.

Đảm bảo JSON đúng định dạng và có trường `message`.

Đồng thời, kiểm tra request có gửi `Content-Type: application/json`.

</details>

<details>

<summary>Request thành công nhưng kết quả không như mong đợi</summary>

Bắt đầu bằng payload mẫu trước khi thử dữ liệu đầu vào tùy chỉnh.

Kiểm tra trường `status` trong response để biết request mới được đưa vào hàng đợi hay đã xử lý xong.

Nếu thay đổi cấu trúc payload, hãy kiểm tra endpoint có chấp nhận các trường đó hay không.

</details>

<details>

<summary>Ví dụ trên máy của tôi không chạy được</summary>

Kiểm tra runtime và các dependency đã được cài đặt.

Với JavaScript, hãy cài SDK trước khi chạy ví dụ.

Với Python, hãy đảm bảo môi trường đã có thư viện `requests`.

</details>

<button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">Giải thích chuyện gì đang xảy ra...</button>
{% endhint %}

Sau khi gửi request đầu tiên, hãy xem các hướng dẫn thiết lập nâng cao và tài liệu API để tìm hiểu thêm về endpoint và tham số.<br>

<a href="https://www.avis.net/gateway" class="button primary" data-icon="rocket-launch">Bắt đầu</a> <a href="https://docs.avis.net/api-reference/introduction" class="button secondary" data-icon="terminal">Tài liệu API</a>
{% endcolumn %}

{% column width="50%" %}
{% stepper %}
{% step %}

#### Tạo API key

Thiết lập tài khoản, rồi tạo API key để thử nghiệm trên máy và dùng cho tích hợp đầu tiên.

<a href="https://www.avis.net/login" class="button primary">Đăng nhập AVIS Platform</a>
{% endstep %}

{% step %}

### Nạp tiền vào số dư

**Bước 1:** Nhấn nút **Top Up**.

**Bước 2:** Chọn và tuỳ chỉnh phương thức thanh toán.

**Bước 3:** Điền đầy đủ thông tin bắt buộc.

**Bước 4:** Hoàn tất thanh toán.
{% endstep %}

{% step %}

#### Gửi request đầu tiên

Chọn một hướng dẫn API trong bộ tài liệu, thay `YOUR_API_KEY` bằng key của bạn rồi chạy ví dụ.

{% tabs %}
{% tab title="Xác thực" %}
{% code overflow="wrap" %}

```typescript
Tạo API key
Đăng nhập tại avis.net

Vào Settings → API Keys.

Nhấn Create key, đặt tên và lưu ở nơi an toàn — key gốc chỉ hiển thị một lần khi tạo (sau đó có thể xem lại từ cùng trang này).

Mỗi tài khoản có thể bị giới hạn số lượng API key. Tạo vượt quá giới hạn sẽ trả về 403 Forbidden.
```

{% endcode %}
{% endtab %}

{% tab title="Streaming" %}
{% code overflow="wrap" %}

```typescript
## Bật / tắt streaming

| Giao diện | Cách stream | Cách nhận một response JSON duy nhất |
|---|---|---|
| OpenAI (`chat/completions`, `/responses`) | `"stream": true` trong body của request | `"stream": false` (mặc định) |
| OpenAI (`images/generations`) | `"stream": true` — chỉ có hiệu lực khi nhà cung cấp của mô hình được chọn hỗ trợ stream sự kiện hình ảnh; nếu không, request vẫn hoàn tất nhưng trả về dưới dạng một response JSON duy nhất | `"stream": false` (mặc định) |
| OpenAI (`videos`) | Không áp dụng — tạo video luôn là bất đồng bộ (gửi + poll), xem [Tương thích OpenAI](./openai-compatibility.md) | n/a |
| Anthropic (`messages`) | `"stream": true` trong body của request | `"stream": false` (mặc định) |
| Gemini | Gọi `models/{model}:streamGenerateContent` thay vì `models/{model}:generateContent` | Gọi `:generateContent` |

Mọi response dạng stream đều được gửi với `Content-Type: text/event-stream`, `Cache-Control: no-cache, no-transform` và `Connection: keep-alive`.
```

{% endcode %}
{% endtab %}

{% tab title="Usage" %}
{% code overflow="wrap" %}

```md
## Endpoints

| Method | Path | Mô tả |
| --- | --- | --- |
| GET | `/api/compat/v1/usage` | Liệt kê các bản ghi generation từ bảng `generations` |

Xác thực: `Authorization: Bearer <jwt>` hoặc `x-api-key`.

## GET /api/compat/v1/usage

Các trường query:

| Trường | Kiểu | Bắt buộc | Ghi chú |
| --- | --- | --- | --- |
| `offset` | `number` | Không | Mặc định `0` |
| `limit` | `number` | Không | Mặc định `20` |

Cấu trúc response:

| Trường | Kiểu |
| --- | --- |
| `results[]` | Mảng các bản ghi generation |
| `results[].id` | `string` |
| `results[].userId` | `string` |
| `results[].apiKeyId` | `string \| undefined` |
| `results[].modality` | `"text" \| "image" \| "video" \| "audio"` |
| `results[].model` | `string` |
| `results[].status` | `"succeeded" \| "failed" \| "aborted" \| "cancelled"` |
| `results[].request` | `object \| undefined` |
| `results[].usage` | `object \| undefined` |
| `results[].usdCost` | `number \| undefined` |
| `results[].durationMs` | `number \| undefined` |
| `results[].createdAt` | `datetime` |
| `total` | `number` |
| `offset` | `number` |
| `limit` | `number` |

Endpoint này hiện chỉ hỗ trợ phân trang và trả về các bản ghi generation dạng compat.

## Lưu ý về dữ liệu `generations`

Endpoint này trả về một **bản ghi sử dụng rút gọn**, bao gồm payload `request` và `usdCost`.

## Tham khảo: `usage` theo loại dữ liệu (từ `generations`)

Dựa trên các bản ghi thực tế hiện tại, payload `usage` khác nhau tùy theo loại dữ liệu.

### Văn bản

Các trường thường gặp:

| Trường | Kiểu |
| --- | --- |
| `usage.promptTokens` | `number` |
| `usage.completionTokens` | `number` |
| `usage.totalTokens` | `number` |

### Hình ảnh

Các trường thường gặp:

| Trường | Kiểu |
| --- | --- |
| `usage.generatedImages` | `number` |
| `usage.inputTokens` | `number` |
| `usage.outputTokens` | `number` |
| `usage.totalTokens` | `number` |

### Video

Các trường thường gặp:

| Trường | Kiểu |
| --- | --- |
| `usage.completionTokens` | `number` |
| `usage.totalTokens` | `number` |

Các key chính xác trong `usage` có thể khác nhau tùy nhà cung cấp/mô hình.

```

{% endcode %}
{% endtab %}

{% tab title="Lỗi" %}
{% code overflow="wrap" expandable="true" %}

```typescript

400
Bad request — thiếu/sai tham số, mô hình không được hỗ trợ, hoặc mô hình chưa được cấu hình giá
401
Unauthorized — API key bị thiếu, không hợp lệ hoặc không còn hoạt động (xem Xác thực)
403
Forbidden — số dư credit bằng 0 hoặc âm
404
Not found — ví dụ: poll một video job ID không tồn tại
429
Too many requests — đã chạm giới hạn chi tiêu (ngày/tuần/tháng/tổng) do chủ sở hữu API key thiết lập
500
Lỗi máy chủ nội bộ phía Avis
502 / 503
Nhà cung cấp mô hình phía upstream gặp lỗi hoặc không khả dụng
```

{% endcode %}
{% endtab %}

{% tab title="Tương thích OpenAI" %}

### Base URL

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

### Chuyển đổi một ứng dụng hiện có

```typescript
import OpenAI from 'openai'

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

#### `POST /chat/completions`

```typescript
const response = await client.chat.completions.create({
  model: 'openai/gpt-4.1-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
})
console.log(response.choices[0].message.content)
```

#### `POST /images/generations`

```typescript
import { writeFileSync } from 'node:fs'

const response = await client.images.generate({
  model: 'gemini-3-pro-image-preview',
  prompt: 'A simple red apple on a white table, photorealistic',
  n: 1,
  size: '1024x1024',
  response_format: 'b64_json',
})

writeFileSync('output.jpg', Buffer.from(response.data[0].b64_json!, 'base64'))
console.log('Image saved to output.jpg')
```

#### `POST /videos` — job bất đồng bộ

```typescript
import { writeFileSync } from 'node:fs'

const job = await client.videos.create({
  model: 'alibaba/happyhorse-1.1',
  prompt: 'A red apple falling from a tree in slow motion, photorealistic',
})
console.log('Job submitted:', job.id, '| status:', job.status)

let video = job
while (video.status !== 'completed' && video.status !== 'failed') {
  await new Promise((r) => setTimeout(r, 3000))
  video = await client.videos.retrieve(job.id)
  console.log('Status:', video.status)
}

if (video.status !== 'completed') {
  throw new Error(`Video generation failed. Status: ${video.status}`)
}

const content = await client.videos.downloadContent(video.id)
writeFileSync('output.mp4', Buffer.from(await content.arrayBuffer()))
console.log('Video saved to output.mp4 (via downloadContent)')
```

{% endtab %}

{% tab title="Tương thích Anthropic" %}

### Base URL

```
https://api.avis.net/api/anthropic
```

### Chuyển đổi một ứng dụng hiện có

```typescript
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  apiKey: process.env.AVIS_API_KEY,
  baseURL: 'https://api.avis.net/api/anthropic',
})
```

Bạn không cần thay đổi phần nào khác trong tích hợp Anthropic hiện có.

### Endpoints

| Method | Path                         | Streaming | Mô tả                                 |
| ------ | ---------------------------- | --------- | ------------------------------------- |
| `HEAD` | `/api/anthropic`             | —         | Kiểm tra kết nối (không cần xác thực) |
| `GET`  | `/api/anthropic/v1/models`   | —         | Liệt kê các mô hình khả dụng          |
| `POST` | `/api/anthropic/v1/messages` | ✅         | Messages API                          |

Nếu request có header `anthropic-version` hoặc `anthropic-beta`, các header này sẽ được chuyển tiếp đến nhà cung cấp upstream. Xem phần Xác thực.

#### `POST /messages`

```typescript
const response = await client.messages.create({
  model: 'anthropic/claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }],
})
console.log(response.content[0].text)
```

{% endtab %}

{% tab title="Tương thích Gemini" %}

### Base URL

```
https://api.avis.net/api/gemini
```

> SDK `@google/genai` tự động thêm `/v1beta` vào `baseUrl`. Hãy truyền `https://api.avis.net/api/gemini`, **không phải** `.../api/gemini/v1beta`, để tránh lặp đường dẫn.

### Chuyển đổi một ứng dụng hiện có

```typescript
import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({
  apiKey: process.env.AVIS_API_KEY,
  httpOptions: {
    baseUrl: 'https://api.avis.net/api/gemini',
  },
})
```

Model ID có tiền tố `google/`, ví dụ `google/gemini-2.0-flash`.

### Endpoints

| Method | Path                                                      | Streaming | Mô tả                                 |
| ------ | --------------------------------------------------------- | --------- | ------------------------------------- |
| `HEAD` | `/api/gemini`                                             | —         | Kiểm tra kết nối (không cần xác thực) |
| `GET`  | `/api/gemini/v1beta/models`                               | —         | Liệt kê các mô hình khả dụng          |
| `POST` | `/api/gemini/v1beta/models/{model}:generateContent`       | —         | Tạo nội dung                          |
| `POST` | `/api/gemini/v1beta/models/{model}:streamGenerateContent` | ✅         | Tạo nội dung, dạng stream             |

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

```typescript
const response = await ai.models.generateContent({
  model: 'google/gemini-2.0-flash',
  contents: 'Explain quantum entanglement in one sentence.',
})
console.log(response.text)
```

```json
{
  "candidates": [
    {
      "content": { "parts": [{ "text": "Hello! How can I help you today?" }], "role": "model" },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": { "promptTokenCount": 2, "candidatesTokenCount": 10 }
}
```

#### `POST /models/{model}:streamGenerateContent`

```typescript
const stream = await ai.models.generateContentStream({
  model: 'google/gemini-2.0-flash',
  contents: 'Explain quantum entanglement in one sentence.',
})

for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? '')
}
```

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="50%" %}

<figure><img src="https://1381001042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBqtOszkBUadA4v68IeIc%2Fuploads%2Fgit-blob-4f8d7ea9e14db1a768967fd75b746eba4f57175e%2Fphoto_2026-07-20_12-11-46%20(2).jpg?alt=media" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column width="50%" valign="middle" %}

## Tìm hiểu thêm về nền tảng dành cho nhà phát triển

Đọc các hướng dẫn để tìm hiểu cách sử dụng nền tảng dành cho nhà phát triển và tích hợp nền tảng vào stack của bạn.

<a href="https://gitbook-templates.gitbook.io/help-center/" class="button primary" data-icon="book-open">Tích hợp</a> <a href="https://docs.avis.net/api-reference/introduction" class="button secondary" data-icon="book">Tài liệu API</a>
{% endcolumn %}
{% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avis.net/vi/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.