Tích hợp HieStudio vào ứng dụng của bạn

Bắt đầu

1. Bật Remote API trên các thiết bị HieStudio muốn tham gia device pool.
2. Vào Portal → Cài đặt → Remote API, tạo key, chọn scopes và device pool.
3. Dùng base URL https://YOUR_SERVER/v1 cùng Bearer key.

export HIESTUDIO_API_KEY="hsk_..."
export HIESTUDIO_BASE_URL="https://YOUR_SERVER/v1"

curl "$HIESTUDIO_BASE_URL/capabilities" \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY"

Scopes

Device pool & routing

Không gửi header thiết bị để HieStudio tự chọn. Nếu cần cố định một thiết bị, gửi public device ID hiển thị trong Portal.

curl -X POST "$HIESTUDIO_BASE_URL/tts/jobs" \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY" \
  -H "X-HieStudio-Device: hdv_..." \
  -H "Content-Type: application/json" \
  -d '{"voiceId":"VOICE_UUID","text":"Xin chào","language":"vi"}'

Header thiết bị chỉ có hiệu lực khi thiết bị thuộc pool của key. Thiết bị được chỉ định nhưng không khả dụng trả DEVICE_OFFLINE; chế độ Auto không tìm được thiết bị phù hợp trả NO_CAPABLE_DEVICE.

Tạo và đọc job

# TTS
curl -X POST "$HIESTUDIO_BASE_URL/tts/jobs" \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voiceId":"VOICE_UUID","text":"Xin chào","language":"vi"}'

# STT
curl -X POST "$HIESTUDIO_BASE_URL/stt/jobs" \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY" \
  -F "[email protected]" -F "language=vi"

# Poll
curl "$HIESTUDIO_BASE_URL/jobs/JOB_ID" \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY"

# Output
curl -L "$HIESTUDIO_BASE_URL/jobs/JOB_ID/output" \
  -H "Authorization: Bearer $HIESTUDIO_API_KEY" -o output.wav

Chi tiết payload TTS/STT giống Local API v1. Xem Local API v1 để tham khảo toàn bộ tham số.

Node.js

const baseUrl = process.env.HIESTUDIO_BASE_URL;
const key = process.env.HIESTUDIO_API_KEY;

const response = await fetch(baseUrl + '/tts/jobs', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + key,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ voiceId: 'VOICE_UUID', text: 'Xin chào', language: 'vi' }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Python

import os, requests

base = os.environ['HIESTUDIO_BASE_URL']
headers = {'Authorization': 'Bearer ' + os.environ['HIESTUDIO_API_KEY']}
r = requests.post(base + '/tts/jobs', headers=headers, json={
    'voiceId': 'VOICE_UUID', 'text': 'Xin chào', 'language': 'vi'
})
r.raise_for_status()
print(r.json())

Limits & errors

Mỗi key có rate limit và concurrency riêng. Key có thể có thời hạn; plaintext chỉ hiển thị một lần khi tạo.

{
  "error": {
    "code": "CONCURRENCY_LIMIT",
    "message": "Remote API đã đạt giới hạn job đồng thời.",
    "maxConcurrentJobs": 4
  }
}

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