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, mỗi đoạn một giọng
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 hoặc callback

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 trong response cho đến khi state là SUCCEED hoặc INTERNAL_ERROR.

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 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. Nếu giá trị không phải UUID hợp lệ, hệ thống sẽ tự sinh một UUID mới. Luôn dùng operation_id trong response để polling.
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. Đây là cơ sở tính credit; hệ thống không tự tính lại từ text.
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 (cơ sở tính credit cho đoạn).
- model_name (tùy chọn): Model TTS (myna-1, myna-1-turbo, myna-2; xem Text to Speech để biết chi phí). Mặc định myna-1-turbo. Model không được hỗ trợ trả về 422 với error_code là unsupported_model.
- speed (tùy chọn): Tốc độ nói. Khuyến nghị 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 riêng cho đoạn này; ưu tiên hơn callback_url ở cấp operation.
callback_url (tùy chọn): URL nhận thông báo khi toàn bộ operation hoàn thành. Xem mục Callback Payload.

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
}

total_segments là số segment trong request. Các segment không có ký tự chữ hoặc số (ví dụ chỉ có dấu câu) sẽ bị bỏ qua khi tổng hợp.

400 Bad Request: segments_empty (danh sách rỗng), segment_{i}_empty_text (đoạn thứ i không có văn bản), voice_not_found (voice_id không tồn tại hoặc không thuộc tài khoản).
422 Validation Error: model_name không được hỗ trợ hoặc body sai định dạng.

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",
    "segments": [
      {
        "index": 0,
        "audio_id": 501,
        "free_audio_id": 501,
        "speaker_label": "Host",
        "text": "Xin chào, hôm nay chúng ta sẽ nói về trí tuệ nhân tạo.",
        "voice_id": 1001,
        "model_name": "myna-1-turbo",
        "speed": 1.0,
        "audio_url": "https://cdn.example.com/audio/segment_0.wav",
        "audio_url_hls": "https://cdn.example.com/audio/segment_0.m3u8",
        "duration": 4.1,
        "state": "SUCCEED"
      },
      {
        "index": 1,
        "audio_id": 502,
        "free_audio_id": 502,
        "speaker_label": "Guest",
        "text": "Đúng vậy!",
        "voice_id": 1002,
        "model_name": "myna-1-turbo",
        "speed": 1.0,
        "audio_url": null,
        "audio_url_hls": null,
        "duration": null,
        "state": "IN_PROGRESS"
      }
    ]
  },
  "message": null
}

200 OK (hoàn thành; mảng segments có cấu trúc như trên, mỗi phần tử ở trạng thái SUCCEED)

{
  "status": 200,
  "result": {
    "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
    "name": "Podcast Demo",
    "state": "SUCCEED",
    "total_segments": 2,
    "completed_segments": 2,
    "audio_url": "https://cdn.example.com/audio/host_mix_dc44e866-b4a6-4478-be71-e9c459a0054c.wav",
    "created_at": "2026-03-21T04:30:25.470000",
    "segments": [ ... ]
  },
  "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ý

400 Bad Request: operation_id không phải UUID hợp lệ.
404 Not Found: Không tìm thấy operation.

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. Mỗi phần tử có cùng cấu trúc với response của endpoint kiểm tra trạng thái (bao gồm mảng segments).

Tham số Query:

limit (tùy chọn): Số lượng kết quả tối đa. 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://cdn.example.com/audio/host_mix_dc44e866.wav",
      "created_at": "2026-03-21T04:30:25.470000",
      "segments": [ ... ]
    }
  ],
  "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. Operation quay về trạng thái WAITING_IN_QUEUE và được ghép lại khi các đoạn mới hoàn thành. Mỗi lần tái tạo được tính credit theo char_count của các đoạn gửi lên.

Tham số Request Body:

operation_id (bắt buộc): UUID của operation gốc. Giá trị không phải UUID trả về 400 (invalid_operation_id).
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": "HostMix segments re-queued"
  },
  "message": null
}

regenerated_segments là danh sách index của các đoạn đã được đưa vào hàng đợi.

400 Bad Request: invalid_operation_id, segments_empty, segment_{i}_empty_text, voice_not_found.
404 Not Found: Không tìm thấy operation.

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.

Callback Payload

Khi toàn bộ operation hoàn thành thành công, API sẽ gửi thông báo đến callback_url với payload:

Nội dung Payload:

operation_id : UUID của operation.
status : SUCCEED.
audio_url : URL tải xuống file audio đã ghép.
audio_hls_url : URL streaming (HLS) của file audio đã ghép.
duration : Thời lượng audio (giây).
message : Thông báo về kết quả xử lý.
created_at : Thời gian tạo operation (ISO 8601).

Ví dụ

{
  "operation_id": "dc44e866-b4a6-4478-be71-e9c459a0054c",
  "status": "SUCCEED",
  "audio_url": "https://cdn.example.com/audio/host_mix_dc44e866-b4a6-4478-be71-e9c459a0054c.wav",
  "audio_hls_url": "https://cdn.example.com/audio/host_mix_dc44e866-b4a6-4478-be71-e9c459a0054c.m3u8",
  "duration": 12.7,
  "message": "HostMix audio generated successfully.",
  "created_at": "2026-03-21T04:30:25.470000"
}

Lưu ý: Callback chỉ được gửi khi thành công. Khi operation lỗi (INTERNAL_ERROR) sẽ không có callback, vì vậy hãy kết hợp polling endpoint kiểm tra trạng thái để phát hiện lỗi. Người dùng cần triển khai endpoint để nhận và xử lý payload này.

Text to Speech File Upload