> 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/tai-lieu-api/introduction/use.md). # Mức sử dụng ### Endpoints | Method | Path | Mô tả | | ------ | -------------------------------------------------- | ------------------------------------------------------------------------------------ | | GET | `/api/compat/v1/usage` | Liệt kê các bản ghi generation từ bảng `generations` | | GET | `/api/compat/v1/balance` | Lấy số dư credit hiện tại của người dùng đã xác thực | | GET | `/api/compat/v1/api-key` | Tra cứu tên, trạng thái và giới hạn chi tiêu của API key đang gọi | | POST | `/api/v1/image/estimate` | Xem trước `usdCost` của một request tạo hình ảnh trước khi gửi | | POST | `/api/v1/video/estimate` | Xem trước `usdCost` của một request tạo video trước khi gửi | | POST | `/api/v1/audio/text-to-speech/estimate` | Xem trước `usdCost` của một request Text-to-Speech trước khi gửi | | POST | `/api/v1/audio/generation-with-reference/estimate` | Xem trước `usdCost` của một request âm thanh Generation-With-Reference trước khi gửi | Xác thực: `Authorization: Bearer ` hoặc `x-api-key`. Cả bốn endpoint `estimate` đều thuộc API gốc (`/api/v1`), không thuộc giao diện tương thích (`/api/compat/v1`). Xem mục Ước tính chi phí trước khi tạo bên dưới. ### 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[].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 theo định dạng tương thích. #### Ví dụ response ```json { "results": [ { "id": "6a584d837deb305999dda675", "userId": "6a38e2554301a757f3721c0c", "modality": "image", "model": "seedream-4-0", "status": "succeeded", "usage": { "totalTokens": 14400, "generatedImages": 1, "outputTokens": 14400 }, "usdCost": 0.036, "durationMs": 6256, "createdAt": "2026-07-16T03:18:27.208Z" } ], "total": 1, "offset": 0, "limit": 20 } ``` ### Cách tính token và credit #### Token (`usage`) Các trường `usage` được chuẩn hóa từ mức sử dụng thực tế trong quá trình chạy và lưu trong từng bản ghi generation. * Văn bản: thường bao gồm `promptTokens`, `completionTokens` và `totalTokens`. * Hình ảnh: thường bao gồm `generatedImages`, `outputTokens` và đôi khi có `totalTokens`. * Video: thường bao gồm `completionTokens` / `totalTokens` khi nhà cung cấp có cung cấp. Các trường token thay đổi tùy mô hình và loại request; do đó, không phải bản ghi nào cũng có đầy đủ các key. #### Credit (`usdCost`) `usdCost` là số tiền cuối cùng được tính cho bản ghi generation đó. Khi quyết toán, backend tính số tiền cuối cùng phải trả theo chính sách giá áp dụng cho tài khoản của bạn. Tóm tắt công thức: ``` usdCost = final billable amount for this generation ``` Trong bản ghi sử dụng, `usdCost` thể hiện số tiền đã trừ cho request đó. ### Ước tính chi phí trước khi tạo Trước khi gửi request tạo hình ảnh, video hoặc âm thanh, bạn có thể ước tính chi phí của request đó bằng endpoint estimate tương ứng trên API gốc (`/api/v1`, không phải `/api/compat/v1`). Chi phí thực tế sẽ được ghi trong `usdCost` khi xem `GET /api/compat/v1/usage`. Request ước tính không trừ credit và không lưu dữ liệu. | Loại dữ liệu | Endpoint ước tính | Body của request | | ------------------------------------ | ------------------------------------------------------- | ---------------------------------------------------- | | Hình ảnh | `POST /api/v1/image/estimate` | Giống `POST /api/v1/image/generations` | | Video | `POST /api/v1/video/estimate` | Giống `POST /api/v1/video/generations` | | Âm thanh (Text-to-Speech) | `POST /api/v1/audio/text-to-speech/estimate` | Giống `POST /api/v1/audio/text-to-speech` | | Âm thanh (Generation With Reference) | `POST /api/v1/audio/generation-with-reference/estimate` | Giống `POST /api/v1/audio/generation-with-reference` | Mỗi endpoint ước tính nhận cùng body request với endpoint tạo nội dung tương ứng và trả về cấu trúc thống nhất `{ estimatedUserCost, currency }`, được bọc trong response chuẩn. `estimatedUserCost` dùng cùng đơn vị với `usdCost` trong các bản ghi sử dụng ở trên. * **Hình ảnh và âm thanh Text-to-Speech:** ước tính chính xác và bằng số tiền được quyết toán trong `usdCost`, vì request đã cho biết đơn vị tính phí (số ảnh hoặc số ký tự). * **Video và âm thanh Generation-With-Reference:** ước tính chỉ mang tính tham khảo. Hai loại này tính phí theo thời lượng đầu ra, thông tin chỉ được nhà cung cấp báo cáo sau khi tạo xong; vì vậy, `usdCost` cuối cùng có thể khác ước tính. #### Hình ảnh Xem [Tạo hình ảnh – Ước tính chi phí](https://docs.avis.net/api-reference/endpoints/image-generation#estimate-cost) để biết chi tiết request và response. ``` POST /api/v1/image/estimate ``` ```json { "model": "seedream-4-0", "content": [ { "type": "text", "text": "Create two clean product mockup images on a neutral background." } ], "size": "1024x1024", "numberOfImages": 2, "watermark": false } ``` ```json { "data": { "estimatedUserCost": 0.12, "currency": "USD" }, "success": true, "status": 200 } ``` #### Video Xem [Tạo video – Ước tính chi phí](https://docs.avis.net/api-reference/endpoints/video-generation#estimate-cost) để biết chi tiết request và response. ``` POST /api/v1/video/estimate ``` ```json { "model": "wan-2-6", "content": [ { "type": "text", "text": "Smooth interpolation between the two frames" }, { "type": "imageUrl", "url": "https://example.com/first.jpeg", "role": "firstFrame" }, { "type": "imageUrl", "url": "https://example.com/last.jpeg", "role": "lastFrame" } ], "duration": 5, "resolution": "720p", "ratio": "16:9", "generateAudio": false } ``` ```json { "data": { "estimatedUserCost": 0.51, "currency": "USD" }, "success": true, "status": 200 } ``` #### Âm thanh — Text-to-Speech Xem [Tạo âm thanh – Ước tính chi phí – Text-to-Speech](https://docs.avis.net/api-reference/endpoints/audio-generation#text-to-speech-1) để biết chi tiết request và response. ``` POST /api/v1/audio/text-to-speech/estimate ``` ```json { "voiceType": "en_female_dacey_uranus_bigtts", "text": "Hello, welcome to our platform. We are glad to have you here." } ``` ```json { "data": { "estimatedUserCost": 0.002, "currency": "USD" }, "success": true, "status": 200 } ``` #### Âm thanh — Generation With Reference Xem [Tạo âm thanh – Ước tính chi phí – Generation With Reference](https://docs.avis.net/api-reference/endpoints/audio-generation#generation-with-reference-1) để biết chi tiết request và response. ``` POST /api/v1/audio/generation-with-reference/estimate ``` ```json { "model": "seed-audio-1.0-multilingual", "textPrompt": "A warm audiobook narrator reading: The sun was setting over the mountain ridge." } ``` ```json { "data": { "estimatedUserCost": 0.015, "currency": "USD" }, "success": true, "status": 200 } ``` ### GET /api/compat/v1/balance Cấu trúc response: | Trường | Kiểu | | --------------- | -------- | | `creditBalance` | `number` | Ví dụ response: ```json { "creditBalance": 12.345 } ``` ### GET /api/compat/v1/api-key Trả về tên, trạng thái và các giới hạn chi tiêu đã cấu hình (ngày/tuần/tháng/tổng) của API key dùng để gọi endpoint. **Xác thực: chỉ chấp nhận `x-api-key`.** Endpoint trả thông tin về *chính key dùng để xác thực request*. Vì vậy, nếu chỉ xác thực bằng JWT mà không gửi key, request sẽ nhận `403`. Response chỉ chứa thông tin của key, không bao gồm số dư credit của tài khoản sở hữu key; người giữ key có thể không phải là chủ tài khoản. Dùng `GET /api/compat/v1/balance` để xem số dư tài khoản. Cấu trúc response: | Trường | Kiểu | Ghi chú | | --------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | `string` | Tên hiển thị của key. | | `isActive` | `boolean` | Luôn là `true` khi lệnh gọi này thành công — key bị vô hiệu hóa/thu hồi sẽ bị lỗi xác thực trước khi tới endpoint này. | | `daily` | `object \| undefined` | Chỉ có khi đã cấu hình mức trần theo ngày. | | `weekly` | `object \| undefined` | Chỉ có khi đã cấu hình mức trần theo tuần. | | `monthly` | `object \| undefined` | Chỉ có khi đã cấu hình mức trần theo tháng. | | `total` | `object \| undefined` | Chỉ có khi đã cấu hình mức trần trọn đời. | | `daily.limit` / `.spent` / `.remaining` | `number` | Mức trần, số đã chi trong chu kỳ hiện tại và hạn mức còn lại — tất cả tính bằng credit. `remaining` được giới hạn ở `0`, không bao giờ âm. | Mỗi trường giới hạn (`daily`/`weekly`/`monthly`/`total`) đều có cấu trúc `{ limit, spent, remaining }`. Nếu key không có giới hạn chi tiêu nào được cấu hình, cả bốn trường này sẽ không xuất hiện. #### Ví dụ response ```json { "name": "my-production-key", "isActive": true, "daily": { "limit": 100, "spent": 40, "remaining": 60 }, "monthly": { "limit": 2000, "spent": 500, "remaining": 1500 } } ``` ### Tham khảo: `usage` theo loại dữ liệu (từ `generations`) Trong các bản ghi hiện tại, cấu trúc `usage` thay đổi 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 cụ thể trong `usage` có thể thay đổi tùy mô hình và loại request. --- # 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/tai-lieu-api/introduction/use.md?ask=&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.