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
Theo dõi tiến trình qua polling

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.
Polling endpoint chi tiết video cho đến khi state là SUCCEED.

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. Xem thêm Rate Limit.

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' \
  'https://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"
  }
}

400 Bad Request: File không phải ảnh ({"error": "Only image files are allowed."}).

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' \
  'https://api.ausynclab.io/api/v1/avatars/a9b8f34d-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": "a9b8f34d-b6f4-4c5f-a003-0f5eceee6b4c",
    "name": "Avatar 1",
    "avatar_url": "https://ausyncdev.blob.core.windows.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": "a9b8f34d-b6f4-4c5f-a003-0f5eceee6b4c",
      "name": "Avatar 1",
      "avatar_url": "https://ausyncdev.blob.core.windows.net/avatar/sample.jpeg",
      "created_at": "2025-01-04T08:33:42"
    },
    {
      "id": "2a9ebd5a-7824-48d3-9f01-1a243f5bed75",
      "name": "Avatar 2",
      "avatar_url": "https://ausyncdev.blob.core.windows.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). Request trả về ngay; theo dõi kết quả bằng cách polling endpoint chi tiết video.

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 thất bại (không có callback khi thành công)

Lưu ý: Phải cung cấp avatar_id hoặc avatar_style. Model sparrow dùng với avatar_style và phải được truyền tường minh ("model": "sparrow"); các model khác dùng với avatar_id. Hệ thống không kiểm tra ràng buộc này khi nhận request: request sai vẫn trả 200 nhưng job sẽ chuyển sang INTERNAL_ERROR.

Ví dụ 1 — Avatar có sẵn (model sparrow):

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

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' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sample Video",
    "avatar_id": "123e4567-e89b-12d3-a456-426614174000",
    "audio_url": "https://example.com/audio.wav",
    "model": "spark"
  }'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "video_id": "123e4567-e89b-12d3-a456-426614174001",
    "message": "Your request to generate talking avatar is processing"
  }
}

403 Forbidden: Tài khoản không có gói trả phí.
422 Validation Error: Dữ liệu không hợp lệ hoặc body không phải JSON.

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 video 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 (kiểu UUID).

CURL:

curl -X 'GET' \
  'https://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://ausyncdev.blob.core.windows.net/talking-avatar-video-output/sample.jpeg.mp4",
    "created_at": "2025-01-04T08:33:49",
    "state": "SUCCEED"
  }
}

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

Các trạng thái có thể (state):

state	Mô tả
`WAITING_IN_QUEUE`	Đang chờ xử lý
`IN_PROGRESS`	Đang tạo video
`SUCCEED`	Hoàn thành, `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

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' \
  'https://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://ausyncdev.blob.core.windows.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://ausyncdev.blob.core.windows.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 video 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-videos/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",
    "success": true
  }
}

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

Callback Payload

Callback chỉ được gửi khi job thất bại. Khi video hoàn thành thành công, API không gửi callback; hãy polling endpoint chi tiết avatar video để lấy video_url.

Nội dung Payload:

video_id: ID duy nhất của video.
credits_used: Số lượng tín dụng đã sử dụng (credit bị giữ được hoàn lại khi thất bại).
status: "failed".
video_url: null.

Ví dụ

{
  "video_id": "123e4567-e89b-12d3-a456-426614174001",
  "credits_used": 0,
  "status": "failed",
  "video_url": null
}

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

Lipsync API Keys

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`)