Kết nối công cụ bên thứ ba với TTS/STT chạy cục bộ

Bắt đầu

Vào Settings → Local API, chọn bind address, port và bật Local API. Mặc định endpoint là http://127.0.0.1:17860/v1. Nếu bạn đổi bind address hoặc port, thay base URL trong các ví dụ bên dưới.

curl http://127.0.0.1:17860/v1/health \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY"

Nếu Bearer authentication đang tắt trong Settings, bỏ hoàn toàn header Authorization.

Authentication

Authentication là cấu hình cục bộ và có thể bật/tắt. Khi bật, mọi request phải gửi API key của tài khoản HieStudio đang đăng nhập.

# Bash
export HIESTUDIO_API_KEY="hiestudio_..."

# PowerShell
$env:HIESTUDIO_API_KEY="hiestudio_..."

Nút Tạo lại trong Settings vô hiệu key cũ ngay lập tức. Khi đổi tài khoản đăng nhập, hãy sử dụng API key của tài khoản mới.

Giọng

Danh sách chỉ trả các giọng mà tài khoản hiện tại có quyền sử dụng. Đây là cùng semantics với thư viện giọng/TTS trên giao diện HieStudio.

curl "http://127.0.0.1:17860/v1/voices?page=1&limit=100" \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY"

Có thể dùng thêm search, languageCode, gender, scope, sortBy và sortDirection.

curl -X POST http://127.0.0.1:17860/v1/tts/jobs \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceId": "11111111-1111-4111-8111-111111111111",
    "text": "Xin chào, đây là HieStudio.",
    "language": "vi"
  }'

Chỉ các trường được mô tả trong tài liệu này được chấp nhận.

curl -X POST http://127.0.0.1:17860/v1/stt/jobs \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY" \
  -F "[email protected]" \
  -F "language=vi" \
  -F "punctuation=true" \
  -F "diarizationEnabled=true" \
  -F "speakerCountMode=auto"

Tác vụ & kết quả

TTS/STT xử lý theo tác vụ bất đồng bộ. Phản hồi tạo tác vụ trả về ID để ứng dụng kiểm tra trạng thái. Local API chỉ cho truy cập các tác vụ được tạo qua Local API.

# Poll
curl http://127.0.0.1:17860/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY"

# Hủy job đang chạy/chờ
curl -X POST http://127.0.0.1:17860/v1/jobs/JOB_ID/cancel \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY"

# Tải audio TTS
curl -L http://127.0.0.1:17860/v1/jobs/JOB_ID/output \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY" \
  -o output.wav

# STT transcript
curl "http://127.0.0.1:17860/v1/jobs/JOB_ID/transcript?format=srt" \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY"

Transcript hỗ trợ txt, srt, vtt, json-simple và json-full.

Errors

{
  "error": {
    "code": "ENTITLEMENT_REQUIRED",
    "message": "Gói hiện tại chưa được cấp quyền sử dụng tính năng này.",
    "feature": "tts"
  }
}

Limits & security

• Local API chỉ hoạt động khi HieStudio Desktop đang chạy, người dùng đã đăng nhập và tài khoản có quyền sử dụng Kết nối ứng dụng.
• Text-to-Speech và Speech-to-Text vẫn yêu cầu quyền tương ứng; bật Local API không tự cấp thêm tính năng.
• Khi authentication bật, mỗi tài khoản sử dụng API key riêng.
• Nếu bind ra LAN/WAN, nên bật Bearer authentication và cấu hình firewall. Tắt authentication trên non-loopback đồng nghĩa máy khác có thể gọi API nếu truy cập được port.
• Request có header Origin từ trình duyệt bị từ chối. Local API không bật CORS và được thiết kế cho CLI, desktop app, automation và dịch vụ chạy trên máy hoặc mạng tin cậy.
• Local API không cung cấp chức năng đăng nhập, đổi gói dịch vụ hoặc quản lý tài nguyên và plugin.

OpenAPI 3.1: /api-specs/local-api-v1.openapi.yaml