Host Mix API

Tổng Quan

Giới thiệu Host Mix API của AusyncLab cho phép tạo audio đa giọng nói từ một kịch bản hội thoại. Mỗi đoạn văn bản có thể được gán cho một giọng nói khác nhau, hệ thống sẽ tổng hợp từng đoạn song song và ghép lại thành một file audio hoàn chỉnh theo đúng thứ tự.

Tính Năng Chính

Tổng hợp audio đa giọng nói (tối đa 6 speakers)
Xử lý các đoạn song song, ghép theo thứ tự
Tái tạo từng đoạn riêng lẻ mà không cần tạo lại toàn bộ
Theo dõi tiến trình qua polling

Quick Start

Đăng ký và lấy API Key từ hệ thống.
Lấy danh sách giọng nói từ Voice Library.
Gửi yêu cầu generate với danh sách segments, mỗi segment gồm voice_id và text.
Polling trạng thái bằng operation_id cho đến khi state là SUCCEED.

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/host-mix

Playground

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

Chi Tiết Endpoints

1. Tạo Audio Đa Giọng Nói

URL: POST /api/v1/host-mix/generate Mô tả: Tạo một host mix operation từ danh sách segments. Trả về ngay lập tức với operation_id để polling.

Tham số Request Body:

operation_id (bắt buộc): UUID do client tự tạo để định danh operation. Dùng để polling trạng thái.
name (bắt buộc): Tên của operation.
char_count (bắt buộc): Tổng số ký tự của tất cả segments.
segments (bắt buộc): Danh sách các đoạn hội thoại. Mỗi segment gồm:
- voice_id (bắt buộc): ID giọng nói. Xem Voice Library để lấy danh sách.
- text (bắt buộc): Văn bản cần chuyển đổi.
- char_count (bắt buộc): Số ký tự của đoạn này.
- model_name (tùy chọn): Model TTS (myna-1, myna-1-turbo, myna-2). Mặc định myna-1-turbo.
- speed (tùy chọn): Tốc độ nói (0.75 – 1.25). Mặc định 1.0.
- language (tùy chọn): Ngôn ngữ (vi, en, ...). Mặc định vi.
- region (tùy chọn): Vùng giọng (northern, southern). Mặc định northern.
- speaker_label (tùy chọn): Nhãn hiển thị cho speaker (ví dụ: "Host", "Guest").
- voice_name (tùy chọn): Tên giọng nói (metadata hiển thị).
callback_url (tùy chọn): URL nhận thông báo khi hoàn thành.

CURL:

curl -X 'POST' \
  'https://api.ausynclab.io/api/v1/host-mix/generate' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
    "name": "Podcast Demo",
    "char_count": 63,
    "segments": [
      {
        "voice_id": 1001,
        "text": "Xin chào, hôm nay chúng ta sẽ nói về trí tuệ nhân tạo.",
        "char_count": 54,
        "model_name": "myna-1-turbo",
        "speed": 1.0,
        "language": "vi",
        "speaker_label": "Host",
        "voice_name": "Liên Hoa"
      },
      {
        "voice_id": 1002,
        "text": "Đúng vậy!",
        "char_count": 9,
        "model_name": "myna-1-turbo",
        "speed": 1.0,
        "language": "vi",
        "speaker_label": "Guest",
        "voice_name": "An Khôi"
      }
    ]
  }'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
    "total_segments": 2,
    "status": "processing",
    "message": "HostMix audio generation queued"
  },
  "message": null
}

2. Kiểm Tra Trạng Thái

URL: GET /api/v1/host-mix/{operation_id} Mô tả: Lấy trạng thái hiện tại của một host mix operation. Polling endpoint này cho đến khi state là SUCCEED hoặc INTERNAL_ERROR.

Tham số:

operation_id (bắt buộc): UUID của operation cần kiểm tra.

CURL:

