Lipsync API

Tổng Quan

Giới thiệu Lipsync API của AusyncLab cung cấp các chức năng đồng bộ hóa chuyển động môi với âm thanh. API hỗ trợ hai model AI để phù hợp với nhu cầu khác nhau về tốc độ và chất lượng.

Tính Năng Chính

Đăng ký và quản lý video gốc (miễn phí, có hiệu lực ngay)
Tạo video lipsync với chất lượng cao
Hỗ trợ hai model AI: Nova và Vega
Hỗ trợ video có hoặc không có occlusion
Theo dõi tiến trình qua polling
Thumbnail tự động cho video

So Sánh Model AI

Model	Credits mỗi giây audio	Mô tả
Nova	5,000 credits/giây	Model tiên tiến, độ chính xác cao.
Vega	8,000 credits/giây	Model chất lượng cao nhất.

Credit được tính theo thời lượng audio của video lipsync.

Model prime đã ngừng hỗ trợ. Gửi "model": "prime" sẽ nhận lỗi 422 kèm thông báo liệt kê các model còn được hỗ trợ. Tên model không phân biệt hoa thường.

Video đăng ký từ ngày 2026-09-05 (khi đăng ký trở thành miễn phí) bắt buộc phải truyền model là "nova" hoặc "vega" khi tạo lipsync; bỏ qua model sẽ nhận lỗi 400. Chỉ các video đăng ký trước đó (đã qua tiền xử lý) còn dùng được pipeline mặc định 50 credits/giây khi không truyền model.

Quick Start

Đăng ký và lấy API Key từ hệ thống.
Đăng ký video gốc thông qua endpoint /register-video — miễn phí và có hiệu lực ngay, không cần chờ xử lý.
Tạo lipsync video với audio mong muốn bằng /generate-lipsync kèm model: "nova" hoặc "vega".
Polling /generate/{video_id} cho đến khi state là SUCCEED.

Tải Lên File Audio/Video

Nếu bạn chưa có URL audio hoặc video, hãy sử dụng File Upload API để tải file lên hệ thống của chúng tôi và lấy URL.

Lưu ý quan trọng: File được tải lên qua File Upload API sẽ tự động bị xóa sau 24 giờ. Hãy đảm bảo đăng ký video hoặc tạo lipsync trước thời hạn này.

Xác Thực

API yêu cầu cung cấp API Key qua header X-API-Key. API Key phải được bảo mật và không chia sẻ công khai. Xem thêm Rate Limit.

Base URL

https://api.ausynclab.io/api/v1/lipsync

Playground

Thử nghiệm API tại: https://api.ausynclab.io/docs (opens in a new tab)

Chi Tiết Endpoints

1. Đăng Ký Video

URL: https://api.ausynclab.io/api/v1/lipsync/register-video
Phương thức: POST
Mô tả: Đăng ký một video gốc để sử dụng cho việc tạo lipsync.

Đăng ký video là miễn phí. Trước đây bước này chạy tiền xử lý trên GPU và tính khoảng 3.000 credit cho mỗi phút video; tiền xử lý đó không còn cần thiết nữa, nên không còn khoản phí này. Bạn chỉ bị trừ credit khi tạo video lipsync.

Video có hiệu lực ngay sau khi đăng ký với state là SUCCEED — không có trạng thái chờ xử lý, không có callback, nên không cần polling trước khi gọi /generate-lipsync.

Tham số Request Body:

name (tùy chọn): Tên video.
video_url (bắt buộc): URL của video gốc. Thời lượng tối đa 300 giây (5 phút); vượt quá sẽ nhận lỗi 403.
has_occlusion (tùy chọn, mặc định false): Đặt true nếu video có vật thể che khuất vùng miệng.

CURL:

curl -X 'POST' \
  'https://api.ausynclab.io/api/v1/lipsync/register-video' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sample Video",
    "video_url": "https://example.com/video.mp4",
    "has_occlusion": false
  }'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "video_id": 123
  }
}

