Hướng dẫn toàn diện Zeni Cloud

⚡ Quick Start — 5 phút từ 0 → API call

Đăng ký, tạo API token, gọi AI request đầu tiên — tất cả trong 5 phút. Không cần thẻ tín dụng. 50.000 VND credit miễn phí.

Bước 1: Đăng ký tài khoản

1. Mở zenicloud.io/signup
2. Nhập email công ty + mật khẩu (≥8 ký tự, có hoa/thường/số/ký tự đặc biệt)
3. Tên công ty + Workspace ID (chỉ chữ thường + dấu gạch ngang, ví dụ acme-corp)
4. Click "Tạo tài khoản" — workspace tự tạo + 50K VND credit miễn phí

Bước 2: Tạo API Token

1. Vào Dashboard → tab "API Tokens" (sidebar)
2. Click "+ New Token"
3. Đặt tên (ví dụ My App Production) + chọn scope:
   • full: tất cả tính năng (recommend cho dev)
   • ai: chỉ AI/Router
   • data: chỉ vector/cache/storage
   • automation: chỉ workflow/cron
   • web3: chỉ smart contract
4. Click "Create" → COPY TOKEN NGAY (chỉ hiện 1 lần)

# Token format: zeni_pat_XXXXXXXXXXXXXXXXXXX
# Lưu vào env var an toàn:
export ZENI_TOKEN=zeni_pat_xxx...
export ZENI_WS=acme-corp

Bước 3: API call đầu tiên (gọi AI)

ZeniRouter tự chọn model tối ưu (Claude Haiku 4.5 / GPT / Gemini Flash / Gemma):

# cURL:
curl -X POST https://zenicloud.io/api/v1/router/route?ws=$ZENI_WS \
  -H "Authorization: Bearer $ZENI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role":"user","content":"Xin chào, bạn là ai?"}],
    "max_tokens": 100
  }'

# Python:
import requests, os
r = requests.post(
    f"https://zenicloud.io/api/v1/router/route?ws={os.environ['ZENI_WS']}",
    headers={"Authorization": f"Bearer {os.environ['ZENI_TOKEN']}"},
    json={"messages": [{"role": "user", "content": "Xin chào"}], "max_tokens": 100}
)
print(r.json())

// Node.js:
const r = await fetch(`https://zenicloud.io/api/v1/router/route?ws=${process.env.ZENI_WS}`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.ZENI_TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ messages: [{role:'user',content:'Xin chào'}], max_tokens: 100 })
});
console.log(await r.json());

📚 Khái niệm cốt lõi

Hiểu 5 khái niệm này — biết cách dùng cả nền tảng.

Cấu trúc URL chuẩn

https://zenicloud.io/api/v1/{LAYER}/{RESOURCE}?ws={WORKSPACE_ID}

# Ví dụ:
https://zenicloud.io/api/v1/projects?ws=acme-corp        # L1: list deployments
https://zenicloud.io/api/v1/vector/collections?ws=acme   # L2: vector DB
https://zenicloud.io/api/v1/router/route?ws=acme         # L3: AI router
https://zenicloud.io/api/v1/automation/crons?ws=acme     # L4: cron jobs
https://zenicloud.io/api/v1/api-tokens?ws=acme           # L5: token management
https://zenicloud.io/api/v1/zeni-token/stack             # L6: $ZENI token info

L1 Compute & Hosting

Deploy web/API/worker/agent — auto-scale 0 → triệu request, zero-config TLS, 30s từ push tới live.

Tạo project (deploy app)

POST /api/v1/projects?ws=$WS

{
  "name": "my-api",                    // chỉ chữ thường + dấu gạch (3-48 chars)
  "type": "api",                        // web | api | worker | agent
  "runtime": "container",                // container | node20 | python312 | bun | go121
  "size": "s",                           // xs (256MB) | s (512MB) | m (2GB) | l (4GB)
  "region": "asia-southeast1",           // us-central1 | asia-southeast1 | europe-west1
  "image": "gcr.io/zeni-cloud-core/my-api:v1", // Artifact Registry / Docker Hub library / GCR samples
  "port": 8080,
  "env_vars": { "NODE_ENV": "production", "DB_URL": "..." },
  "secrets": { "API_KEY": "my-secret:latest" }, // from Secret Manager
  "allow_unauthenticated": true,
  "git_ref": "main"
}

