Instant Avatar API

Tổng Quan

Giới thiệu
Instant Avatar API của AusyncLab cho phép tạo video avatar biết nói từ hình ảnh tĩnh. Sử dụng công nghệ AI tiên tiến để tạo chuyển động môi, biểu cảm và cử động đầu đồng bộ với âm thanh.

Tính Năng Chính

Tạo avatar từ hình ảnh tĩnh (PNG, JPG)
Đồng bộ chuyển động môi với audio
Tạo biểu cảm và cử động đầu tự nhiên
Hỗ trợ nhiều định dạng audio input
Callback URL để theo dõi tiến trình

Quick Start

Đăng ký và lấy API Key từ hệ thống.
Tải lên hình ảnh avatar thông qua endpoint /register.
Tạo video từ avatar và file audio.
Nhận thông báo qua callback khi video hoàn thành.

Tải Lên File Audio

Nếu bạn chưa có URL audio, 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 tạo avatar video 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 URLs

https://api.ausynclab.io/api/v1/avatars
https://api.ausynclab.io/api/v1/avatar-videos

Playground

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

Chi Tiết Endpoints

1. Tạo Avatar

URL: https://api.ausynclab.io/api/v1/avatars/register
Phương thức: POST
Mô tả: Đăng ký một avatar tùy chỉnh mới.

Tham số Query:

name (bắt buộc): Tên của avatar.

Body:
Tải lên file avatar dưới dạng multipart/form-data.

CURL:

curl -X 'POST' \
  'http://api.ausynclab.io/api/v1/avatars/register?name=demo' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'Content-Type: multipart/form-data' \
  -F 'avatar_file=@sample.png;type=image/png

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": "123e4567-e89b-12d3-a456-426614174001"
  }
}

404 Not Found: Không thể tạo avatar.

2. Lấy Thông Tin Chi Tiết Avatar

URL: https://api.ausynclab.io/api/v1/avatars/{avatar_id}
Phương thức: GET
Mô tả: Lấy thông tin chi tiết của một avatar cụ thể.

Tham số:

avatar_id (bắt buộc): ID của avatar (kiểu UUID).

CURL:

curl -X 'GET' \
  'http://api.ausynclab.io/api/v1/avatars/a9t8f34d-b6f4-4c5f-a003-0f5eceee6b4c' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": "a9t8f34d-b6f4-4c5f-a003-0f5eceee6b4c",
    "name": "Avatar 1",
    "avatar_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/avatar/sample.jpeg",
    "created_at": "2025-01-04T08:33:42"
  }
}

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

3. Lấy Danh Sách Avatar

URL: https://api.ausynclab.io/api/v1/avatars/list
Phương thức: GET
Mô tả: Lấy danh sách các avatar của người dùng.

CURL:

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

Phản hồi:

200 OK

{
  "status": 200,
  "result": [
    {
      "id": "a9t8f34d-b6f4-4c5f-a003-0f5eceee6b4c",
      "name": "Avatar 1",
      "avatar_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/avatar/sample.jpeg",
      "created_at": "2025-01-04T08:33:42"
    },
    {
      "id": "2a9ebd5a-7824-48d3-9f01-1a243f5bed75",
      "name": "Avatar 2",
      "avatar_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/avatar/sample2.png",
      "created_at": "2025-01-04T08:30:21"
    },
    ...
  ]
}

404 Not Found: Không tìm thấy danh sách avatar.

4. Xóa Avatar

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

Tham số:

avatar_id (bắt buộc): ID của avatar (kiểu UUID).

CURL:

curl -X 'DELETE' \
  'https://api.ausynclab.io/api/v1/avatars/a8b8f34d-b6f4-4c5f-a003-0f5eceee6b4c' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": "a8b8f34d-b6f4-4c5f-a003-0f5eceee6b4c",
    "message": "The avatar is successfully deleted."
  }
}

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

5. Tạo Avatar Video

URL: https://api.ausynclab.io/api/v1/avatar-videos/generate Phương thức: POST Mô tả: Tạo video từ avatar và file âm thanh. Hỗ trợ hai chế độ: avatar tùy chỉnh (tải lên ảnh) hoặc avatar có sẵn (avatar_style).

Tham số Body:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`name`	string	✅	—	Tên video
`audio_url`	string	✅	—	URL file âm thanh (WAV, MP3)
`avatar_id`	UUID	❌	—	ID avatar tùy chỉnh (dùng khi không dùng `avatar_style`)
`model`	string	❌	`"spark"`	Model AI: `spark`, `glow`, `apex`, `wren`, `sparrow`
`avatar_style`	string	❌	—	Phong cách avatar có sẵn (dùng với model `sparrow`)
`callback_url`	string	❌	—	URL nhận thông báo khi video hoàn thành

Lưu ý: Phải cung cấp avatar_id hoặc avatar_style. Model sparrow dùng với avatar_style; các model khác dùng với avatar_id.

Ví dụ 1 — Avatar có sẵn (model sparrow, mặc định):

curl -X 'POST' \
  'https://api.ausynclab.io/api/v1/avatar-videos/generate' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key' \
  -d '{
    "name": "Sample Video",
    "avatar_style": "linh-phong-cach",
    "audio_url": "https://example.com/audio.wav",
    "callback_url": "https://your-callback-url.com"
  }'

Ví dụ 2 — Avatar tùy chỉnh (model spark):