curl -X 'GET' \
  'https://api.ausynclab.io/api/v1/host-mix/dc44e866-b4a6-4478-be71-e9c459a0054c' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK (đang xử lý)

{
  "status": 200,
  "result": {
    "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
    "name": "Podcast Demo",
    "state": "IN_PROGRESS",
    "total_segments": 2,
    "completed_segments": 1,
    "audio_url": null,
    "created_at": "2026-03-21T04:30:25.470000"
  },
  "message": null
}

200 OK (hoàn thành)

{
  "status": 200,
  "result": {
    "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
    "name": "Podcast Demo",
    "state": "SUCCEED",
    "total_segments": 2,
    "completed_segments": 2,
    "audio_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/audio/host_mix_dc44e866-b4a6-4478-be71-e9c459a0054c.wav",
    "created_at": "2026-03-21T04:30:25.470000"
  },
  "message": null
}

Các trạng thái có thể:

state	Mô tả
`WAITING_IN_QUEUE`	Đang chờ xử lý
`IN_PROGRESS`	Đang tổng hợp từng segment
`MERGING`	Đang ghép các segment thành file hoàn chỉnh
`SUCCEED`	Hoàn thành, `audio_url` sẵn sàng
`INTERNAL_ERROR`	Lỗi xử lý

3. Lấy Danh Sách Operations

URL: GET /api/v1/host-mix/ Mô tả: Lấy danh sách các host mix operations trong 30 ngày gần nhất (tối đa 20 kết quả).

Tham số Query:

limit (tùy chọn): Số lượng kết quả trả về. Mặc định 20.

CURL:

curl -X 'GET' \
  'https://api.ausynclab.io/api/v1/host-mix/?limit=10' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": [
    {
      "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
      "name": "Podcast Demo",
      "state": "SUCCEED",
      "total_segments": 2,
      "completed_segments": 2,
      "audio_url": "https://ausync-h8f7gketarb6a2dt.z01.azurefd.net/audio/host_mix_dc44e866.wav",
      "created_at": "2026-03-21T04:30:25.470000"
    }
  ],
  "message": null
}

4. Tái Tạo Một Số Segments

URL: POST /api/v1/host-mix/regenerate-segments Mô tả: Tái tạo một số đoạn cụ thể trong operation đã có mà không cần tạo lại toàn bộ. Hữu ích khi muốn thay đổi giọng hoặc nội dung một vài đoạn.

Tham số Request Body:

operation_id (bắt buộc): UUID của operation gốc.
segments (bắt buộc): Danh sách các segment cần tái tạo. Mỗi item có đầy đủ thông tin của segment mới và thêm:
- index (bắt buộc): Vị trí (0-based) của segment trong danh sách gốc.
callback_url (tùy chọn): URL nhận thông báo khi hoàn thành.

CURL:

curl -X 'POST' \
  'https://api.ausynclab.io/api/v1/host-mix/regenerate-segments' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
    "segments": [
      {
        "index": 1,
        "voice_id": 1003,
        "text": "Chính xác!",
        "char_count": 10,
        "model_name": "myna-1-turbo",
        "speed": 1.0,
        "language": "vi",
        "speaker_label": "Guest"
      }
    ]
  }'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
    "regenerated_segments": 1,
    "status": "processing"
  },
  "message": null
}

5. Xóa Operation

URL: DELETE /api/v1/host-mix/{operation_id} Mô tả: Xóa một host mix operation.

Tham số:

operation_id (bắt buộc): UUID của operation cần xóa.

CURL:

curl -X 'DELETE' \
  'https://api.ausynclab.io/api/v1/host-mix/dc44e866-b4a6-4478-be71-e9c459a0054c' \
  -H 'accept: application/json' \
  -H 'X-API-Key: your_api_key'

Phản hồi:

200 OK

{
  "status": 200,
  "result": {
    "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
    "deleted": true
  },
  "message": null
}

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

Text to Speech File Upload