Quản lý project

L2 Data Lake & Vector

Postgres, Redis, Object Storage, Vector DB (pgvector) — managed hoàn toàn. RAG pipeline built-in.

Vector DB — Tạo collection + insert

# 1. Tạo collection (768 dims = text-embedding-004)
POST /api/v1/vector/collections?ws=$WS
{ "name": "docs", "dim": 768 }

# 2. Embed + insert văn bản (Zeni tự gọi text-embedding-004)
POST /api/v1/vector/collections/docs/upsert?ws=$WS
{
  "items": [
    {"id":"doc1", "text":"Zeni Cloud là PaaS Việt Nam", "metadata":{"lang":"vi"}}
  ]
}

# 3. Search semantic
POST /api/v1/vector/collections/docs/search?ws=$WS
{ "query": "hosting Việt Nam", "top_k": 5 }

Cache (Redis)

# Set
POST /api/v1/cache?ws=$WS
{ "key": "user:123", "value": {"name":"Tuấn"}, "ttl": 3600 }

# Get
GET /api/v1/cache/user:123?ws=$WS

Vector Premium — Hybrid Search + RAG Pipeline

# Tạo RAG pipeline (lưu config: collection + embedding + LLM + system prompt)
POST /api/v1/vector-premium/rag/pipelines?ws=$WS
{
  "name": "customer-support",
  "collection_id": 1,
  "hybrid_alpha": 0.5,                  // 0=BM25 only, 1=vector only, 0.5=hybrid
  "top_k": 5,
  "rerank_enabled": true,
  "system_prompt": "Bạn là trợ lý...",
  "llm_model": "gemini-2.5-flash"
}

# Query (tự động embed + retrieve + LLM)
POST /api/v1/vector-premium/rag/pipelines/customer-support/query?ws=$WS
{ "question": "Cách deploy app trên Zeni Cloud?" }

L3 AI Engine — ZeniRouter

Smart router truy cập 20+ models top-tier từ 4 nhà cung cấp AI hàng đầu thế giới: Anthropic Claude (Opus 4.7 / Sonnet 4.6), OpenAI (GPT-5 / GPT-4o / o1), Google Gemini (2.5 Pro / 2.5 Flash), AWS Bedrock (Nova). Tự động chọn model phù hợp nhất theo task — tiết kiệm 30-60% chi phí so với gọi trực tiếp.

5 Tier — Auto-route theo task

💰 Pricing minh bạch — Không markup ẩn

Zeni Cloud cộng 15% margin để cover infra + smart routing + multi-provider failover. Toàn bộ raw cost từ Anthropic/OpenAI/Google đều public — anh có thể verify:

⚖️ Vì sao Zeni vẫn rẻ hơn dù +15%? Smart routing tự chọn model RẺ NHẤT đáp ứng task. Khách dùng Gemini Flash cho 80% Q&A đơn giản (rẻ 200x Opus) → tổng chi phí thấp 30-60% so với khách hardcode Sonnet/GPT-4 cho mọi task.

Endpoint chính

POST /api/v1/router/route?ws=$WS
Authorization: Bearer $TOKEN

{
  "messages": [
    {"role": "system", "content": "Bạn là trợ lý..."},
    {"role": "user", "content": "Cho tôi hỏi..."}
  ],
  "max_tokens": 500,
  "temperature": 0.7,
  "model_hint": "flash",            // optional: fast | flash | balanced | premium | reasoning
  "task_type": "qa_simple",         // optional: qa_simple | code | analysis | creative | agent
  "failover": true                 // auto-retry với chain fallback nếu fail
}

Agents — 16 loại agent built-in

# List 16 agent kinds
GET /api/v1/agents/kinds

# Trả về: ['chat','rag','code','sql','support','translation','summarize',
#         'extract','classify','review','planner','writer','researcher',
#         'data_analyst','customer_support','agent_orchestrator']

# Run agent (structured output)
POST /api/v1/agents/{kind}/run-structured?ws=$WS
{
  "input": "Phân tích đoạn văn bản này...",
  "params": { ... }
}

Agents Library — Catalog 50+ template sẵn

# List catalog
GET /api/v1/agents-library/catalog

# Install template (tự copy config + prompt vào workspace)
POST /api/v1/agents-library/catalog/{id}/install?ws=$WS

