Tài liệu API

POST https://staging-j97-api-9tm2.encr.app/v1/systemone

Base URL: https://staging-j97-api-9tm2.encr.app

Không có key? POST /demo/systemone nhận cùng body, không cần xác thực, không tính phí, giới hạn theo IP: 10 request mỗi phút, 60 mỗi giờ, 300 mỗi ngày.

Authorization: Bearer tia_live_<32 url-safe characters>

Gửi API key trong header Authorization. Key có dạng tia_live_ theo sau 32 ký tự, tạo trong trang Tài khoản và chỉ hiện một lần. Hệ thống chỉ lưu bản băm SHA-256; mất key thì thu hồi và tạo key mới.

Body là một object JSON:

{
  "state": {
    "kenh": "zalo",
    "goi_dich_vu": "Pro năm",
    "tin_nhan": "Chào shop, tháng này em bị trừ tiền 2 lần cho gói Pro, 499.000đ mỗi lần, hoá đơn thứ hai vẫn đang treo. Nhờ shop hoàn lại khoản bị trừ trùng trong hôm nay giúp em, mai kế toán bên em chốt sổ rồi."
  },
  "questions": {
    "hoan_tien": {
      "type": "noul",
      "instructions": "Khách có đang yêu cầu trả lại tiền không?",
      "criteria": {
        "true": "đòi hoàn tiền, huỷ giao dịch hoặc bù tiền",
        "false": "không đòi lại tiền"
      }
    },
    "doi_xu_ly": {
      "type": "choice",
      "instructions": "Đội nào nên nhận ticket này?",
      "criteria": {
        "thanh_toan": "hoá đơn, trừ tiền, hoàn tiền, gói cước",
        "ky_thuat": "lỗi, sự cố, tích hợp",
        "tai_khoan": "đăng nhập, quyền truy cập, bảo mật",
        "ban_hang": "mua mới, nâng cấp, báo giá"
      }
    },
    "muc_do_gap": {
      "type": "score",
      "instructions": "Ticket này gấp đến mức nào?",
      "criteria": [
        "để tuần sau được",
        "bình thường, trả lời trong 2 ngày",
        "ảnh hưởng tiền hoặc công việc hôm nay",
        "sự cố diện rộng, rủi ro pháp lý hoặc bảo mật"
      ]
    }
  }
}

Mỗi câu hỏi cần instructions: chuỗi nêu câu hỏi.

Response 200 có dạng sau (kiểu dữ liệu TypeScript):

type Response = {
  id: string;                    // "req_…", quote it for support
  object: "systemone";
  model: string;
  answers: Record<string,        // one entry per question name
    | { type: "noul"; noul: number }                      // P(yes), 0..1
    | { type: "choice"; choice: string; confidence: number;
        probabilities: Record<string, number> }           // sums to 1
    | { type: "score"; score: number; confidence: number; // score = expected level
        legend: Record<string, string>;                   // "0" → lowest description
        probabilities: Record<string, number> }
  >;
  cached: boolean;               // served from a stored result: cached price
  usage: { input_tokens: number; output_tokens: 0;
           cached_input_tokens: number; // input_tokens if cached, else 0
           free_tokens: number;         // free quota used (1/10 per cached token)
           cost_micro_vnd: number; cost_display: string };
  balance_display: string;       // e.g. "12.345 đ"; absent on /demo/systemone
};

Mọi lỗi có dạng {"code": ..., "message": ..., "details": ...}. message viết cho người đọc, code để code rẽ nhánh. Lỗi 400 từ mô hình có details.type là input_too_long hoặc invalid_request.

• Mỗi tháng (giờ Việt Nam) có 100.000.000 token đầu vào miễn phí, trừ trước; hết lượt thì 500 đ cho 1 triệu token đầu vào, trừ vào ví. Output miễn phí. Áp dụng từ 01/10/2026.
• Request lặp lại được trả từ kết quả đã lưu ("cached": true; cùng tài khoản, cùng nội dung JSON, cùng phiên bản mô hình) tính 50 đ cho 1 triệu token và trừ 1/10 lượt miễn phí; usage.cached_input_tokens cho biết số token tính giá này.
• Token đầu vào gồm state, instructions và mô tả trong criteria. usage.input_tokens và usage.cost_display trong response là của chính request đó.
• Giới hạn request tính theo tài khoản (mọi key của tài khoản dùng chung) và tăng theo hạng. Hạng là tổng số tiền đã nạp thành công từ trước tới nay.
• Mỗi response có trường id (req_…). Gửi id này khi cần hỗ trợ.

Hạng Miễn phí còn bị giới hạn theo IP: mọi tài khoản miễn phí trên cùng một IP dùng chung một hạn mức ngày (window ip_day).

Mọi hạng có cùng một giới hạn đầu vào: 4.096 token mỗi request, là giới hạn cứng của chính mô hình. GET /v1/models trả về giá trị này ở max_input_tokens. Vượt giới hạn, response là 400 với details.type input_too_long.

Response 429 có các header sau (dùng chúng để giãn nhịp gọi):

Body của 429 nói rõ khung nào bị chạm (minute, hour, day, concurrency, ip_day):

{
  "code": "rate_limited",
  "message": "rate limit exceeded",
  "window": "minute",
  "limit": 30,
  "retry_after_seconds": 2,
  "tier": "free",
  "upgrade_url": "https://tia.8syncdev.com/pricing"
}

Ví dụ đọc base URL và key từ biến môi trường, không ghi key vào code.

