Tài liệu tích hợp
Mọi request đều xác thực bằng API key trong header Authorization: Bearer sk-cb-…. Chatbot trừ theo số token mỗi câu trả lời; API tạo ảnh trừ theo số ảnh tạo được.
1. Widget nhúng
Dán đoạn sau trước thẻ </body>. Nên giới hạn key theo domain website của bạn trong trang quản lý key, vì key nằm công khai trong mã nguồn trang.
<script src="https://api.aidesign.io.vn/chatbot-widget.js" data-api-key="sk-cb-..." data-title="AI Hỗ trợ" data-theme="light" data-primary-color="#059669" ></script>
Thuộc tính khác: data-position (bottom-right | bottom-left), data-welcome, data-system-prompt, data-theme (light | dark).
2. REST API
POST /api/chatbot/chat
| Tham số | Kiểu | Mô tả |
|---|---|---|
| message | string (bắt buộc) | Câu hỏi của người dùng, tối đa 32.000 ký tự. |
| history | array | Lịch sử hội thoại: [{ role: "user" | "assistant", content }]. |
| system_prompt | string | Chỉ dẫn riêng cho bot (vai trò, giọng văn, thông tin cửa hàng…). |
| image | string | Ảnh dạng data URL base64 (data:image/png;base64,…) để AI phân tích. |
| stream | boolean | true (mặc định): trả về Server-Sent Events. false: trả về JSON đầy đủ. |
curl https://api.aidesign.io.vn/api/chatbot/chat \
-H "Authorization: Bearer sk-cb-..." \
-H "Content-Type: application/json" \
-d '{"message": "Xin chào", "stream": false}'const res = await fetch("https://api.aidesign.io.vn/api/chatbot/chat", {
method: "POST",
headers: {
"Authorization": "Bearer sk-cb-...",
"Content-Type": "application/json",
},
body: JSON.stringify({
message: "Xin chào",
history: [], // [{ role: "user" | "assistant", content: "..." }]
system_prompt: "", // tùy chọn
stream: false,
}),
});
const data = await res.json();
console.log(data.choices[0].message.content);import requests
res = requests.post(
"https://api.aidesign.io.vn/api/chatbot/chat",
headers={"Authorization": "Bearer sk-cb-..."},
json={"message": "Xin chào", "stream": False},
)
print(res.json()["choices"][0]["message"]["content"])Kết quả (stream: false) theo định dạng OpenAI: nội dung trả lời ở choices[0].message.content, số token ở usage.total_tokens.
3. API tạo ảnh (chuẩn OpenAI)
Cần key có gói Tạo ảnh hoặc Combo. Mỗi ảnh trả về trừ 1 ảnh trong hạn mức; ảnh tạo lỗi không bị trừ. Dùng được trực tiếp với thư viện OpenAI chính thức: đặt base_url là https://api.aidesign.io.vn/v1.
| Endpoint | Mô tả |
|---|---|
| POST /v1/images/generations | Tạo ảnh từ mô tả (JSON) |
| POST /v1/images/edits | Sửa ảnh / ghép ảnh từ ảnh gốc (multipart form) |
| Tham số | Kiểu | Mô tả |
|---|---|---|
| prompt | string (bắt buộc) | Mô tả ảnh cần tạo hoặc yêu cầu chỉnh sửa. |
| model | string | gpt-image-2 (mặc định). |
| n | number | Số ảnh, 1–4. Bị trừ theo số ảnh thực sự trả về. |
| size | string | Tỷ lệ khung: 1:1 (mặc định), 16:9, 9:16, 4:3, 3:4. |
| response_format | string | b64_json (mặc định) hoặc url. |
| image | file | Chỉ với /v1/images/edits: một hoặc nhiều ảnh gốc (PNG/JPG). |
from openai import OpenAI
import base64
client = OpenAI(api_key="sk-cb-...", base_url="https://api.aidesign.io.vn/v1")
result = client.images.generate(
model="gpt-image-2",
prompt="Poster cà phê sữa đá, phong cách tối giản",
n=1,
size="1:1",
)
with open("poster.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))import OpenAI from "openai";
const client = new OpenAI({ apiKey: "sk-cb-...", baseURL: "https://api.aidesign.io.vn/v1" });
const result = await client.images.generate({
model: "gpt-image-2",
prompt: "Poster cà phê sữa đá, phong cách tối giản",
n: 1,
size: "1:1",
});
const pngBase64 = result.data[0].b64_json;curl https://api.aidesign.io.vn/v1/images/generations \
-H "Authorization: Bearer sk-cb-..." \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2", "prompt": "Poster cà phê sữa đá, phong cách tối giản", "n": 1, "size": "1:1"}'curl https://api.aidesign.io.vn/v1/images/edits \ -H "Authorization: Bearer sk-cb-..." \ -F "model=gpt-image-2" \ -F "prompt=Đổi nền thành bãi biển lúc hoàng hôn" \ -F "image=@san-pham.png"
Kết quả: data[i].b64_json (ảnh PNG dạng base64) hoặc data[i].url khi gửi response_format: "url". Thời gian tạo thường 20–60 giây/ảnh — nên đặt timeout tối thiểu 180 giây.
4. Kiểm tra hạn mức còn lại
curl https://api.aidesign.io.vn/api/chatbot/key-info \ -H "Authorization: Bearer sk-cb-..."
{ "name": "Shop ABC", "status": "ok", "token_limit": 1000000, "tokens_used": 12345,
"tokens_remaining": 987655, "image_limit": 200, "images_used": 12, "images_remaining": 188,
"daily_token_cap": 0, "next_reset_at": null, "credit_balance_vnd": 85320.5, "rate_card": "Tiêu chuẩn",
"expires_at": "2026-12-31T23:59:59Z" }Key trả theo dùng (có credit) trừ tiền theo bảng đơn giá: token vào, token ra và mỗi ảnh. Key combo dùng hạn mức trước, phần vượt mới trừ credit. Credit có thể âm nhẹ sau request cuối cùng (vì số token chỉ biết sau khi AI trả lời); request tiếp theo sẽ bị chặn cho đến khi nạp thêm.