Sota Voice
Tài liệu

Tạo giọng nói qua HTTP

POST /v1/audio/speech - nhận trọn file, stream PCM, hoặc Server-Sent Events.

Xem dạng Markdown

POST /v1/audio/speech đọc input và trả audio trong cùng response. Có ba chế độ: trọn file (mặc định), stream PCM thô ("stream": true) và Server-Sent Events ("stream_format": "sse").

Tham khảo đầy đủ: Create speech.

Tham số

FieldKiểuMặc địnhGhi chú
inputstring(bắt buộc)Chữ cần đọc, tối đa 5.000 ký tự (mặc định của deployment). Dài hơn: dùng job bất đồng bộ.
modelstringsota-voice-v1Chỉ có sota-voice-v1; có thể bỏ qua. Model khác: 404 model_not_found.
voicestringdefaultGiọng có sẵn hoặc name của giọng bạn đã nhân bản (ở bất kỳ profile_state nào).
response_formatstringmp3mp3, wav, opus, aac, flac, pcm. Bỏ qua khi stream.
streambooleanfalsetrue: trả PCM thô ngay khi sinh.
stream_formatstringsse: trả text/event-stream.
literal_punctuationbooleanĐọc dấu câu thành chữ thay vì coi là ngữ điệu.

Tách câu (split_granularity) chỉ có ở WebSocket realtime; gửi field này qua HTTP: 400 invalid_request.

Field model, voice, input, stream, stream_format, response_format không được lặp lại hoặc viết khác hoa thường (Voice): 400 invalid_request với param là tên field.

Trọn file

curl https://voice-be.sotalabs.io/v1/audio/speech \
  -H "Authorization: Bearer $SOTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sota-voice-v1","voice":"default","input":"Chào mừng bạn đến với Sota Voice.","response_format":"wav"}' \
  --output speech.wav

Content-Type của response khớp response_format: audio/mpeg, audio/wav, audio/ogg (Opus), audio/aac, audio/flac, audio/pcm.

Stream PCM

Với "stream": true, response là PCM thô (16-bit có dấu little-endian, mono, 44,1 kHz) gửi ngay khi đang sinh, thường bắt đầu sau 100-250 ms. Hợp để phát ngay mà không cần giải mã.

curl -N https://voice-be.sotalabs.io/v1/audio/speech \
  -H "Authorization: Bearer $SOTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sota-voice-v1","voice":"default","input":"Đây là audio đang được stream.","stream":true}' \
  | ffplay -f s16le -ar 44100 -ch_layout mono -nodisp -autoexit -

Một mẫu PCM (2 byte) có thể bị cắt giữa hai chunk; hãy giữ byte lẻ lại cho chunk sau.

Server-Sent Events

Với "stream_format": "sse", response là text/event-stream. Mỗi dòng data: là JSON: nhiều sự kiện speech.audio.delta (audio mã hóa base64 trong audio), rồi một speech.audio.done.

curl -N https://voice-be.sotalabs.io/v1/audio/speech \
  -H "Authorization: Bearer $SOTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sota-voice-v1","voice":"default","input":"Xin chào.","stream_format":"sse"}'
data: {"type":"speech.audio.delta","audio":"UklGRiQAAABXQVZF..."}

data: {"type":"speech.audio.delta","audio":"ZGF0YQAAAAAAAA=="}

data: {"type":"speech.audio.done"}

Giải mã base64 của từng audio và ghép theo thứ tự.

Tính phí và lỗi

  • Credit bị trừ trước, đúng số ký tự của input. Nếu dịch vụ giọng nói lỗi trước khi gửi byte đầu tiên, credit được hoàn lại (503 upstream_unavailable). Response kèm x-credits-remaining.
  • Không đủ credit: 402 insufficient_credit. Chữ quá dài: 400 input_too_long. Body quá lớn: 413 request_too_large.
  • Request này tính vào giới hạn request/giây của khóa và số request realtime đồng thời của tài khoản. Xem Giới hạn tốc độ và Mã lỗi.