Tài liệu tích hợp API

API tương thích chuẩn OpenAI Chat Completions — dùng được với mọi SDK hỗ trợ OpenAI.

Bắt đầu nhanh

Ba bước để có bài viết đầu tiên:

• Tạo tài khoản — API key sinh ngay trên dashboard.
• Chờ quản trị viên duyệt tài khoản và cấp token — key chỉ hoạt động sau bước này.
• Gọi API:

curl https://fbagent.work999.com/api/v1/chat/completions \
  -H "Authorization: Bearer sk-fba-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "Bạn là chuyên gia content marketing tiếng Việt."},
      {"role": "user", "content": "Viết bài SEO 500 từ về: cách chọn máy lọc không khí"}
    ],
    "max_tokens": 1200,
    "temperature": 0.7
  }'

Xác thực

Mọi request cần header:

Authorization: Bearer <API_KEY>

API key dạng sk-fba-…, lấy tại Dashboard. Tạo key mới bất kỳ lúc nào — key cũ vô hiệu ngay khi key mới sinh ra.

Tạo nội dung

POST /api/v1/chat/completions

Response chuẩn OpenAI — trường usage.total_tokens là số token trừ vào tài khoản:

{
  "choices": [{
    "message": {"role": "assistant", "content": "Nội dung được tạo…"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 45, "completion_tokens": 812, "total_tokens": 857}
}

Header phản hồi kèm X-Tokens-Used và X-Tokens-Remaining để bạn theo dõi số dư không cần gọi thêm.

Endpoint phụ

Tạo ảnh

POST /api/v1/images/generations

Tạo ảnh minh họa 512×512 từ mô tả. Prompt nên viết bằng tiếng Anh — model ảnh không hiểu tiếng Việt.

curl https://fbagent.work999.com/api/v1/images/generations \
  -H "Authorization: Bearer sk-fba-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "bowl of Vietnamese pho with beef and herbs, top view, natural light"}'

Response:

{
  "created": 1783590000,
  "data": [{"url": "https://fbagent.work999.com/gen/AbC123xyz.png"}],
  "usage": {"tokens_charged": 500}
}

• Mỗi ảnh trừ số token cố định (mặc định 500 — xem giá hiện tại qua GET /api/v1/me, trường image_token_cost).
• Giới hạn riêng cho ảnh: mặc định 3 ảnh/phút mỗi tài khoản (trường img_rpm_limit trong /api/v1/me). Vượt trả 429 kèm Retry-After.
• Ảnh mất khoảng 15–30 giây tùy tải hệ thống — đặt timeout client tối thiểu 120 giây.
• Link ảnh lưu 7 ngày; cần giữ lâu dài hãy tải về hoặc dùng b64_json.

Streaming

Thêm "stream": true để nhận nội dung dần theo Server-Sent Events — phù hợp hiển thị chữ chạy realtime:

curl -N https://fbagent.work999.com/api/v1/chat/completions \
  -H "Authorization: Bearer sk-fba-xxxxxxxx" \
  -d '{"messages":[{"role":"user","content":"Viết caption về trà sữa"}],"stream":true}'

Mỗi dòng data: chứa một phần nội dung, kết thúc bằng data: [DONE]. Token tính đầy đủ như chế độ thường.

SDK OpenAI

Python

# pip install openai
from openai import OpenAI

client = OpenAI(base_url="https://fbagent.work999.com/api/v1", api_key="sk-fba-xxxxxxxx")

resp = client.chat.completions.create(
    model="qwen3-4b",
    messages=[{"role": "user", "content": "Viết mô tả 100 từ cho son môi đỏ cam"}],
    max_tokens=400,
)
print(resp.choices[0].message.content)
print("Token đã dùng:", resp.usage.total_tokens)

Node.js

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://fbagent.work999.com/api/v1",
  apiKey: "sk-fba-xxxxxxxx",
});

const resp = await client.chat.completions.create({
  model: "qwen3-4b",
  messages: [{ role: "user", content: "Viết tiêu đề SEO cho bài về du lịch Phú Quốc" }],
  max_tokens: 200,
});
console.log(resp.choices[0].message.content);

PHP

$ch = curl_init("https://fbagent.work999.com/api/v1/chat/completions");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer sk-fba-xxxxxxxx",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "messages" => [["role" => "user", "content" => "Viết mô tả nồi chiên không dầu"]],
    "max_tokens" => 500
  ])
]);
$data = json_decode(curl_exec($ch), true);
echo $data["choices"][0]["message"]["content"];

Tính phí token

• Mỗi request trừ usage.total_tokens — tổng token input và output.
• Tiếng Việt: 1 từ xấp xỉ 1.4–1.6 token. Bài 1000 từ cần 1500–1800 token output.
• Số dư hết, API trả 402 insufficient_tokens — liên hệ quản trị viên để nạp thêm.
• Kiểm tra số dư qua GET /api/v1/me hoặc trên Dashboard.

Rate limit & hàng chờ

• Mỗi tài khoản có giới hạn request/phút — mặc định 10, quản trị viên điều chỉnh được. Vượt hạn mức, API trả 429 rate_limit_exceeded kèm header Retry-After.
• Hệ thống xử lý tối đa 8 request đồng thời. Request kế tiếp xếp hàng FIFO — tối đa 32 request chờ, mỗi request chờ tối đa 120 giây.
• Hàng chờ đầy, API trả 429 queue_full — retry với backoff tăng dần: 5s, 15s, 30s.
• Xem tình trạng hàng chờ realtime: GET /api/v1/status.

Mã lỗi

Định dạng lỗi thống nhất:

{"error": {"code": "rate_limit_exceeded", "message": "Vượt giới hạn 10 request/phút…"}}

Mẹo viết prompt content tiếng Việt

• Cố định vai trò bằng system message: "Bạn là chuyên gia content marketing tiếng Việt, viết chuẩn SEO."
• Nêu rõ độ dài, cấu trúc heading, tone giọng và từ khóa cần chứa.
• Bài dài trên 800 từ: đặt max_tokens 2000–2500 để không bị cắt giữa chừng.
• Nội dung nhất quán dùng temperature 0.6 — nội dung sáng tạo dùng 0.8–0.9.
• Sinh hàng loạt: gửi tuần tự hoặc vài request song song, xử lý 429 bằng retry và backoff.