Video API

AVCaption phát hành REST API để quản lý video bằng code. Có sẵn ở gói Enterprise; truy cập preview cho Premium theo yêu cầu.

Xác thực

Hai cách:

Bearer token (JWT) — phát hành khi đăng nhập, gửi qua header Authorization: Bearer <token>. Dùng cho phiên dashboard đã xác thực.

API key — sinh ở trang settings. Định dạng avc_<64 ký tự hex>. Gửi qua header X-API-Key: <key> hoặc query param ?api_key=<key>. Hữu ích cho server-to-server.

Endpoint

GET    /api/v1/videos               Liệt kê video (phân trang, ?page=1)
GET    /api/v1/videos/:id           Metadata video + embed token
POST   /api/v1/upload               Upload trực tiếp (file nhỏ)
POST   /api/v1/upload/init          Bắt đầu phiên upload chunk
POST   /api/v1/upload/chunk         Upload một chunk
POST   /api/v1/upload/complete      Kết thúc upload chunk
PUT    /api/v1/videos/:id           Cập nhật title, allowed_domains
DELETE /api/v1/videos/:id           Xoá video
GET    /api/v1/stats                Thống kê tài khoản: tổng video, lượt xem, dung lượng
GET    /api/v1/embed/:token         Metadata embed công khai (không cần auth cho video công khai)
POST   /api/v1/videos/:id/subtitles Upload track phụ đề (Enterprise)
GET    /api/v1/presets              Liệt kê preset player (Enterprise)
POST   /api/v1/presets              Tạo preset player (Enterprise)

Pattern upload theo chunk

# Bước 1: init
curl -X POST https://dashboard.avcaption.com/api/v1/upload/init \
  -H "X-API-Key: avc_..." \
  -d '{"filename":"course-lesson-1.mp4","size":1234567890,"title":"Lesson 1"}'
# Trả về: {"upload_id":"abc123","chunk_size":5242880}

# Bước 2: upload chunk (có thể song song)
curl -X POST https://dashboard.avcaption.com/api/v1/upload/chunk \
  -H "X-API-Key: avc_..." \
  -H "X-Upload-ID: abc123" \
  -H "X-Chunk-Index: 0" \
  --data-binary @chunk-0.bin
# ...lặp lại cho mỗi chunk

# Bước 3: complete
curl -X POST https://dashboard.avcaption.com/api/v1/upload/complete \
  -H "X-API-Key: avc_..." \
  -d '{"upload_id":"abc123"}'
# Trả về: {"video_id":"...","embed_token":"...","status":"processing"}

Webhook event (Enterprise)

Đăng ký event tới bất kỳ endpoint HTTPS nào:

• video.uploaded — upload chunk hoàn tất
• video.encoded — encode xong, sẵn sàng phát
• video.failed — encode thất bại (kèm chi tiết lỗi)
• view.threshold — số người xem vượt ngưỡng cấu hình
• subtitle.translated — dịch AI hoàn tất

Payload webhook ký bằng HMAC-SHA256.

Giới hạn tốc độ

• Endpoint đọc (list, get): 300 req/phút mỗi API key
• Endpoint ghi (update, delete): 60 req/phút
• Endpoint upload: 60 req/phút trên init/complete; bản thân các chunk không bị giới hạn
• Stats: 60 req/phút

Giới hạn tự nâng cho khách Enterprise; liên hệ sales để có mức tuỳ chỉnh.

Định dạng lỗi

{
  "error": "thông báo lỗi đọc được",
  "code": "machine_readable_error_code",
  "request_id": "x-request-id-for-support-tickets"
}

Bắt đầu

REST API có trong Enterprise. Sinh API key ở dashboard Settings → API Keys. Mở tài khoản Enterprise và chạy thử một call upload chunked với một file nguồn thật trước khi bạn script bulk migration. Triển khai API-driven phổ biến: host video cho LMS, video cho khách của agency, sản phẩm số.