API AI chuẩn OpenAI, thanh toán bằng VND có hoá đơn VAT

AI gateway của ZoCloud là một endpoint chuẩn OpenAI cho nhiều model, trả tiền theo token bằng ví VND và có hoá đơn VAT. Bạn giữ nguyên SDK OpenAI đang dùng, chỉ đổi base_url sang https://api.zocloud.io/v1/ai và dùng key của ZoCloud.

Cách này giải quyết hai việc thường gây khó cho đội ở Việt Nam: không cần thẻ quốc tế để trả tiền cho từng nhà cung cấp, và chi phí AI nằm chung một hoá đơn với hosting, tên miền, e-mail.

Thông số chính

Thông số	Giá trị
Base URL	`https://api.zocloud.io/v1/ai`
Key	dạng `zcai_…`, tạo ở mục AI của tổ chức
Endpoint	`POST /chat/completions` (có streaming), `POST /embeddings`, `GET /models`
Thanh toán	Theo token, trừ ví VND khoảng mỗi phút

Danh sách model do ZoCloud mở. Nếu mục AI ghi "Chưa có model nào được mở.", gateway chưa có model để gọi. Tên model chính xác lấy từ Bảng giá trên portal hoặc GET https://api.zocloud.io/v1/ai/models.

Vì theo chuẩn OpenAI, gateway dùng được với SDK Python, JavaScript, LangChain, n8n và các công cụ hỗ trợ OpenAI khác.

Tạo key

Vào mục AI → Tạo key.
Nhập Tên (ứng dụng dùng key), và nếu muốn, Hạn mức mỗi tháng (VND). Để trống là không giới hạn.
Bấm Tạo. Sao chép key ngay: ZoCloud không hiển thị lại.
Đặt key vào biến môi trường của service (ví dụ OPENAI_API_KEY), không ghi vào code.

Thu hồi một key thì ứng dụng dùng key đó ngừng gọi được ngay, nên hãy dùng mỗi ứng dụng một key.

Ví dụ Python

from openai import OpenAI

client = OpenAI(base_url="https://api.zocloud.io/v1/ai", api_key="zcai_...")
r = client.chat.completions.create(
    model="TÊN_MODEL",
    messages=[{"role": "user", "content": "Xin chào"}],
)
print(r.choices[0].message.content)

Trong code thật, đọc key từ biến môi trường thay vì viết thẳng vào code.

Ví dụ Node.js (streaming)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.zocloud.io/v1/ai",
  apiKey: process.env.OPENAI_API_KEY, // zcai_...
});

const stream = await client.chat.completions.create({
  model: "TÊN_MODEL",
  messages: [{ role: "user", content: "Xin chào" }],
  stream: true,
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");

Streaming giúp chatbot hiện chữ ngay khi model trả về, thay vì chờ cả câu trả lời.

Embeddings và curl

Cho tìm kiếm ngữ nghĩa hoặc RAG:

e = client.embeddings.create(model="TÊN_MODEL_EMBEDDING", input=["văn bản cần nhúng"])

Kiểm tra nhanh từ terminal:

curl https://api.zocloud.io/v1/ai/chat/completions \
  -H "Authorization: Bearer zcai_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"TÊN_MODEL","messages":[{"role":"user","content":"Xin chào"}]}'

Thay TÊN_MODEL bằng tên trong bảng giá.

Giá và cách tính tiền

Mục AI → Bảng giá (gồm VAT): mỗi model có giá Vào (token gửi đi) và Ra (token nhận về), tính cho mỗi 1 triệu token, bằng VND, đã gồm VAT. Giá có thể thay đổi theo giá của nhà cung cấp, nên hãy xem bảng giá trên portal thay vì ghi cứng vào kế hoạch chi phí.

Mỗi request được ghi lại; ZoCloud gộp và trừ ví khoảng mỗi phút. Cuối tháng, chi phí AI được gộp thành một dòng "Sử dụng AI gateway tháng …" trên bảng kê và hoá đơn (xem hoá đơn điện tử cho dịch vụ cloud).

Giới hạn và mã lỗi

Tình huống	Kết quả
Ví xuống dưới mức tối thiểu	HTTP 402; nạp tiền để gọi tiếp
Key vượt Hạn mức mỗi tháng	HTTP 429
Gọi model không có	Lỗi `ai.model_not_found`

Ứng dụng nên xử lý riêng 402 và 429: hiện thông báo thân thiện cho người dùng và báo cho đội vận hành, thay vì thử lại liên tục.

Kiểm soát chi phí

Mỗi ứng dụng một key: biết rõ ứng dụng nào tốn bao nhiêu, thu hồi riêng khi cần.
Đặt hạn mức tháng cho mỗi key, nhất là key dùng trong workflow tự động hay bản thử nghiệm.
Theo dõi sử dụng: danh sách Key hiện lần dùng gần nhất và chi phí "Tháng này …"; mục Sử dụng 30 ngày chia theo ngày và model, với số request, token vào/ra và chi phí.
Chọn model vừa đủ: việc phân loại, trích xuất đơn giản thường không cần model lớn nhất. So sánh giá Vào/Ra trong bảng giá.
Rút gọn prompt: token gửi đi cũng tính tiền; cắt bớt lịch sử hội thoại dài và văn bản không cần thiết.

Dùng từ AI agent và n8n

Qua zo MCP, agent như Claude hay Cursor có các công cụ ai_models (model và giá), create_ai_key (tạo key, có thể kèm hạn mức) và ai_usage. Key chỉ hiện một lần, nên agent nên đặt ngay vào biến môi trường của service. Xem vibe coding và deploy từ Cursor, Claude.

Với n8n tự host, tạo credential OpenAI trỏ về gateway như hướng dẫn ở bài tự host n8n.

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

Đổi code từ OpenAI sang AI gateway của ZoCloud có khó không? Không. Gateway theo chuẩn OpenAI nên bạn giữ nguyên SDK, chỉ đổi base_url thành https://api.zocloud.io/v1/ai, dùng key zcai_ của ZoCloud và tên model trong bảng giá trên portal.

Giá gọi AI tính thế nào? Mỗi model có giá token vào và token ra cho mỗi 1 triệu token, bằng VND, đã gồm VAT, hiện ở mục AI trên portal. Giá có thể đổi theo nhà cung cấp, nên luôn xem bảng giá trước khi dùng.

Làm sao tránh hoá đơn AI tăng đột biến? Đặt Hạn mức mỗi tháng (VND) cho từng key; vượt hạn mức thì request bị từ chối với HTTP 429. Dùng mỗi ứng dụng một key để biết ứng dụng nào tốn tiền.

Doanh nghiệp có hoá đơn VAT cho chi phí AI không? Chi phí AI trong tháng được gộp thành một dòng trên bảng kê và hoá đơn tháng. Hoá đơn GTGT điện tử được lập theo thông tin xuất hoá đơn của tổ chức khi tính năng này đã bật.

Bắt đầu

Đăng ký ZoCloud, nạp ví bằng chuyển khoản VietQR hoặc cổng thanh toán đang bật, rồi tạo key đầu tiên. Tài liệu: AI gateway, Thanh toán, zo CLI và MCP. Đang chạy backend Python? Xem deploy Python FastAPI, Django.