Lipsync

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
  • Tạo video lipsync với chất lượng cao
  • Hỗ trợ hai model AI: Prime và Nova
  • Hỗ trợ video có hoặc không có occlusion
  • Callback URL để theo dõi tiến trình xử lý
  • Thumbnail tự động cho video

So Sánh Model AI

ModelCredits mỗi giâyMô tả
Prime50 credits/giâyModel chuẩn của AusyncLab. Yêu cầu đăng ký video trước qua /register-video.
Nova5,000 credits/giâyModel tiên tiến, độ chính xác cao hơn. Không cần đăng ký video, chỉ cần truyền URL trực tiếp.

Quick Start — Model Prime

  1. Đăng ký và lấy API Key từ hệ thống.
  2. Đăng ký video gốc thông qua endpoint /register-video.
  3. Chờ video được xử lý (theo dõi qua callback hoặc polling).
  4. Tạo lipsync video với audio mong muốn bằng /generate-lipsync.

Quick Start — Model Nova

  1. Đăng ký và lấy API Key từ hệ thống.
  2. Tạo lipsync video trực tiếp bằng /generate-lipsync-v2 với video_url, audio_url và model: "nova" (không cần đăng ký video).

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.

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.

Body:

{
  "name": "Sample Video", // Tên video (tùy chọn)
  "video_url": "https://example.com/video.mp4", // URL của video gốc (bắt buộc)
  "callback_url": "https://your-callback-url.com" // URL được gọi khi job hoàn thành (tùy chọn)
}

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",
    "callback_url": "https://your-callback-url.com"
  }'

Phản hồi:

  • 200 OK
{
  "status": 200,
  "result": {
    "video_id": 123
  }
}
  • 404 Not Found: Không thể đăng ký video.
  • 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",
      "state": "COMPLETED"
    },
    {
      "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",
      "state": "PROCESSING"
    }
  ]
}
  • 404 Not Found: Không tìm thấy danh sách video.

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",
    "state": "COMPLETED"
  }
}
  • 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/{id}
Phương thức: DELETE
Mô tả: Xóa một video đã đăng ký cụ thể theo ID.

Tham số:

  • id (bắt buộc): ID của video (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,
    "message": "The registered video is successfully deleted."
  }
}
  • 404 Not Found: Không tìm thấy video.

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.

Body:

{
  "name": "Lipsync Video", // Tên video lipsync (tùy chọn)
  "registered_video_id": 123, // ID của video đã đăng ký (bắt buộc)
  "audio_url": "https://example.com/audio.wav", // URL của file âm thanh (bắt buộc)
  "callback_url": "https://your-callback-url.com" // URL được gọi khi job hoàn thành (tùy chọn)
}

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",
    "callback_url": "https://your-callback-url.com"
  }'

Phản hồi:

  • 200 OK
{
  "status": 200,
  "result": {
    "video_id": 456
  }
}
  • 404 Not Found: Không thể tạo video lipsync.
  • 422 Validation Error: Dữ liệu không hợp lệ.

5b. Tạo Video Lipsync Nhanh (Model Nova)

URL: https://api.ausynclab.io/api/v1/lipsync/generate-lipsync-v2 Phương thức: POST Mô tả: Tạo video lipsync trực tiếp từ URL video và URL âm thanh — không cần đăng ký video trước. Sử dụng model Nova cho độ chính xác cao nhất.

Body:

{
  "name": "Lipsync Video", // Tên video lipsync (tùy chọn)
  "video_url": "https://example.com/video.mp4", // URL video nguồn (bắt buộc)
  "audio_url": "https://example.com/audio.wav", // URL file âm thanh (bắt buộc)
  "model": "nova", // Model AI: "prime" hoặc "nova" (mặc định: "prime")
  "sync_mode": "loop", // Chế độ đồng bộ: "cut_off" | "loop" | "bounce" | "silence" | "remap" (mặc định: "loop")
  "callback_url": "https://your-callback-url.com" // URL nhận thông báo khi hoàn thành (tùy chọn)
}

CURL:

curl -X 'POST' \
  'https://api.ausynclab.io/api/v1/lipsync/generate-lipsync-v2' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Lipsync Video",
    "video_url": "https://example.com/video.mp4",
    "audio_url": "https://example.com/audio.wav",
    "model": "nova",
    "sync_mode": "loop",
    "callback_url": "https://your-callback-url.com"
  }'

