Quickstart — Hello World trong 5 phút
Hướng dẫn này đưa bạn từ con số 0 đến lệnh gọi API đầu tiên với Zeni Cloud. Không cần cài đặt phức tạp, chỉ cần một trình duyệt và terminal có sẵn curl.
curl; Windows 10 trở lên cũng đã tích hợp.Bước 1 — Đăng ký tài khoản (30 giây)
Tạo tài khoản miễn phí
Truy cập https://zenicloud.io/signup. Bạn có thể đăng ký bằng email hoặc đăng nhập nhanh qua Google. Free tier không yêu cầu thẻ tín dụng và không có giới hạn thời gian.
Sau khi xác nhận email, bạn sẽ được đưa thẳng vào dashboard.
Bước 2 — Lấy API token
Tạo Personal Access Token
Trong dashboard, mở menu bên trái và đi tới:
Settings → API Tokens → + New Token
Điền thông tin:
- Name — đặt là
My First Token - Scope — chọn
fullđể có quyền với tất cả lớp - Expiry — mặc định 90 ngày
Sau khi nhấn Create, hệ thống sẽ hiển thị token một lần duy nhất, dạng:
tokenzeni_pat_3a8f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a
Bước 3 — Export token vào terminal
Trên Mac/Linux:
bashexport ZENI_TOKEN="zeni_pat_3a8f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a"
Trên Windows PowerShell:
powershell$env:ZENI_TOKEN = "zeni_pat_3a8f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a"
Bước 4 — Gọi API đầu tiên
Test với curl
Gửi câu hỏi đầu tiên đến ZeniRouter — engine định tuyến AI thông minh:
bashcurl -X POST "https://zenicloud.io/api/v1/router/complete?ws=my_workspace" \
-H "Authorization: Bearer $ZENI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "Xin chào Zeni!"}
],
"task_type": "qa_simple"
}'
Sau khoảng 1 giây, bạn sẽ nhận được phản hồi như sau:
json{
"text": "Xin chào! Em là AI từ Zeni Cloud, sẵn sàng hỗ trợ bạn. Bạn cần em giúp việc gì hôm nay?",
"routing": {
"primary_model": "gemini-3-1-flash",
"tier": "fast",
"actual_cost_usd": 0.0001
},
"usage": {
"input_tokens": 12,
"output_tokens": 45,
"total_tokens": 57
},
"cache_hit": false,
"latency_ms": 1234
}
Bước 5 — Hiểu response
ZeniRouter trả về 4 nhóm thông tin chính:
- text — câu trả lời do AI sinh ra
- routing — model nào đã được chọn, tier và chi phí thực tế (USD)
- usage — số token input/output để bạn theo dõi
- cache_hit — nếu là
true, request đã được trả lời từ cache (rẻ và nhanh hơn)
task_type chính xác, hệ thống sẽ định tuyến tối ưu theo chiến lược 80 phần trăm Flash, 15 phần trăm Sonnet, 5 phần trăm Opus — tiết kiệm khoảng 70 phần trăm so với gọi trực tiếp Anthropic.Bước 6 — Tạo app đầu tiên
Bây giờ thử gọi API từ Python để hiểu cách tích hợp vào ứng dụng thực tế:
pythonimport os
import requests
ZENI = "https://zenicloud.io/api/v1"
TOKEN = os.environ["ZENI_TOKEN"]
def chat(question: str) -> str:
r = requests.post(
f"{ZENI}/router/complete?ws=my_workspace",
headers={"Authorization": f"Bearer {TOKEN}"},
json={
"messages": [{"role": "user", "content": question}],
"task_type": "qa_simple",
},
timeout=30,
)
r.raise_for_status()
return r.json()["text"]
if __name__ == "__main__":
print(chat("Tóm tắt 50 chữ về Hà Nội."))
print(chat("Việt Nam có bao nhiêu tỉnh thành?"))
Lưu file thành hello_zeni.py rồi chạy:
bashpython hello_zeni.py
Bước tiếp theo
Bạn đã hoàn thành Hello World với Zeni Cloud. Hãy chọn một trong các hướng sau để khám phá tiếp: