API & webhook

REST API cho developer cần tích hợp VietClaw vào hệ thống riêng. Beta trên Pro plan trở lên.

Xác thực#

Tạo API key trong Settings → Developer. Mỗi key có scope cấu hình được (read-only, run-employee, gen-image…). Truyền qua header Authorization Bearer.

bash
curl https://api.vietclaw.ai/v1/me \
  -H "Authorization: Bearer vc_live_..."

Endpoint chính#

POST /v1/chat — chat với Thư ký, stream SSE
POST /v1/employees/:id/run — kích hoạt nhân viên cụ thể
POST /v1/studio/image — gen ảnh
POST /v1/studio/video — gen video (async, trả job_id)
GET /v1/library/:file_id — tải file
GET /v1/usage — số credit đã dùng tháng này

Ví dụ chat streaming#

bash
curl -N https://api.vietclaw.ai/v1/chat \
  -H "Authorization: Bearer vc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Soạn hợp đồng dịch vụ marketing 6 tháng",
    "stream": true
  }'

Webhook events#

employee.run.completed — nhân viên chạy xong
employee.run.failed — nhân viên fail
studio.video.ready — video async ready
credit.low — < 10% credit gói còn lại
billing.payment.success / billing.payment.failed

Rate limit#

Pro: 60 req/phút, 1000 req/giờ. Business: 300 req/phút, 5000 req/giờ. Vượt → 429 + header Retry-After. Burst grace 2× trong 30 giây đầu mỗi giờ.

Lưu ý

API hiện ở Beta — schema có thể thay đổi. Mọi breaking change sẽ thông báo 30 ngày trước qua changelog và email.

Bảo mật & dữ liệu

Khắc phục sự cố