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. Hết số dư → 402. 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
`402`	Hết số dư Xu	Nạp thêm
`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 402 (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)