API Reference

Mọi request tới /v1 phải mang API key của tổ chức. Tạo key trong dashboard ở Cài đặt → Khoá API (/dashboard/cai-dat). Key có dạng ck_live_… cho môi trường thật và ck_test_… cho môi trường thử.

Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Hoặc, nếu thư viện của bạn không cho đổi header Authorization:
X-Api-Key: ck_live_xxxxxxxxxxxxxxxxxxxxxxxx

Vài điều nên biết trước khi tích hợp:

• Key thô chỉ hiện đúng một lần lúc tạo. Cơ sở dữ liệu chỉ lưu SHA-256 của key, nên không có đường “xem lại”. Mất thì thu hồi và tạo cái mới.
• Key gắn với tổ chức, không gắn với người. Nhân sự nghỉ việc không làm chết tích hợp.
• Đặt được scopes và số ngày hết hạn khi tạo. Key thiếu scope sẽ nhận 403 insufficient_scope.
• Thu hồi có hiệu lực ngay ở request kế tiếp.

Trả về danh sách model đang bật cho tổ chức bạn, theo đúng khung list của OpenAI và có thêm vài trường riêng để bạn dựng giao diện chọn model.

curl https://api.chattudong.com/v1/models \
  -H "Authorization: Bearer $CHATLY_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "local/gemma-3-12b",
      "object": "model",
      "created": 1750000000,
      "owned_by": "local",
      "display_name": "Gemma 3 12B",
      "friendly_name": "Tiết kiệm",
      "tier": "economy",
      "context_window": 128000,
      "vn_hosted": true
    }
  ]
}

owned_by là provider: openai, anthropic, google, xai hoặc local. vn_hosted cho biết model chạy trên máy chủ đặt tại Việt Nam — dùng để lọc khi tổ chức yêu cầu dữ liệu không rời lãnh thổ.

Endpoint chính. Nhận đúng định dạng OpenAI; những trường lạ trong body được bỏ qua thay vì báo lỗi, nên SDK phiên bản mới hơn cũng không làm hỏng tích hợp.

Tham số

Header tuỳ chọn

Ví dụ — không streaming

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": "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, lịch sự."},
      {"role": "user", "content": "Shop mở cửa mấy giờ?"}
    ],
    "temperature": 0.3,
    "max_tokens": 512
  }'

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "local/gemma-3-12b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Shop mở cửa từ 9h đến 21h mỗi ngày ạ." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 48, "completion_tokens": 17, "total_tokens": 65 },
  "chatly": { "charged_micros": "1830", "byok": false }
}

Khối chatly là phần mở rộng ngoài chuẩn OpenAI: charged_micros là số tiền đã trừ tính theo micro (một phần triệu đơn vị tiền, trả về dạng chuỗi để không mất chính xác), byok cho biết lần gọi đó có dùng khoá riêng của bạn hay không. SDK OpenAI bỏ qua trường lạ nên khối này không làm hỏng gì.

Ví dụ — streaming (SSE)

Đặt "stream": true. Phản hồi là chuỗi sự kiện chat.completion.chunk: mẩu đầu mang role, các mẩu sau mang delta.content, mẩu áp chót mang finish_reason, mẩu cuối mang usage để bạn đối soát, rồi kết thúc bằng [DONE].

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Shop mở cửa"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":48,"completion_tokens":17,"total_tokens":65},"chatly":{"charged_micros":"1830","byok":false}}

data: [DONE]

Mọi lỗi ra khỏi API đều có cùng một hình dạng. Đây là hợp đồng: bạn switch-case theo error.code được, không phải parse chuỗi tiếng Việt.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Ví của tổ chức không đủ credits cho lần gọi này",
    "field": "model",        // chỉ có khi lỗi validate
    "docsUrl": "https://chattudong.com/docs/api-reference",  // chỉ có khi trỏ được tới mục cụ thể
    "retryAfter": 42,        // chỉ có với 429 / 503, đơn vị giây
    "requestId": "req_…"     // LUÔN có
  }
}

• code — mã ổn định, xem bảng bên dưới. Đổi tên mã là breaking change nên chúng tôi không đổi lặng lẽ.
• message — viết cho người đang đọc log lúc 2 giờ sáng: nói rõ chuyện gì xảy ra và làm gì tiếp theo.
• requestId — dán vào ticket hỗ trợ, chúng tôi tra được đúng request đó.
• Với 429 và 503, giá trị retryAfter cũng được trả ở header HTTP Retry-After.

Đây là toàn bộ mã lỗi công khai, không có mã nào nằm ngoài bảng này.

Giới hạn tính theo tổ chức, cửa sổ cố định 60 giây. Số yêu cầu mỗi phút phụ thuộc gói bạn đang dùng; vượt thì nhận 429 rate_limited kèm Retry-After cho biết còn bao nhiêu giây nữa sang cửa sổ mới.

Cách xử lý đúng là đợi đúng Retry-After rồi thử lại, có jitter nếu bạn chạy nhiều worker song song. Đừng thử lại ngay lập tức trong vòng lặp — cửa sổ chưa đổi thì kết quả vẫn thế.

Ngoài /v1, API còn các nhóm phục vụ dashboard và tích hợp sâu hơn. Chúng dùng phiên đăng nhập hoặc API key có scope tương ứng:

Đặc tả OpenAPI được sinh thẳng từ mã nguồn nên không bao giờ lệch với thực tế — xem tại https://api.chattudong.com/docs.