Tài liệu API AI — CloudMoon

1. Hai nhóm API — dùng domain nào?

Có 2 domain khác nhau cho 2 mục đích — đừng nhầm:

Bạn muốn	Domain	Cần khoá?
Gọi AI (chat, ảnh, video…)	https://aiapi.cloudmoon.net/v1	✅ Có (`sk-`)
Tra bảng giá / trạng thái model (công khai)	https://cloudmoon.net/api/ai	❌ Không

• aiapi.cloudmoon.net = cổng AI — nơi THỰC SỰ gọi model, luôn cần khoá sk-. Mục 2–13 dùng domain này.
• cloudmoon.net/api/ai = thông tin công khai — giá + trạng thái, không cần khoá, để dựng web bán lại. Mục 14.

2. Lấy khoá & Base URL

Base URL (điền vào tool / SDK):

https://aiapi.cloudmoon.net/v1

Lấy khoá sk- ở trang API keys (cần đăng nhập + nạp Xu). Một tài khoản tạo nhiều khoá, tất cả dùng chung số dư Xu; mỗi khoá đặt được hạn mức riêng + khoá theo IP.

Kiểm tra khoá hợp lệ (ping nhanh — trả HTTP 200 là OK):

curl https://aiapi.cloudmoon.net/v1/models -H "Authorization: Bearer sk-YOUR_KEY"

Nên gọi API từ backend/server — đừng nhúng khoá vào frontend công khai.

3. Xác thực

Chuẩn OpenAI — gửi header Authorization: Bearer:

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

Chuẩn Anthropic (SDK anthropic) — dùng x-api-key (cũng chấp nhận):

x-api-key: sk-xxxxxxxxxxxxxxxx anthropic-version: 2023-06-01

4. Chat (chuẩn OpenAI) — POST /chat/completions

Cách gọi phổ biến nhất, dùng cho tất cả model.

curl https://aiapi.cloudmoon.net/v1/chat/completions \ -H "Authorization: Bearer sk-YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-2.5-flash-lite", "messages": [{"role": "user", "content": "Xin chào"}] }'

# pip install openai from openai import OpenAI client = OpenAI(api_key="sk-YOUR_KEY", base_url="https://aiapi.cloudmoon.net/v1") resp = client.chat.completions.create( model="google/gemini-2.5-flash-lite", messages=[{"role": "user", "content": "Xin chào"}], ) print(resp.choices[0].message.content)

// npm i openai import OpenAI from "openai"; const client = new OpenAI({ apiKey: "sk-YOUR_KEY", baseURL: "https://aiapi.cloudmoon.net/v1" }); const resp = await client.chat.completions.create({ model: "google/gemini-2.5-flash-lite", messages: [{ role: "user", content: "Xin chào" }], }); console.log(resp.choices[0].message.content);

Kết quả mẫu:

{ "id": "chatcmpl-8f2b...", "object": "chat.completion", "model": "google/gemini-2.5-flash-lite", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Chào bạn! Mình giúp gì được?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 8, "completion_tokens": 9, "total_tokens": 17 } }

Câu trả lời ở choices[0].message.content. Token thực dùng ở usage — căn cứ trừ Xu.

5. Chat (chuẩn Anthropic) — POST /messages

Dành cho ai quen SDK anthropic. Bắt buộc max_tokens. Trả về khối content.

curl https://aiapi.cloudmoon.net/v1/messages \ -H "x-api-key: sk-YOUR_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-2.5-flash-lite", "max_tokens": 1024, "messages": [{"role": "user", "content": "Xin chào"}] }'

# pip install anthropic import anthropic client = anthropic.Anthropic(api_key="sk-YOUR_KEY", base_url="https://aiapi.cloudmoon.net/v1") msg = client.messages.create( model="google/gemini-2.5-flash-lite", max_tokens=1024, messages=[{"role": "user", "content": "Xin chào"}], ) print(msg.content[0].text)

// npm i @anthropic-ai/sdk import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ apiKey: "sk-YOUR_KEY", baseURL: "https://aiapi.cloudmoon.net/v1" }); const msg = await client.messages.create({ model: "google/gemini-2.5-flash-lite", max_tokens: 1024, messages: [{ role: "user", content: "Xin chào" }], }); console.log(msg.content[0].text);

Kết quả mẫu:

