Bỏ qua, tới nội dung chính

SDK & thư viện

SDK & thư viện

Nói thẳng: Chat Tự Động chưa phát hành SDK riêng. Và trong đa số trường hợp bạn không cần — endpoint gọi model được thiết kế tương thích OpenAI, nên thư viện OpenAI chính thức chạy được ngay sau khi đổi baseURL.

Tình trạng hiện tại

Chúng tôi không muốn bạn mất thời gian đi tìm một gói không tồn tại, nên nói rõ ngay từ đầu:

  • Chưa có gói npm hay PyPI mang thương hiệu Chat Tự Động. Nếu bạn thấy gói nào tên như vậy trên registry công khai, đó không phải của chúng tôi — đừng cài.
  • Có đặc tả OpenAPI sinh thẳng từ mã nguồn tại https://api.chattudong.com/docs, dùng để tự sinh client cho ngôn ngữ bạn cần.
  • Có khả năng tương thích OpenAI ở /v1/models và /v1/chat/completions — đủ cho phần lớn tích hợp.

Cách làm này có một lợi ích thật cho bạn: không bị khoá chân. Code viết hôm nay chạy với chúng tôi, đổi baseURL là chạy thẳng với OpenAI hoặc bất kỳ nhà cung cấp tương thích nào khác. Bạn không phải viết lại gì cả.

Node.js / TypeScript

Cài thư viện chính thức của OpenAI rồi trỏ baseURL sang https://api.chattudong.com/v1. Khoá bạn truyền vào apiKey là API key của Chat Tự Động (bắt đầu bằng ck_live_), không phải khoá OpenAI.

Cài đặt
npm install openai
Gọi model, nhận trả lời đầy đủ
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.chattudong.com/v1",
  apiKey: process.env.CHATLY_API_KEY,   // ck_live_…
});

const res = await client.chat.completions.create({
  model: "local/gemma-3-12b",
  messages: [
    { role: "system", content: "Bạn là trợ lý của một cửa hàng thời trang. Trả lời ngắn gọn." },
    { role: "user", content: "Shop mở cửa mấy giờ?" },
  ],
  temperature: 0.3,
  max_tokens: 512,
});

console.log(res.choices[0]?.message.content);

Streaming

Chữ hiện dần khi khách đang chờ
const stream = await client.chat.completions.create({
  model: "local/gemma-3-12b",
  messages: [{ role: "user", content: "Tư vấn giúp tôi chọn size áo" }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

Đọc chi phí đã trừ

Phản hồi có thêm khối chatly nằm ngoài chuẩn OpenAI, nên kiểu dữ liệu của thư viện không biết tới nó. Ép kiểu một lần rồi đọc là xong:

TypeScript
type UsageMeta = { charged_micros: string; byok: boolean };

const meta = (res as unknown as { chatly?: UsageMeta }).chatly;
if (meta) {
  console.log("Đã trừ (micro):", meta.charged_micros, "| BYOK:", meta.byok);
}

Python

Cài đặt
pip install openai
Gọi model
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.chattudong.com/v1",
    api_key=os.environ["CHATLY_API_KEY"],   # ck_live_…
)

res = client.chat.completions.create(
    model="local/gemma-3-12b",
    messages=[
        {"role": "system", "content": "Bạn là trợ lý của một cửa hàng thời trang. Trả lời ngắn gọn."},
        {"role": "user", "content": "Shop mở cửa mấy giờ?"},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(res.choices[0].message.content)
Streaming
stream = client.chat.completions.create(
    model="local/gemma-3-12b",
    messages=[{"role": "user", "content": "Tư vấn giúp tôi chọn size áo"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
Liệt kê model đang bật
for m in client.models.list().data:
    print(m.id)

cURL và các ngôn ngữ khác

Không có thư viện phù hợp thì gọi HTTP thẳng cũng chỉ là một request JSON. Ngôn ngữ nào cũng làm được trong vài dòng.

Terminal
curl https://api.chattudong.com/v1/chat/completions \
  -H "Authorization: Bearer $CHATLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local/gemma-3-12b",
    "messages": [{"role": "user", "content": "Shop mở cửa mấy giờ?"}]
  }'

Muốn sinh client tự động cho Go, Java, C# hay PHP thì dùng đặc tả OpenAPI ở https://api.chattudong.com/docs với công cụ sinh code bạn quen. Đặc tả này sinh thẳng từ mã nguồn nên không bao giờ lệch với API thật.

Những chỗ khác với OpenAI

Tương thích không có nghĩa là giống hệt. Đây là những khác biệt bạn nên biết trước khi bê nguyên code cũ sang:

  • Tên model khác. Id model có dạng provider/model, ví dụ local/gemma-3-12b. Đừng đoán — gọi GET /v1/models để lấy danh sách đang bật cho tổ chức của bạn.
  • Phản hồi có thêm khối chatly với charged_micros và byok. Thư viện OpenAI bỏ qua trường lạ nên không gây lỗi.
  • Mã lỗi là của chúng tôi. Thân lỗi có dạng { error: { code, message, requestId } } với bộ mã riêng — xem bảng mã lỗi. Nếu code cũ của bạn bắt lỗi theo mã của OpenAI thì cần chỉnh lại chỗ này.
  • Có header riêng. x-chatly-use-byok: true để dùng khoá provider của bạn (xem BYOK).
  • Chưa hỗ trợ function calling, tool use, đầu vào hình ảnh, embeddings hay tạo ảnh qua endpoint tương thích. Body chỉ nhận content dạng chuỗi. Cần những thứ này thì hiện tại nên gọi thẳng nhà cung cấp.

Sắp tới có SDK riêng không?

Chúng tôi sẽ chỉ làm SDK riêng khi nó thật sự giải quyết được thứ mà thư viện OpenAI không làm nổi — chẳng hạn thao tác với kho kiến thức, quản lý kênh, đọc hội thoại. Phần gọi model thì không có lý do gì để phát minh lại.

Bạn đang cần client cho một ngôn ngữ cụ thể, hoặc đã tự viết một cái muốn chia sẻ? Viết cho chúng tôi ở chattudongcskh@gmail.com — nhu cầu thật quyết định thứ tự ưu tiên tốt hơn phỏng đoán của chúng tôi.