403 Forbidden: Video dài hơn giới hạn của gói.
422 Validation Error: Dữ liệu không hợp lệ.

2. Lấy Danh Sách Video Đã Đăng Ký

URL: https://api.ausynclab.io/api/v1/lipsync/register
Phương thức: GET
Mô tả: Lấy danh sách các video đã đăng ký của người dùng.

CURL:

curl -X 'GET' \
  'https://api.ausynclab.io/api/v1/lipsync/register' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": [
    {
      "id": 123,
      "name": "Sample Video",
      "video_url": "https://example.com/video.mp4",
      "thumbnail_url": "https://example.com/thumbnail.jpg",
      "created_at": "2025-01-04T08:33:42",
      "has_occlusion": false,
      "state": "SUCCEED"
    },
    {
      "id": 124,
      "name": "Another Video",
      "video_url": "https://example.com/video2.mp4",
      "thumbnail_url": "https://example.com/thumbnail2.jpg",
      "created_at": "2025-01-04T08:30:21",
      "has_occlusion": true,
      "state": "SUCCEED"
    }
  ]
}

3. Lấy Thông Tin Chi Tiết Video Đã Đăng Ký

URL: https://api.ausynclab.io/api/v1/lipsync/register/{video_id}
Phương thức: GET
Mô tả: Lấy thông tin chi tiết của một video đã đăng ký cụ thể.

Tham số:

video_id (bắt buộc): ID của video (kiểu integer).

CURL:

curl -X 'GET' \
  'https://api.ausynclab.io/api/v1/lipsync/register/123' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": 123,
    "name": "Sample Video",
    "video_url": "https://example.com/video.mp4",
    "thumbnail_url": "https://example.com/thumbnail.jpg",
    "created_at": "2025-01-04T08:33:42",
    "has_occlusion": false,
    "state": "SUCCEED"
  }
}

404 Not Found: Video không tồn tại.

4. Xóa Video Đã Đăng Ký

URL: https://api.ausynclab.io/api/v1/lipsync/register/{video_id}
Phương thức: DELETE
Mô tả: Xóa một video đã đăng ký theo ID.

Tham số:

video_id (bắt buộc): ID của video đã đăng ký (kiểu integer).

CURL:

curl -X 'DELETE' \
  'https://api.ausynclab.io/api/v1/lipsync/register/123' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": 123,
    "success": true
  }
}

404 Not Found: Video không tồn tại.

5. Tạo Video Lipsync

URL: https://api.ausynclab.io/api/v1/lipsync/generate-lipsync
Phương thức: POST
Mô tả: Tạo video lipsync từ video đã đăng ký và file âm thanh.

Tham số Request Body:

name (tùy chọn): Tên video lipsync.
registered_video_id (bắt buộc): ID của video đã đăng ký.
audio_url (bắt buộc): URL của file âm thanh.
model ("nova" | "vega"): Model AI. Bắt buộc với video đăng ký từ 2026-09-05; bỏ qua sẽ nhận lỗi 400. Credits được tính theo bảng ở phần So Sánh Model AI.
callback_url (tùy chọn): Hiện được chấp nhận nhưng không gửi thông báo với model Nova/Vega. Hãy polling /generate/{video_id}.

CURL:

curl -X 'POST' \
  'https://api.ausynclab.io/api/v1/lipsync/generate-lipsync' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Lipsync Video",
    "registered_video_id": 123,
    "audio_url": "https://example.com/audio.wav",
    "model": "nova"
  }'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "video_id": 456,
    "thumbnail_url": null
  }
}

400 Bad Request: Thiếu model với video đăng ký mới (thông báo: Send "model": "nova" or "vega" to generate it.).
404 Not Found: Video đã đăng ký không tồn tại.
422 Validation Error: model không được hỗ trợ (bao gồm prime) hoặc dữ liệu không hợp lệ.

