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: Nova và Vega
  • 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ả
Nova5,000 credits/giâyModel tiên tiến, độ chính xác cao.
Vega8,000 credits/giâyModel chất lượng cao nhất.

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.

Nếu bạn không truyền model, request giữ nguyên hành vi cũ (pipeline mặc định, 50 credits/giây) — các tích hợp hiện tại không bị ảnh hưởng.

Quick Start — Dùng video đã đăng ký

  1. Đăng ký và lấy API Key từ hệ thống.
  2. Đă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ý.
  3. Tạo lipsync video với audio mong muốn bằng /generate-lipsync.

Quick Start — Không cần đăng ký video

  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" hoặc "vega" (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.

Đă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ý — không còn trạng thái chờ xử lý, nên không cần polling hay callback trước khi gọi /generate-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" // (tùy chọn — đăng ký hoàn tất ngay, không còn job để chờ)
}

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. 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ố model là tùy chọn. Bỏ qua để dùng pipeline mặc định (50 credits/giây, đúng như trước đây). Truyền "nova" hoặc "vega" để dùng model tương ứng — khi đó credits được tính theo bảng ở phần So Sánh Model AI.

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)
  "model": "nova", // Model AI: "nova" | "vega" (tùy chọn — bỏ qua để dùng pipeline mặc định)
  "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ệ.

4b. Tạo Video Lipsync Nhanh (Nova / Vega)

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. Mặc định dùng model Nova; truyền "vega" cho chất lượng 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: "nova" | "vega" (mặc định: "nova")
  "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}.

5. 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://ausyncdev.blob.core.windows.net/lipsync-output/video456.mp4",
      "thumbnail_url": "https://ausyncdev.blob.core.windows.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://ausyncdev.blob.core.windows.net/lipsync-output/video457.mp4",
      "thumbnail_url": "https://ausyncdev.blob.core.windows.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.

6. 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://ausyncdev.blob.core.windows.net/lipsync-output/video456.mp4",
    "thumbnail_url": "https://ausyncdev.blob.core.windows.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.

7. 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://ausyncdev.blob.core.windows.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:

  • Dùng video đã đăng ký: Đăng ký video gốc qua /register-video, sau đó tạo lipsync bằng /generate-lipsync với registered_video_id. Bỏ qua model để dùng pipeline mặc định (50 credits/giây), hoặc truyền "nova" / "vega" để dùng model tương ứng.
  • Không cần đăng ký video: Truyền video_url và audio_url trực tiếp vào /generate-lipsync-v2 kèm model. Chi phí: Nova 5,000 credits/giây, Vega 8,000 credits/giây.
  • Model prime đã ngừng hỗ trợ: mọi request truyền "model": "prime" sẽ trả về lỗi 422.
Voice DenoiserInstant Avatar