export TIA_API_URL="https://staging-j97-api-9tm2.encr.app"
export TIA_API_KEY="tia_live_..."

curl -sS "$TIA_API_URL/v1/systemone" \
  -H "Authorization: Bearer $TIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":{"kenh":"zalo","goi_dich_vu":"Pro năm","tin_nhan":"Chào shop, tháng này em bị trừ tiền 2 lần cho gói Pro, 499.000đ mỗi lần, hoá đơn thứ hai vẫn đang treo. Nhờ shop hoàn lại khoản bị trừ trùng trong hôm nay giúp em, mai kế toán bên em chốt sổ rồi."},"questions":{"hoan_tien":{"type":"noul","instructions":"Khách có đang yêu cầu trả lại tiền không?","criteria":{"true":"đòi hoàn tiền, huỷ giao dịch hoặc bù tiền","false":"không đòi lại tiền"}},"doi_xu_ly":{"type":"choice","instructions":"Đội nào nên nhận ticket này?","criteria":{"thanh_toan":"hoá đơn, trừ tiền, hoàn tiền, gói cước","ky_thuat":"lỗi, sự cố, tích hợp","tai_khoan":"đăng nhập, quyền truy cập, bảo mật","ban_hang":"mua mới, nâng cấp, báo giá"}},"muc_do_gap":{"type":"score","instructions":"Ticket này gấp đến mức nào?","criteria":["để tuần sau được","bình thường, trả lời trong 2 ngày","ảnh hưởng tiền hoặc công việc hôm nay","sự cố diện rộng, rủi ro pháp lý hoặc bảo mật"]}}}'

import os, time
import requests  # pip install requests

BASE = os.environ["TIA_API_URL"]
KEY = os.environ["TIA_API_KEY"]

body = {
    "state": "Em bị trừ tiền 2 lần cho gói Pro tháng này, nhờ shop hoàn lại giúp em.",
    "questions": {
        "hoan_tien": {"type": "noul", "instructions": "Khách có yêu cầu trả lại tiền không?"},
        "muc_do_gap": {
            "type": "score",
            "instructions": "Ticket này gấp đến mức nào?",
            "criteria": ["để tuần sau được", "bình thường", "ảnh hưởng tiền hôm nay"],
        },
    },
}

for attempt in range(3):
    r = requests.post(f"{BASE}/v1/systemone", json=body, timeout=30,
                      headers={"Authorization": f"Bearer {KEY}"})
    if r.status_code not in (429, 503):
        break
    time.sleep(float(r.headers.get("Retry-After", "1")))

if r.status_code != 200:
    err = r.json()
    raise SystemExit(f"{r.status_code} {err['code']}: {err['message']}")

data = r.json()
print(data["answers"]["hoan_tien"]["noul"])    # P(có)
print(data["answers"]["muc_do_gap"]["score"])  # mức kỳ vọng, thấp nhất = 0
print(data["usage"]["cost_display"], data["balance_display"])

const BASE = process.env.TIA_API_URL;
const KEY = process.env.TIA_API_KEY;

const res = await fetch(`${BASE}/v1/systemone`, {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    state: { tieu_de: "Không thanh toán được bằng VietQR", nen_tang: "Android 3.4.1" },
    questions: {
      thanh_phan: {
        type: "choice",
        instructions: "Lỗi nằm ở thành phần nào?",
        criteria: { app_mobile: "ứng dụng Android/iOS", cong_thanh_toan: "cổng thanh toán, VietQR" },
      },
    },
  }),
});

const data = await res.json();
if (!res.ok) {
  // 400 invalid_argument, 401 unauthenticated, 402 payment_required, 429 / 503 (see Retry-After)
  throw new Error(`${res.status} ${data.code}: ${data.message}`);
}
console.log(data.answers.thanh_phan.choice, data.answers.thanh_phan.probabilities);

// npm install @typesafe-ai/sdk
// .env
//   TIA_API_URL=https://staging-j97-api-9tm2.encr.app
//   TIA_API_KEY=tia_live_...
import { TypeSafeClient, choice, noul, score } from "@typesafe-ai/sdk";

process.env.TYPESAFE_BASE_URL = process.env.TIA_API_URL;
process.env.TYPESAFE_API_KEY = process.env.TIA_API_KEY;
const client = new TypeSafeClient();

const { answers } = await client.systemOne({
  state: { tin_nhan: "Em bị trừ tiền 2 lần, nhờ shop hoàn lại giúp em." },
  questions: {
    hoan_tien: noul("Khách có yêu cầu trả lại tiền không?"),
    doi_xu_ly: choice("Đội nào nên nhận ticket?", {
      thanh_toan: "hoá đơn, trừ tiền, hoàn tiền",
      ky_thuat: "lỗi, sự cố",
    }),
    muc_do_gap: score("Gấp đến mức nào?", ["để tuần sau", "bình thường", "trong hôm nay"]),
  },
});

answers.doi_xu_ly.choice; // "thanh_toan" | "ky_thuat"

Ví dụ dưới đọc TIA_API_URL và TIA_API_KEY, rồi chuyển chúng sang biến cấu hình TYPESAFE_BASE_URL và TYPESAFE_API_KEY mà @typesafe-ai/sdk sử dụng. Ví dụ không chỉ định model, nên API trả lời bằng bản đang phục vụ, không phải ứng viên thử nghiệm TIA 1.5.

TYPESAFE_BASE_URL=https://staging-j97-api-9tm2.encr.app
TYPESAFE_API_KEY=tia_live_...