L4 Automation

Workflows, Crons, Webhooks, Connectors (Slack/Email/SMS/Stripe) — tự động hóa mọi pipeline.

Tạo Cron Job

POST /api/v1/automation/crons?ws=$WS
{
  "name": "daily-report",
  "schedule": "0 8 * * *",           // 8 sáng mỗi ngày (cron expression)
  "timezone": "Asia/Ho_Chi_Minh",
  "http_target": {
    "url": "https://my-api.com/cron/daily",
    "method": "POST",
    "headers": { "X-Cron-Secret": "..." }
  }
}

Tạo Workflow (chain steps)

POST /api/v1/automation/flows?ws=$WS
{
  "name": "new-signup-flow",
  "trigger": { "type": "webhook", "path": "/signup" },
  "steps": [
    { "id":"send_welcome_email", "type":"connector", "connector":"email", "params": { "to":"{{trigger.email}}", "template":"welcome" } },
    { "id":"create_zenipay", "type":"http", "url":"https://...api/zeni-pay/wallet" },
    { "id":"notify_slack", "type":"connector", "connector":"slack", "params": { "channel":"#growth" } }
  ]
}

L5 Identity & Auth

Auth, MFA, OAuth, API Tokens, CMEK, Smart Contract ZeniAccessControl, CAAA (Customer-Approved Admin Access).

Email + Password

# Signup
POST /api/v1/auth/signup
{ "email":"...", "password":"...", "full_name":"...", "company_name":"...", "workspace_id":"acme" }

# Login
POST /api/v1/auth/login
{ "email":"...", "password":"..." }
# → returns { access_token, refresh_token, token_type: "Bearer", expires_in: 3600 }

OAuth (Google / GitHub / Zeni Digital)

Click nút OAuth trên trang login → redirect về Google/GitHub → callback tự exchange token.

GET /api/v1/auth/oauth/google/authorize?return_to=/app
GET /api/v1/auth/oauth/github/authorize?return_to=/app
GET /api/v1/auth/oauth/zenidigital/authorize?return_to=/app

# Check provider availability:
GET /api/v1/auth/oauth/providers
# → returns { providers: [{ name, ready: true|false, ... }] }

MFA (TOTP — Google Authenticator)

# Setup MFA
POST /api/v1/auth/mfa/setup
# → returns { secret, qr_code_url } — scan QR vào Authenticator

# Verify enrollment
POST /api/v1/auth/mfa/verify
{ "code": "123456" }

# Login với MFA enabled
POST /api/v1/auth/mfa/login
{ "email":"...", "password":"...", "code":"123456" }

API Tokens (PAT)

# Tạo token
POST /api/v1/api-tokens?ws=$WS
{ "name":"My App", "scopes":"full", "ttl_days":365 }
# → returns { token: "zeni_pat_xxx" } — chỉ hiện 1 lần!

# Scopes: full | ai | data | automation | web3
# List, revoke, rotate qua /api-tokens/{id}

Customer OAuth (Zalo/Apple/Facebook/Line/Kakao/TikTok/LinkedIn)

Khách của bạn build app → muốn người dùng login bằng Zalo? Bạn cài key Zalo của HỌ trên Zeni Cloud → Zeni làm OAuth middleware:

# 1. Đăng ký app Zalo tại developers.zalo.me
# 2. Lấy App ID + Secret Key
# 3. Add provider vào Zeni:

POST /api/v1/identity/oauth-providers?ws=$WS
{
  "provider": "zalo",
  "display_name": "Đăng nhập Zalo",
  "client_id": "your_zalo_app_id",
  "client_secret": "your_zalo_secret_key",
  "redirect_uri": "https://zenicloud.io/auth/zalo/$WS/callback",
  "app_callback_url": "https://your-app.com/auth/callback"
}

# Endpoint dành cho user app:
GET https://zenicloud.io/auth/zalo/$WS/login
# → redirect về Zalo, callback về app của bạn với access token

L6 Web3 — $ZENI Token + Polygon

Token $ZENI deployed Polygon mainnet, smart contract integration, ZeniBadge SBT, AffiliateCommission.

Endpoints chính