{ "id": "msg_01Ab...", "type": "message", "role": "assistant", "model": "google/gemini-2.5-flash-lite", "content": [{ "type": "text", "text": "Chào bạn!" }], "stop_reason": "end_turn", "usage": { "input_tokens": 8, "output_tokens": 5 } }

Không rành thì cứ dùng mục 4 (OpenAI) — bao hết mọi model.

6. Streaming (nhận token dần)

Thêm "stream": true để chữ hiện dần như ChatGPT. Server trả SSE — mỗi dòng một data:, kết thúc data: [DONE].

data: {"choices":[{"delta":{"content":"Ngày"}}]} data: {"choices":[{"delta":{"content":" xưa"}}]} data: {"choices":[{"delta":{},"finish_reason":"stop"}]} data: [DONE]

SDK tự gộp: Python stream=True rồi for chunk in resp; JS { stream: true } rồi for await.

7. Hội thoại nhiều lượt & tham số

Gửi cả lịch sử trong messages (vai system / user / assistant) để model nhớ ngữ cảnh:

{ "model": "google/gemini-2.5-flash-lite", "messages": [ {"role": "system", "content": "Bạn là trợ lý bán hàng, trả lời ngắn gọn."}, {"role": "user", "content": "Shop có bán VPS không?"}, {"role": "assistant", "content": "Dạ có ạ."}, {"role": "user", "content": "Giá rẻ nhất bao nhiêu?"} ], "temperature": 0.7, "max_tokens": 500 }

Tham số hay dùng (thêm vào body):

Tham số	Kiểu	Ý nghĩa
`temperature`	0–2	Càng cao càng sáng tạo (mặc định ~1)
`max_tokens`	số	Giới hạn độ dài trả lời
`top_p`	0–1	Nucleus sampling (thay cho temperature)
`stop`	chuỗi / mảng	Gặp chuỗi này thì dừng
`stream`	bool	Trả token dần (mục 6)
`response_format`	object	`{"type":"json_object"}` ép trả JSON hợp lệ
`seed`	số	Cố gắng tái lập cùng kết quả
`tools` / `tool_choice`	mảng	Function calling (mục 8)

8. Function calling (tools) — cho model tự gọi hàm

Khai báo hàm ở tools; model quyết định gọi hàm nào + trả về arguments. Bạn chạy hàm rồi gửi kết quả lại.

B1. Gửi kèm tools:

curl https://aiapi.cloudmoon.net/v1/chat/completions \ -H "Authorization: Bearer sk-YOUR_KEY" -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-2.5-flash-lite", "messages": [{"role": "user", "content": "Thời tiết Hà Nội thế nào?"}], "tools": [{ "type": "function", "function": { "name": "get_weather", "description": "Lấy thời tiết theo thành phố", "parameters": { "type": "object", "properties": { "city": {"type": "string"} }, "required": ["city"] } } }] }'

B2. Model trả về ý định gọi hàm (finish_reason: "tool_calls"):

{ "choices": [{ "finish_reason": "tool_calls", "message": { "role": "assistant", "content": null, "tool_calls": [{ "id": "call_abc", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Hà Nội\"}" } }] } }] }

B3. Chạy hàm của bạn, gửi kết quả lại bằng message vai tool:

"messages": [ {"role": "user", "content": "Thời tiết Hà Nội thế nào?"}, {"role": "assistant", "content": null, "tool_calls": [ /* như B2 */ ]}, {"role": "tool", "tool_call_id": "call_abc", "content": "{\"temp\":31,\"desc\":\"nắng\"}"} ]

Lượt cuối model dùng kết quả hàm để trả lời bằng chữ. Dùng cho chatbot tra cứu, đặt lịch, gọi API nội bộ…

9. Vision — gửi ảnh cho model đọc

Với model hỗ trợ ảnh đầu vào (Gemini, GPT, Claude…), chèn image_url vào content:

curl https://aiapi.cloudmoon.net/v1/chat/completions \ -H "Authorization: Bearer sk-YOUR_KEY" -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-2.5-flash-lite", "messages": [{ "role": "user", "content": [ {"type": "text", "text": "Ảnh này có gì?"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KG..."}} ] }] }'

Ảnh gửi dạng data URL base64 (data:image/png;base64,...) hoặc HTTPS URL công khai. Model không hỗ trợ vision sẽ báo lỗi.

10. Responses API — POST /responses (cho Codex / IDE)

Chuẩn "Responses" của OpenAI, dùng cho một số IDE/agent (Codex…).

