Gọi trợ lý từ ứng dụng của bạn thế nào?
Copee API cho máy chủ của ứng dụng khác (Smail, web bán hàng, công cụ nội bộ) gửi việc cho trợ lý bạn đã tạo trên ai.copee.vn. Trợ lý vẫn chạy bằng khoá mô hình AI của bạn. Mỗi lần gọi thành công tính một lượt giao việc của gói.
Xác thực bằng gì?
Tạo khoá ở Bảng điều khiển → API. Khoá có dạng cpk_…, chỉ hiện một lần. Gửi kèm mọi yêu cầu:
Authorization: Bearer cpk_…
Chỉ dùng khoá ở máy chủ. Đừng đặt khoá trong JavaScript chạy trên trình duyệt hay trong app điện thoại — ai mở mã ra là thấy khoá. Lộ khoá thì bấm "Thu hồi" và tạo khoá mới.
Khoá có thể giới hạn chỉ gọi một số trợ lý. Mỗi khoá tối đa 20 lần gọi mỗi phút.
Gửi việc cho trợ lý?
POST https://ai.copee.vn/v1/assistants/{assistant_id}/responses
Content-Type: application/json
{ "input": "Viết 3 câu giới thiệu giày chạy bộ cho khách nữ" }
Mã trợ lý (tl_…) xem ở trang trợ lý. Yêu cầu chờ tới khi trợ lý làm xong (thường 5–60 giây), đặt thời gian chờ phía bạn ít nhất 120 giây.
Trả về khi thành công:
{
"id": "tv_…",
"status": "completed",
"output": "…nội dung trợ lý viết…",
"duration_ms": 8421,
"request_id": "req_…"
}
Xem thông tin trợ lý?
GET https://ai.copee.vn/v1/assistants/{assistant_id}
{ "id": "tl_…", "name": "Soạn bài", "goal": "…", "status": "hoat-dong", "request_id": "req_…" }
Xem hạn mức?
GET https://ai.copee.vn/v1/usage
{ "plan": "starter", "expires_at": "2026-11-29T…", "tasks_used": 12, "tasks_limit": 100, "request_id": "req_…" }
Lỗi trả về thế nào?
{ "error": { "code": "quota_exceeded", "message": "…lời giải thích tiếng Việt…" }, "request_id": "req_…" }
| HTTP | code | Nghĩa là |
|---|---|---|
| 400 | invalid_request | Thiếu input hoặc dữ liệu không phải JSON |
| 401 | unauthorized | Sai khoá, thiếu khoá, hoặc khoá đã thu hồi |
| 402 | quota_exceeded | Chưa có gói hoặc đã hết lượt. Không tự tính thêm tiền |
| 404 | not_found | Không có trợ lý này, hoặc khoá không được phép gọi nó |
| 409 | assistant_disabled | Trợ lý đang tắt |
| 412 | model_key_missing | Chủ trợ lý chưa nhập khoá mô hình AI |
| 424 | model_provider_error | OpenAI/Anthropic từ chối (khoá hết tiền, sai mô hình…). Không tính lượt |
| 429 | rate_limited | Gọi quá 20 lần/phút với một khoá |
| 502 / 503 | internal_error / busy | Lỗi hoặc quá tải phía Copee. Không tính lượt, thử lại sau |
Gửi kèm request_id khi cần hỗ trợ: hoanglongteam.com/bio