# Token info
GET /api/v1/zeni-token/stack          # Tokenomics, supply, vesting
GET /api/v1/zeni-token/exchange-rate  # 1 ZENI = ? VND
POST /api/v1/zeni-token/quote         # Quote swap ZENI ↔ VND

# Web3 chain
GET /api/v1/web3/chains               # Polygon mainnet info
POST /api/v1/web3/read                # Call contract method (read-only)
POST /api/v1/web3/write               # Send tx (cần wallet signed)

🌐 Edge CDN — Cloudflare integration

CDN global, auto SSL, DDoS protection, WAF rules, Bot Fight Mode.

POST /api/v1/edge/zones?ws=$WS
{ "hostname": "my-app.com", "origin_url": "https://...zenicloud.app" }

GET /api/v1/edge/zones?ws=$WS
POST /api/v1/edge/zones/{id}/verify
POST /api/v1/edge/zones/{id}/routes  # Route rules

💾 Backup & Disaster Recovery

Backup policies, PITR (Point-in-Time Recovery), DR site failover.

# Tạo backup policy
POST /api/v1/backup/policies?ws=$WS
{
  "name": "daily-1am",
  "schedule": "0 1 * * *",
  "retention_days": 30,
  "target": { "type":"postgres", "datasource_id": 1 }
}

# PITR restore (rollback đến giây bất kỳ trong 7 ngày)
POST /api/v1/backup/pitr?ws=$WS
{ "datasource_id": 1, "restore_to": "2026-04-30T15:30:00Z" }

🗺️ Multi-Region & Auto-Scaling

Deploy đa vùng (asia/eu/us), auto-scale theo load, canary release, blue/green deploy.

GET /api/v1/multi-region/regions    # 12 regions available
POST /api/v1/multi-region/projects/{id}/regions
{ "region":"us-central1", "min_instances":1, "max_instances":50 }

POST /api/v1/multi-region/projects/{id}/scaling
{ "cpu_target":60, "concurrency_target":80, "canary_percent":10 }

🤝 White-label Reseller

Bán Zeni Cloud dưới brand của bạn. Custom domain, logo, color scheme. Hoa hồng 30%.

# Apply để trở thành reseller
POST /api/v1/reseller/apply
{ "company":"My Cloud Co", "website":"...", "target_market":"VN/TH/ID" }

# Branding (sau khi approved)
PATCH /api/v1/reseller/brand
{ "name":"My Cloud", "primary_color":"#ff0080", "logo_url":"...", "custom_domain":"cloud.mycompany.com" }

📜 Compliance — SOC2 / GDPR / PCI / ISO 27001

5 framework built-in: SOC2 Type II, GDPR, PCI-DSS, ISO 27001, NIST CSF. Audit log immutable.

GET /api/v1/compliance/frameworks         # 5 frameworks
GET /api/v1/compliance/frameworks/{id}/controls
POST /api/v1/compliance/assessments       # Self-assessment
GET /api/v1/audit?ws=$WS&limit=100        # Audit log
GET /api/v1/privacy/preferences?ws=$WS    # GDPR consent

💳 ZeniPay — VietQR Direct

Thanh toán VietQR trực tiếp qua NAPAS — không qua trung gian. Hỗ trợ tất cả ngân hàng VN.

# Tạo intent thanh toán
POST /api/v1/zeni-pay/intent?ws=$WS
{
  "amount_vnd": 4900000,
  "description": "Pro plan tháng 5",
  "reference": "INV-2026-001"
}
# → returns { intent_code, qr_image_base64, expires_at, bank_info }

# Check status
GET /api/v1/zeni-pay/intent/{intent_code}
# → status: pending | paid | expired | cancelled

📧 ZeniMail — Mailing Lists

Tạo mailing list, quản lý subscriber, gửi campaign, track open/click rate.

POST /api/v1/mail/lists?ws=$WS         # Tạo list
POST /api/v1/mail/subscribers?ws=$WS   # Add subscriber
POST /api/v1/mail/campaigns?ws=$WS     # Send campaign

📞 ZeniVoice — Số điện thoại + Voice AI

Mua số VN/quốc tế, voice agent (AI auto trả lời), call recording, transcribe.

GET /api/v1/voice/numbers?ws=$WS       # List numbers
POST /api/v1/voice/numbers/buy         # Mua số mới
POST /api/v1/voice/agents              # Tạo voice AI agent

🤖 Workflow: Build chatbot trong 30 phút

