REST API v1 · Chuẩn JSON

Tài Liệu Tích Hợp API Dành Cho Khách Hàng & Đại Lý

Tích hợp toàn bộ 14 tính năng Tạo Ảnh & Video AI vào ứng dụng, website hoặc công cụ tự động của bạn.

Đăng nhập lấy Khóa API

1. Xác thực & Đường dẫn gốc (Base URL)

Mọi yêu cầu tới https://tavvideo.pro/api/v1/* đều bắt buộc đính kèm tiêu đề xác thực Bearer Token do bạn tạo tại trang Khóa API:

Authorization: Bearer <API_TOKEN_CỦA_BẠN>
Accept: application/json
Content-Type: application/json

Giới hạn tốc độ mặc định: 60 yêu cầu / phút trên mỗi tài khoản. Mọi mức phí đều được tính bằng Đồng Việt Nam (VND) và tự động hoàn tiền 100% nếu đơn gặp lỗi xử lý.

GET /api/v1/models Lấy danh sách tính năng, dòng máy & giá bán

curl -X GET "https://tavvideo.pro/api/v1/models" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

GET /api/v1/balance Tra cứu số dư ví VND & hạng chiết khấu

curl -X GET "https://tavvideo.pro/api/v1/balance" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Phản hồi mẫu:
{
  "balance": 245000,
  "currency": "VND",
  "tier": {
    "name": "Bạc",
    "discount_percent": 5
  }
}

POST /api/v1/generations Gửi yêu cầu tạo Ảnh / Video AI mới

Hỗ trợ gửi kèm khóa idempotency_key để chống trừ tiền trùng khi thử lại kết nối mạng.

curl -X POST "https://tavvideo.pro/api/v1/generations" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_code": "text_to_video",
    "model_code": "video-pro",
    "prompt": "Người mẫu cầm chai nước hoa bước đi dưới ánh hoàng hôn 4K",
    "options": {
      "aspect_ratio": "16:9",
      "duration": 5,
      "resolution": "1080p"
    },
    "idempotency_key": "order-unique-001"
  }'

# Phản hồi mẫu (201 Created):
{
  "uuid": "9d8a12b4-5678-4c90-abcd-1234567890ef",
  "status": "pending",
  "price_charged": 15000,
  "balance_after": 230000
}

GET /api/v1/generations/{uuid} Kiểm tra trạng thái đơn & nhận link tải kết quả

Các trạng thái trả về: pending (Đang xếp hàng), processing (Đang tạo), completed (Hoàn thành), failed (Thất bại – đã hoàn tiền). Đường dẫn tải tệp kết quả luôn có dạng https://tavvideo.pro/media/{uuid}.

curl -X GET "https://tavvideo.pro/api/v1/generations/9d8a12b4-5678-4c90-abcd-1234567890ef" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Phản hồi khi hoàn thành:
{
  "uuid": "9d8a12b4-5678-4c90-abcd-1234567890ef",
  "status": "completed",
  "progress": 100,
  "media_url": "https://tavvideo.pro/media/9d8a12b4-5678-4c90-abcd-1234567890ef",
  "download_url": "https://tavvideo.pro/media/9d8a12b4-5678-4c90-abcd-1234567890ef?download=1"
}

GET /api/v1/generations Danh sách lịch sử đơn có phân trang

curl -X GET "https://tavvideo.pro/api/v1/generations?status=completed&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"