6. Lấy Danh Sách Video Lipsync Đã Tạo

URL: https://api.ausynclab.io/api/v1/lipsync/generate
Phương thức: GET
Mô tả: Lấy danh sách các video lipsync đã được tạo bởi người dùng.

CURL:

curl -X 'GET' \
  'https://api.ausynclab.io/api/v1/lipsync/generate' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": [
    {
      "id": 456,
      "registered_video_id": 123,
      "name": "Lipsync Video",
      "audio_url": "https://example.com/audio.wav",
      "output_video_url": "https://cdn.example.com/lipsync-output/video456.mp4",
      "thumbnail_url": "https://cdn.example.com/lipsync-thumbnails/thumb456.jpg",
      "created_at": "2025-01-04T08:35:12",
      "state": "SUCCEED"
    },
    {
      "id": 457,
      "registered_video_id": 124,
      "name": "Another Lipsync",
      "audio_url": "https://example.com/audio2.mp3",
      "output_video_url": null,
      "thumbnail_url": null,
      "created_at": "2025-01-04T08:32:45",
      "state": "IN_PROGRESS"
    }
  ]
}

7. Lấy Thông Tin Chi Tiết Video Lipsync

URL: https://api.ausynclab.io/api/v1/lipsync/generate/{video_id}
Phương thức: GET
Mô tả: Lấy thông tin chi tiết của một video lipsync cụ thể. Polling endpoint này cho đến khi state là SUCCEED hoặc một trạng thái lỗi.

Tham số:

video_id (bắt buộc): ID của video lipsync (kiểu integer).

CURL:

curl -X 'GET' \
  'https://api.ausynclab.io/api/v1/lipsync/generate/456' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": 456,
    "registered_video_id": 123,
    "name": "Lipsync Video",
    "audio_url": "https://example.com/audio.wav",
    "output_video_url": "https://cdn.example.com/lipsync-output/video456.mp4",
    "thumbnail_url": "https://cdn.example.com/lipsync-thumbnails/thumb456.jpg",
    "created_at": "2025-01-04T08:35:12",
    "state": "SUCCEED"
  }
}

404 Not Found: Video lipsync không tồn tại.

8. Xóa Video Lipsync

URL: https://api.ausynclab.io/api/v1/lipsync/generate/{video_id}
Phương thức: DELETE
Mô tả: Xóa một video lipsync cụ thể theo ID.

Tham số:

video_id (bắt buộc): ID của video lipsync (kiểu integer).

CURL:

curl -X 'DELETE' \
  'https://api.ausynclab.io/api/v1/lipsync/generate/456' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": 456,
    "success": true
  }
}

404 Not Found: Không tìm thấy video lipsync.

Trạng thái Video

Các trạng thái có thể của video (state) trong hệ thống:

state	Mô tả
`WAITING_IN_QUEUE`	Đang chờ xử lý
`IN_PROGRESS`	Đang tạo video
`MERGING`	Đang ghép các phân đoạn
`SUCCEED`	Hoàn thành, `output_video_url` sẵn sàng
`INTERNAL_ERROR`	Lỗi xử lý
`ABORTED`	Job bị hủy
`TIME_OUT`	Job không hoàn thành trong thời gian cho phép

Video đã đăng ký luôn ở trạng thái SUCCEED ngay sau khi đăng ký.

Lưu ý quan trọng

Quy trình sử dụng: Đăng ký video gốc qua /register-video, sau đó tạo lipsync bằng /generate-lipsync với registered_video_id và model là "nova" hoặc "vega". Chi phí: Nova 5,000 credits/giây, Vega 8,000 credits/giây audio.
Theo dõi kết quả: Polling GET /generate/{video_id}; API hiện không gửi callback cho các job Nova/Vega.
Model prime đã ngừng hỗ trợ: mọi request truyền "model": "prime" sẽ trả về lỗi 422.

Voice Denoiser Instant Avatar