文本转语音

Convbased.textToSpeech 一次完成参考音频上传、任务提交和结果轮询。0.3 API 提供三种稳定的产品模式，不暴露服务端执行引擎。

选择模式

`mode`	参考音频	计费单位	适用能力
`general`	可不提供；克隆时最多 1 段，并提供 `promptText`	字符	通用生成、参考音色克隆。
`expressive`	最多 1 段主参考，可另传 `emotionVoice`	字符	情感、采样和分段控制。
`advanced`	最多 3 段有序参考，可作为上下文	秒	场景描述、语速/音高/响度、格式和字幕。

省略 mode 时使用服务端默认模式。面向用户提供模式选择器时，通过 TtsClient.getModes() 获取当前能力，不要依赖执行引擎名称：

import { TtsClient } from "@convbased/sdk";

const modes = await new TtsClient({ auth }).getModes();

返回项包括 billingUnit、cloneRequiresTranscript、maxReferences 和 supportsContext。

情感合成

import { Convbased } from "@convbased/sdk";

const result = await Convbased.textToSpeech({
  auth,
  mode: "expressive",
  voice: referenceFile,
  text: "你好，这是一段合成语音。",
  params: {
    temperature: 0.8,
    use_emo_text: true,
    emo_text: "平静、自然",
  },
  onProgress: (status, queuePosition) => {
    console.log(status, queuePosition);
  },
});

const audio = document.querySelector<HTMLAudioElement>("#tts")!;
if (result.url) {
  audio.src = result.url;
}

voice 可以是 File / Blob，也可以是已上传音频的 { key }。

无参考生成

general 模式可以不传参考音频：

const result = await Convbased.textToSpeech({
  auth,
  mode: "general",
  text: "请生成一段清晰、自然的旁白。",
  params: {
    cfg_value: 2,
    inference_timesteps: 10,
    normalize: true,
  },
});

使用参考音频克隆时，同时传入参考内容的 promptText。

多参考与字幕

const result = await Convbased.textToSpeech({
  auth,
  mode: "advanced",
  voices: [speakerReference, contextReference],
  text: "雨停以后，街道慢慢安静下来。",
  params: {
    scene_description: "克制的纪录片旁白，近讲，语速稍慢",
    format: "wav",
    sample_rate: 48000,
    speech_rate: 0.95,
    enable_subtitle: true,
  },
});

voice 与 voices 不能同时使用；voices 的顺序会保留。独立的 emotionVoice 只用于 expressive 模式。

参数

参数	类型	说明
`auth`	`SdkAuthentication`	SDK 鉴权配置，见鉴权。
`text`	`string`	待生成文本。
`mode`	`"general" \| "expressive" \| "advanced"`	产品模式。
`voice`	`Blob \| { key: string }`	单段参考音频。
`voices`	`readonly TtsReference[]`	有序参考音频；不能与 `voice` 同时传入。
`emotionVoice`	`TtsReference`	`expressive` 模式的独立情感参考。
`promptText`	`string`	参考音频转写；所选模式要求时必填。
`params`	`TtsParams`	所选模式的生成参数。
`onProgress`	`(status, queuePosition) => void`	队列与处理状态回调。
`timeoutMs`	`number`	等待超时，默认 `300000`。
`signal`	`AbortSignal`	中止等待；仍在排队时 SDK 会尝试取消任务。

模式参数：

GeneralTtsParams：cfg_value、inference_timesteps、normalize、denoise。
ExpressiveTtsParams：emo_alpha、emo_vector、use_emo_text、emo_text、temperature、top_p、top_k、max_text_tokens_per_segment、interval_silence。
AdvancedTtsParams：scene_description、format、sample_rate、speech_rate、loudness_rate、pitch_rate、enable_subtitle。

参数由所选模式校验，不要把一类模式的参数传给另一类模式。

结果

字段	类型	说明
`url`	`string \| null`	合成音频的临时访问地址。
`key`	`string`	合成音频标识。
`mode`	`TtsGenerationMode \| null`	实际使用的产品模式；旧任务可能为 `null`。
`billingQuantity`	`number`	本次实际计费数量。
`billingUnit`	`"CHAR" \| "SECOND"`	`billingQuantity` 的单位。
`tokenCount`	`number`	输入字符数；字段名为兼容旧版本保留。
`audioDurationSec`	`number`	音频时长（秒）。
`amountCharged`	`number`	本次扣费金额。
`balanceAfter`	`number`	扣费后余额。
`subtitle`	`unknown \| null`	启用字幕且服务返回时的时间信息。

任务失败、取消、超时或中止时，调用会 reject。

上传限制

参考音频支持 mp3、wav、ogg、flac、m4a 和 aac，单文件最大 100 MB。传入 File 可以保留正确文件名和后缀；裸 Blob 使用默认文件名 audio.wav，不会转换其实际编码。

文本转语音 ​

选择模式 ​

情感合成 ​

无参考生成 ​

多参考与字幕 ​

参数 ​

结果 ​

上传限制 ​