curl -X 'POST' \
  'https://api.ausynclab.io/api/v1/avatar-videos/generate' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key' \
  -d '{
    "name": "Sample Video",
    "avatar_id": "123e4567-e89b-12d3-a456-426614174000",
    "audio_url": "https://example.com/audio.wav",
    "model": "spark",
    "callback_url": "https://your-callback-url.com"
  }'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": "123e4567-e89b-12d3-a456-426614174001"
  }
}

404 Not Found: Không thể tạo video.
422 Validation Error: Dữ liệu không hợp lệ.

Danh Sách Avatar Có Sẵn (`avatar_style`)

Dùng với model sparrow. Chi phí: 500 credits/giây.

`avatar_style`	Tên hiển thị
`linh-phong-cach`	Linh - Phong Cách
`linh-cuon-hut`	Linh - Cuốn Hút
`linh`	Linh
`linh-tinh-te`	Linh - Tinh Tế
`minh-phong-cach`	Minh - Phong Cách
`minh-cuon-hut`	Minh - Cuốn Hút
`ngoc-phong-cach`	Ngọc - Phong Cách
`ngoc-cuon-hut`	Ngọc - Cuốn Hút
`hoa-phong-cach`	Hoa - Phong Cách
`hoa-cuon-hut`	Hoa - Cuốn Hút
`hoa-song-dong`	Hoa - Sống Động
`thanh-tu-tin`	Thanh - Tự Tin
`thanh-song-dong`	Thanh - Sống Động
`lan-cuon-hut`	Lan - Cuốn Hút
`lan-tinh-te`	Lan - Tinh Tế
`nam-phong-cach`	Nam - Phong Cách
`nam-cuon-hut`	Nam - Cuốn Hút
`nam`	Nam
`nam-tinh-te`	Nam - Tinh Tế
`nu-cuon-hut`	Nữ - Cuốn Hút
`nu-song-dong`	Nữ - Sống Động
`nu`	Nữ
`nu-tinh-te`	Nữ - Tinh Tế

Bảng So Sánh Model

Model	Credits/giây	Thời lượng tối đa	Avatar
`sparrow`	500	Không giới hạn	Avatar có sẵn (`avatar_style`)
`wren`	6,000	30 giây	Avatar tùy chỉnh
`apex`	11,500	30 giây	Avatar tùy chỉnh
`glow`	14,000	30 giây	Avatar tùy chỉnh
`spark`	15,000	Không giới hạn	Avatar tùy chỉnh

6. Lấy Thông Tin Chi Tiết Avatar Video

URL: https://api.ausynclab.io/api/v1/avatar-videos/{video_id}
Phương thức: GET
Mô tả: Lấy thông tin chi tiết của một avatar cụ thể.

Tham số:

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

CURL:

curl -X 'GET' \
  'http://api.ausynclab.io/api/v1/avatar-videos/fda2b68f-8707-404a-9ad8-c78d60a41b64' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": "fda2b68f-8707-404a-9ad8-c78d60a41b64",
    "name": "Video 1",
    "video_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/talking-avatar-video-output/sample.jpeg.mp4",
    "created_at": "2025-01-04T08:33:49",
    "state": "SUCCEED"
  }
}

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

7. Lấy Danh Sách Avatar Video

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

CURL:

curl -X 'GET' \
  'http://api.ausynclab.io/api/v1/avatar-videos/list' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": [
    {
      "id": "fda2b68f-8707-404a-9ad8-c78d60a41b64",
      "name": "Video 1",
      "video_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/talking-avatar-video-output/sample1.jpeg.mp4",
      "created_at": "2025-01-04T08:33:49",
      "state": "SUCCEED"
    },
    {
      "id": "32cb52e6-89fa-43a6-a3df-1508c62f76fd",
      "name": "Video 2",
      "video_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/talking-avatar-video-output/sample2.png.mp4",
      "created_at": "2025-01-04T08:30:31",
      "state": "SUCCEED"
    },
    ...
  ]
}

404 Not Found: Không tìm thấy danh sách video.

8. Xóa Video

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

Tham số:

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

CURL:

curl -X 'DELETE' \
  'https://api.ausynclab.io/api/v1/avatar-video/a8b8f34d-b6f4-4c5f-a003-0f5eceee6b4c' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "id": "a8b8f34d-b6f4-4c5f-a003-0f5eceee6b4c",
    "message": "The video is successfully deleted."
  }
}

Callback Payload

Khi job "Tạo Avatar 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 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 ("SUCCEED", "FAILED").
video_url: Liên kết để tải xuống video đã được hệ thống tạo.
message: Thông báo từ hệ thống về trạng thái xử lý.

Ví dụ

{
  "video_id": "123e4567-e89b-12d3-a456-426614174001",
  "credits_used": 10,
  "status": "SUCCEED",
  "video_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/talking-avatar-video-output/sample2.png.mp4",
  "message": "Your video is generated successfully"
}

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

Lipsync Rate Limit

Instant Avatar API

Tổng Quan

Tải Lên File Audio

Xác Thực

Base URLs

Playground

Chi Tiết Endpoints

1. Tạo Avatar

2. Lấy Thông Tin Chi Tiết Avatar

3. Lấy Danh Sách Avatar

4. Xóa Avatar

5. Tạo Avatar Video

Danh Sách Avatar Có Sẵn (avatar_style)

Bảng So Sánh Model

6. Lấy Thông Tin Chi Tiết Avatar Video

7. Lấy Danh Sách Avatar Video

8. Xóa Video

Callback Payload

Danh Sách Avatar Có Sẵn (`avatar_style`)