建立複製音色

複製流程第 2 步：用上傳的錄音複製出你命名的音色；複製本身免費，首次合成成功時收一次複製費。

POST/v1/voice_clone

傳入第 1 步的 file_id 與你自己起的 voice_id，之後把 voice_id 填到 /v1/audio/speech 的 voice 或 /v1/t2a_v2 的 voice_setting.voice_id 即可合成。帶上 text 與 model 可拿到試聽音訊：demo_audio 是 api.hop-base.com 上的下載連結，6 小時內有效；不傳 text 時為空。

計費：上傳與複製免費。複製費只收一次，在音色首次合成成功時一併扣除（使用記錄明細多一項 voice_clone_activation）；試聽只按語音字元計費，不算首次使用。價格見價格頁。

生命週期：複製成功後來源音訊與示例音訊自動刪除，再次複製須重新上傳；複製失敗則保留檔案，可換參數重試。複製後 7 天內未用於合成的音色自動刪除，且不收複製費。音色只屬於你的帳戶（企業帳戶下由企業主名下成員的金鑰共享），其他帳戶即使知道 voice_id 也用不了。

建立複製音色

curl https://api.hop-base.com/v1/voice_clone \
  -H "Authorization: Bearer $HOPBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 123456789,
    "voice_id": "MyNarrator01",
    "text": "Hello, this is my cloned voice.",
    "model": "speech-2.8-hd",
    "need_noise_reduction": true
  }'

200application/json

{
  "input_sensitive": false,
  "input_sensitive_type": 0,
  "demo_audio": "https://api.hop-base.com/relay/EXAMPLE-TOKEN",
  "extra_info": {
    "audio_length": 2210,
    "usage_characters": 31
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

請求標頭

Authorization:必填string

Bearer sk-…：主控台「API 金鑰」中建立的金鑰，所屬分組須包含請求的模型

請求主體參數JSON

file_id:必填integer

第 1 步 purpose=voice_clone 上傳回傳的檔案 ID，只能用一次

範圍≥ 1

voice_id:必填string

你自己起的音色名，帳戶內唯一：由字母、數字、-、_ 組成，以字母開頭，不以 - 或 _ 結尾

長度8–256 字元

clone_prompt:選填object

示例片段

text:選填string

試聽文字；傳了會回傳試聽音訊，按語音字元計費（不算首次使用）

長度≤ 1000 字元

model:選填string

傳 text 時必填

可選值speech-2.8-hdspeech-2.8-turbo

language_boost:選填string

與原生入口相同

可選值autoChineseChinese,YueEnglishArabicRussianSpanishFrenchPortugueseGermanTurkishDutchUkrainianVietnameseIndonesianJapaneseItalianKoreanThaiPolishRomanianGreekCzechFinnishHindiBulgarianDanishHebrewMalayPersianSlovakSwedishCroatianFilipinoHungarianNorwegianSlovenianCatalanNynorskTamilAfrikaans

text_validation:選填string

預期文字，用語音辨識比對來源音訊

長度≤ 200 字元

accuracy:選填number

text_validation 的通過門檻值；官方預設 0.7

範圍0–1

need_noise_reduction:選填boolean

降噪

預設false

need_volume_normalization:選填boolean

音量歸一

預設false

aigc_watermark:選填boolean

AIGC 浮水印

預設false

回傳

200複製成功

input_sensitive:選填boolean

輸入是否觸發敏感內容

input_sensitive_type:選填integer

敏感內容類型

demo_audio:選填string

試聽音訊下載連結，6 小時內有效；不傳 text 時為空字串

extra_info:選填object

僅帶試聽時回傳

base_resp:選填object

成功時為 {"status_code": 0, "status_msg": "success"}；錯誤不走這裡，而是非 200 狀態碼加 error 物件

錯誤

400file_id 已用過或已過期、voice_id 不合規或已被佔用、音訊時長超出範圍、text_validation 比對未通過、text 超長、傳 text 缺 model、未知欄位等

401沒帶金鑰、金鑰無效或已過期（missing_api_key / invalid_api_key / api_key_expired）

402餘額或金鑰 / 成員 / 部門額度用完（insufficient_quota）

404模型不在這把金鑰的分組裡（model_not_found），或路徑不屬於該分組（route_not_found）

413請求體超過 64 KiB：request body is too large

503voice cloning is temporarily unavailable、voice registry is temporarily unavailable; please retry 等：稍後重試

請求標頭

請求主體參數JSON

回傳

錯誤

相關頁面