1. Tạo collection vector để lưu knowledge base
2. Upload docs vào collection (PDF/MD/HTML — auto chunk + embed)
3. Tạo RAG pipeline với prompt template
4. Build webhook receiver tại POST /webhooks/chatbot
5. Connect frontend (chat widget) đến webhook

# Webhook handler:
async function handleChat(req) {
  const { question, sessionId } = req.body;
  const answer = await fetch('https://zenicloud.io/api/v1/vector-premium/rag/pipelines/{id}/query?ws=...', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${ZENI_TOKEN}` },
    body: JSON.stringify({ question, session_id: sessionId })
  });
  return answer.json();
}

📖 Workflow: RAG Pipeline production

Use case: Bot trả lời câu hỏi về tài liệu công ty.

1. L2: Tạo collection company-docs (768 dims)
2. L4: Cron job chạy mỗi tối, scan Google Drive → chunk → embed → upsert
3. L3: RAG pipeline với hybrid_alpha=0.5 + rerank
4. L1: Deploy chatbot frontend (Next.js) → connect API
5. L5: Restrict access bằng MFA cho nhân viên nội bộ
6. Edge CDN: Cache static assets

🚂 Migrate từ Railway → Zeni Cloud

1. Container image: Push image lên Artifact Registry hoặc Docker Hub
2. Database: pg_dump từ Railway → restore vào Cloud SQL via POST /data/datasources/{id}/restore
3. Redis: Provision Memorystore via Zeni → migrate keys (KEYS pattern + DUMP/RESTORE)
4. Env vars: Copy từ Railway → paste vào env_vars + secrets khi deploy project
5. DNS: Point CNAME từ Railway domain → Zeni Cloud hostname
6. AI keys: Bỏ Anthropic/OpenAI/Gemini — dùng ZENI_TOKEN qua ZeniRouter

▲ Migrate từ Vercel → Zeni Cloud

1. Build app: Next.js → standalone build → Docker image
2. Deploy: POST /projects với image Docker
3. Edge CDN: Setup zone qua POST /edge/zones
4. Functions/API routes: Cùng codebase, chạy native trên L1 Compute
5. KV/Edge Config: Dùng L2 Redis cache

🔧 Troubleshooting

❌ "Email hoặc mật khẩu không đúng" khi login

Có thể do:

• Sai password — thử reset qua "Quên mật khẩu" trên trang login
• Account bị disabled — liên hệ support@zenicloud.io
• Workspace bị xóa — đăng ký workspace mới

❌ HTTP 401 "missing bearer token"

Header Authorization: Bearer YOUR_TOKEN chưa set. Kiểm tra:

• Token đã có prefix zeni_pat_ hoặc là JWT từ login
• Token chưa hết hạn (default 365 ngày cho PAT, 1h cho JWT)
• Token chưa bị revoke (check tại /api-tokens?ws=...)

❌ HTTP 403 "workspace_id mismatch"

Bạn đang dùng token của workspace A để gọi resource workspace B. Mỗi token chỉ cho 1 workspace.

❌ HTTP 429 "Too Many Requests" (quota exceeded)

Đã vượt quota plan hiện tại:

• Free: 100K req/tháng, 5 agent runs, 50K tokens out
• Starter: 1M req, 100 agent runs, 500K tokens
• Pro: 10M req, 1K agent runs, 5M tokens

Upgrade tại /pricing hoặc top-up wallet.

❌ HTTP 500 "Internal Server Error"

Bug platform — check status page status.zenicloud.io hoặc báo support kèm request_id trong response header.

❌ Deploy thất bại (status: failed)

Check GET /projects/{id} để xem error message. Lý do thường gặp:

• Image không pull được: image private hoặc tên sai
• Container không listen port: check port param khớp với app
• Out of memory: tăng size từ s → m hoặc l

💰 Giá & Quota

Top-up wallet để vượt quota tạm thời mà không upgrade plan.

📋 API Reference

OpenAPI spec đầy đủ với 387+ endpoints:

• JSON Spec
• Swagger UI (interactive)
• ReDoc (clean reference)

✉️ Liên hệ

• 📧 support@zenicloud.io
• 📧 sales@zenicloud.io (Enterprise / Reseller)
• 💬 Telegram @zenicloud
• 🐛 Bug report GitHub