Phản hồi:

  • 200 OK
{
  "status": 200,
  "result": {
    "video_id": 789,
    "operation_id": "abc123-...",
    "message": "Your lipsync request is being processed"
  }
}
  • 404 Not Found: Không thể tạo video lipsync.
  • 422 Validation Error: Dữ liệu không hợp lệ.

Lưu ý: Model Nova chi phí 5,000 credits mỗi giây âm thanh. Sau khi gửi yêu cầu thành công, bạn có thể theo dõi kết quả qua callback_url hoặc polling endpoint /generate/{video_id}.

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://ausync-h8f7gketarb6a2dt.z01.azurefd.net/lipsync-output/video456.mp4",
      "thumbnail_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/lipsync-thumbnails/thumb456.jpg",
      "created_at": "2025-01-04T08:35:12",
      "state": "COMPLETED"
    },
    {
      "id": 457,
      "registered_video_id": 124,
      "name": "Another Lipsync",
      "audio_url": "https://example.com/audio2.mp3",
      "output_video_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/lipsync-output/video457.mp4",
      "thumbnail_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/lipsync-thumbnails/thumb457.jpg",
      "created_at": "2025-01-04T08:32:45",
      "state": "PROCESSING"
    }
  ]
}
  • 404 Not Found: Không tìm thấy danh sách video lipsync.

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ể.

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://ausync-h8f7gketarb6a2dt.z01.azurefd.net/lipsync-output/video456.mp4",
    "thumbnail_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/lipsync-thumbnails/thumb456.jpg",
    "created_at": "2025-01-04T08:35:12",
    "state": "COMPLETED"
  }
}
  • 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/{id}
Phương thức: DELETE
Mô tả: Xóa một video lipsync cụ thể theo ID.

Tham số:

  • 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,
    "message": "The generated video is successfully deleted."
  }
}
  • 404 Not Found: Không tìm thấy video lipsync.

Callback Payload

Callback cho Video Đăng Ký

Khi job "Đăng ký Video" hoàn thành, API sẽ gửi thông báo đến callback_url với payload:

Nội dung Payload:

  • video_id: ID duy nhất của video đã được đăng ký.
  • credits_used: Số lượng tín dụng đã sử dụng để xử lý công việc này.
  • status: Trạng thái của công việc ("COMPLETED", "FAILED", "PROCESSING").
  • message: Thông báo từ hệ thống về trạng thái xử lý.

Ví dụ

{
  "video_id": 123,
  "credits_used": 5,
  "status": "COMPLETED",
  "message": "Your video registration is completed successfully"
}

Callback cho Video Lipsync

Khi job "Tạo Video Lipsync" hoàn thành, API sẽ gửi thông báo đến callback_url với payload:

Nội dung Payload:

  • video_id: ID duy nhất của video lipsync đã được tạo.
  • video_url: Liên kết để tải xuống video lipsync đã được hệ thống tạo.
  • credits_used: Số lượng tín dụng đã sử dụng để xử lý công việc này.
  • status: Trạng thái của công việc ("COMPLETED", "FAILED", "PROCESSING").
  • message: Thông báo từ hệ thống về trạng thái xử lý.

Ví dụ

{
  "video_id": 456,
  "video_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/lipsync-output/video456.mp4",
  "credits_used": 15,
  "status": "COMPLETED",
  "message": "Your lipsync video is generated successfully"
}

Lưu ý: Người dùng cần triển khai endpoint để nhận và xử lý payload này.

Trạng thái Video

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

  • PROCESSING: Video đang được xử lý
  • COMPLETED: Video đã được xử lý thành công
  • FAILED: Video xử lý thất bại
  • PENDING: Video đang chờ xử lý

Lưu ý quan trọng

Quy trình sử dụng:

  • Model Prime: Bạn cần đăng ký video gốc trước qua /register-video, sau đó tạo lipsync bằng /generate-lipsync với registered_video_id. Chi phí: 50 credits/giây.
  • Model Nova: Không cần đăng ký video trước. Truyền video_url và audio_url trực tiếp vào /generate-lipsync-v2. Chi phí: 5,000 credits/giây.
Voice DenoiserInstant Avatar