Sota Voice
Tài liệu

Nhân bản giọng

Tạo giọng riêng từ một bản ghi ngắn, với xác nhận đồng ý của người nói.

Xem dạng Markdown

POST /v1/audio/voices tạo một giọng nhân bản từ bản ghi ngắn. Nhân bản giọng không tính phí; dùng giọng đó để đọc thì tính phí như bình thường.

Bạn chỉ được nhân bản giọng của chính mình, hoặc giọng của người đã cho phép bạn. Mỗi request phải gửi consent=true, nghĩa là bạn xác nhận câu:

I confirm I own this voice or have the speaker's permission to clone it.

Hệ thống lưu lại lời xác nhận, thời điểm, địa chỉ IP và khóa API đã dùng. Bản ghi đồng ý được giữ lại cả khi bạn xóa giọng. Thiếu consent=true: 422 consent_required.

Tạo giọng

Gửi multipart/form-data:

FieldBắt buộcGhi chú
namecó1-40 ký tự a-z, 0-9, _, -. Không trùng giọng có sẵn, duy nhất trong tài khoản. Đây là giá trị bạn truyền vào voice.
consentcóPhải là true.
ref_textcóLời chính xác của những gì được nói trong bản ghi, 1-500 ký tự.
audio_samplecóFile WAV hoặc MP3, tối đa 10 MiB và 30 giây.
display_namekhôngTên hiển thị, 1-60 ký tự; mặc định bằng name. Sai độ dài trả 400 voice_display_name_invalid.
descriptionkhôngMô tả, tối đa 500 ký tự (400 voice_description_too_long). Được trả về ở cả description.vi và description.en.
anchorskhôngMảng JSON tối đa 5 chuỗi (mỗi chuỗi đến 500 ký tự) giúp hoàn thiện hồ sơ giọng.
curl https://voice-be.sotalabs.io/v1/audio/voices \
  -H "Authorization: Bearer $SOTA_API_KEY" \
  -F name=my_narrator \
  -F consent=true \
  -F "ref_text=Xin chào, đây là giọng đọc mẫu của tôi." \
  -F [email protected]
{
  "id": "voice_01jd8y7n4t2k6m8p0q1r3s5u7w",
  "object": "voice",
  "name": "my_narrator",
  "display_name": "my_narrator",
  "type": "cloned",
  "profile_state": "queued",
  "created_at": 1763366400,
  "tagline": null,
  "description": null,
  "category": null,
  "gender": null,
  "age": null,
  "accent": null,
  "languages": [],
  "featured": false,
  "verified": false,
  "sort_order": 0,
  "preview_url": null
}

Gợi ý cho bản ghi: một người nói, phòng yên tĩnh, không nhạc nền, nói tự nhiên, và ref_text khớp từng chữ với lời nói.

Trạng thái hồ sơ giọng

Giọng dùng được ngay khi request trả về: truyền name vào voice của POST /v1/audio/speech, WebSocket hoặc job. Trong lúc đó hồ sơ giọng được hoàn thiện dần, thể hiện qua profile_state:

profile_stateÝ nghĩa
queuedĐang chờ xử lý hồ sơ.
buildingĐang hoàn thiện hồ sơ.
readyHồ sơ đã hoàn thiện. Giọng có sẵn luôn ở trạng thái này.
failedKhông hoàn thiện được hồ sơ.

Giọng dùng được ở mọi trạng thái; trạng thái chỉ cho biết hồ sơ đã được tinh chỉnh tới đâu. Theo dõi bằng GET /v1/audio/voices/{id}.

Giới hạn và lỗi

Trường hợpLỗi
Đã có tối đa số giọng nhân bản (mặc định 10 mỗi tài khoản)409 voice_limit
name đã có trong tài khoản409 voice_name_taken
File quá 10 MiB413 sample_too_large
File dài quá 30 giây422 sample_too_long
Không phải WAV hoặc MP3 hợp lệ422 unsupported_audio
Thiếu consent=true422 consent_required
Tài khoản bị tạm khóa403 account_suspended

Liệt kê và xóa

  • GET /v1/audio/voices: mọi giọng có sẵn đang hiển thị (theo thứ tự danh mục), sau đó là các giọng bạn đã nhân bản (mới nhất trước), trong một response. Giọng có sẵn kèm display_name, tagline, description, category, gender, age, accent, languages, featured, verified, sort_order và preview_url (URL ký sẵn, sống 1 giờ); giọng nhân bản có các trường này ở giá trị rỗng (null hoặc []).
  • GET /v1/audio/voices/{id}: giọng có sẵn (theo tên) hoặc giọng nhân bản (theo voice_...).
  • DELETE /v1/audio/voices/{id}: xóa giọng nhân bản và bản ghi mẫu đã lưu. Giọng có sẵn không xóa được. Bản ghi đồng ý vẫn được giữ.