curl https://aiapi.cloudmoon.net/v1/responses \ -H "Authorization: Bearer sk-YOUR_KEY" -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-2.5-flash-lite", "input": "Xin chào" }'

Cấu hình Codex (custom provider) — config.toml:

model = "google/gemini-2.5-flash-lite" model_provider = "cloudmoon" [model_providers.cloudmoon] name = "CloudMoon AI" base_url = "https://aiapi.cloudmoon.net/v1" env_key = "CLOUDMOON_API_KEY" wire_api = "responses"

env_key = TÊN biến môi trường chứa khoá (đặt khoá thật vào CLOUDMOON_API_KEY), không phải khoá.

11. Tích hợp vào công cụ có sẵn (không cần code)

Nhiều IDE / app chat cho nhập endpoint tùy chỉnh — trỏ vào cổng AI + dán khoá + chọn model là chạy.

Claude Code (Anthropic CLI) — đặt biến môi trường rồi mở Claude Code:

export ANTHROPIC_BASE_URL="https://aiapi.cloudmoon.net" export ANTHROPIC_AUTH_TOKEN="sk-YOUR_KEY" export ANTHROPIC_MODEL="google/gemini-2.5-flash-lite" export ANTHROPIC_SMALL_FAST_MODEL="google/gemini-2.5-flash-lite"

Cursor — Settings → Models:

Mục trong Cursor	Giá trị
OpenAI API Key	`sk-YOUR_KEY`
Override OpenAI Base URL (bật)	`https://aiapi.cloudmoon.net/v1`
Add model	`google/gemini-2.5-flash-lite`, `openai/gpt-5.6-sol`…

Agent/Composer cần model hỗ trợ tool-call (Claude / GPT đều được). Tab autocomplete vẫn dùng model riêng của Cursor.

Codex — dùng Responses API, cấu hình config.toml (xem mục 10).

App chat bên thứ 3 (Cherry Studio, ChatBox, LibreChat, Jan…) — chọn 1 trong 2 chuẩn (cổng hỗ trợ cả hai):

Base URL nhập vào app	Chuẩn	App gọi
`https://aiapi.cloudmoon.net/v1`	OpenAI	`/chat/completions`
`https://aiapi.cloudmoon.net`	Anthropic	`/v1/messages`

Dán khoá sk-, chọn model theo bảng giá (dùng đúng id có dấu /).

12. Sinh ảnh & video sắp có

Endpoint theo chuẩn OpenAI, sẽ mở khi có model ảnh/video. Định dạng dự kiến:

POST https://aiapi.cloudmoon.net/v1/images/generations — sinh ảnh, trừ Xu mỗi ảnh

// request { "model": "…", "prompt": "hoàng hôn trên biển", "size": "1024x1024", "n": 1 } // response → link ảnh dùng thẳng { "created": 1779000000, "data": [{ "url": "https://…/media/…" }] }

POST https://aiapi.cloudmoon.net/v1/videos/generations — sinh video dạng job bất đồng bộ, trừ Xu theo giây

// 1) submit → nhận job id ngay 2) poll trạng thái tới khi xong 3) tải MP4

Ảnh/video render lâu → gọi bất đồng bộ (job + poll) tránh timeout. Theo dõi model mở bán ở bảng giá / trạng thái.

13. Danh sách model — GET /models

curl https://aiapi.cloudmoon.net/v1/models -H "Authorization: Bearer sk-YOUR_KEY"

{ "data": [ { "id": "google/gemini-2.5-flash-lite", "object": "model" }, { "id": "openai/gpt-5.6-sol", "object": "model" } ] }

Dùng đúng id trả về trong request. Muốn xem kèm GIÁ mà không cần khoá → mục 14.

14. Theo dõi usage — GET /dashboard/billing/usage

curl "https://aiapi.cloudmoon.net/v1/dashboard/billing/usage?start_date=2026-07-01&end_date=2026-07-31" \ -H "Authorization: Bearer sk-YOUR_KEY"

{ "object": "list", "total_usage": 12.34 }

Tổng tiêu dùng trong kỳ. Xem số dư còn lại + chi tiết từng lượt (model, token, chi phí) ở Nhật ký.

15. API công khai (không cần khoá) — cloudmoon.net/api/ai

Dựng web bán lại / hiện bảng giá — không cần đăng nhập, CORS mở.

GET https://cloudmoon.net/api/ai/pricing — bảng giá (xem trang)

{ "brand": "CloudMoon", "base_url": "https://aiapi.cloudmoon.net/v1", "currency": "xu", "count": 13, "data": [ { "model": "google/gemini-2.5-flash-lite", "name": "Claude Opus 4.8", "type": "chat", "input_per_1m_vnd": 6000, "output_per_1m_vnd": 9000 } ] }

GET https://cloudmoon.net/api/ai/status — model nào đang chạy (xem trang)

{ "brand": "CloudMoon", "checked_at": "2026-07-29 10:25:46", "summary": { "total": 13, "operational": 11, "down": 2 }, "data": [ { "model": "google/gemini-2.5-flash-lite", "name": "Claude Opus 4.8", "status": "operational" } ] }

Đơn vị = Xu (1 xu = 1đ). input/output_per_1m_vnd = Xu / 1 triệu token; ảnh/video có per_request_vnd.

16. Tính phí (Xu)

Trừ theo token thực dùng (input + output), đơn giá theo bảng giá — Xu / 1 triệu token, 1 xu = 1đ. Ảnh trừ theo mỗi ảnh, video theo mỗi giây. Số token trả về trong usage mỗi response. Khi số dư thấp, trước mỗi lượt cổng tạm giữ một khoản ước theo max_tokens rồi trả lại phần dư khi xong — số dư không đủ cho khoản tạm giữ thì lượt bị chối với 403 và error.code = insufficient_user_quota (hãy bắt theo code, đừng dựa vào câu chữ của message). Chi tiết từng lượt: Nhật ký.

17. Timeout, retry & thực hành tốt

Timeout client khuyên đặt: chat/text 60–180s · streaming giữ tới [DONE] · ảnh (sắp có) 180–360s · video submit 60s, poll 300s.

Retry: gặp 429/500/502/503/504 → thử lại tối đa 2–3 lần, chờ tăng dần 1s → 3s → 8s + jitter. Đừng bắn lại 20–50 request cùng lúc.

Mã	Ý nghĩa	Xử lý
`401`	Sai / thiếu khoá `sk-`	Kiểm tra header Authorization
`403` · `insufficient_user_quota`	Số dư Xu không đủ cho lượt này	Nạp thêm, hoặc giảm `max_tokens`
`403` · `pre_consume_token_quota_failed`	Khoá đã chạm hạn mức chi tiêu bạn đặt cho nó	Tăng hạn mức ở Khoá API
`404`	Model / endpoint không tồn tại	Lấy id đúng ở `GET /models`
`429`	Gọi quá nhanh (rate limit)	Giảm concurrency + retry backoff
`5xx` / `503`	Model tạm gián đoạn	Xem trạng thái, retry hoặc đổi model

Thực hành tốt:

Tái dùng client SDK (một instance) thay vì khởi tạo mới mỗi request.
Streaming (stream:true) cho app chat — user thấy chữ chảy dần, UX mượt hơn.
Không retry 403 hết số dư / hết hạn mức khoá (chờ nạp) hay 422/prompt-lỗi (sửa prompt); chỉ retry 429/5xx.
Đặt max_tokens hợp lý để kiểm soát chi phí + độ trễ.

18. Khuyến nghị bảo mật

Chỉ lưu khoá ở biến môi trường phía server — không nhúng vào frontend / GitHub.
Tạo khoá riêng cho production / staging / local để dễ thu hồi.
Đặt hạn mức + khoá theo IP cho từng khoá ở API keys.
Nghi lộ khoá → bấm "Thu hồi & tạo lại" (khoá cũ chết ngay, nhận khoá mới giữ nguyên cài đặt).

19. Bảng endpoint

Method	Endpoint	Mục đích
POST	`/chat/completions`	Chat chuẩn OpenAI (mọi model) + tools + vision
POST	`/messages`	Chat chuẩn Anthropic
POST	`/responses`	Responses API (Codex/IDE)
GET	`/models`	Danh sách model gọi được
GET	`/dashboard/billing/usage`	Tổng usage theo kỳ
POST	`/images/generations` sắp có	Sinh ảnh
POST	`/videos/generations` sắp có	Sinh video (job)
GET	`cloudmoon.net/api/ai/pricing`	Bảng giá công khai (không key)
GET	`cloudmoon.net/api/ai/status`	Trạng thái model (không key)