主题

浏览器文本转语音 ​

Convbased.textToSpeech() 将文本合成为音频，按需上传参考音频并等待结果。

在 AI 客户端中生成语音，请使用 MCP 连接指引。

前置条件 ​

  • 已在浏览器项目中安装 SDK；
  • 已按鉴权说明配置 auth，应用后端允许当前用户使用 tts 权限和 { type: "tts" } 资源；
  • Convbased 账户可用余额足够支付本次合成。

无参考音频合成 ​

使用 general 模式，无需准备音频文件。每次调用都会创建收费任务，收费规则见模式与价格。

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

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

console.log(result.url);

成功后从 result.url 取得临时音频地址；结果字段见结果。

模式与价格 ​

模式用途与参考音频要求计费单位
general不用参考音频直接合成，或用一段参考音频克隆音色；克隆时需提供参考音频对应的文字字符
expressive可控制情感、采样和分段；最多一段主参考音频，可另传一段情感参考音频字符
advanced支持上下文参考音频、场景描述和输出格式设置；最多三段参考音频，按传入顺序使用秒

查询模式与价格 ​

使用 TtsClient 读取模式要求和当前价格：

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

const tts = new TtsClient({ auth });
const [modes, pricing] = await Promise.all([
  tts.getModes(),
  tts.getPricing(),
]);

modes 中的 billingUnit、cloneRequiresTranscript、maxReferences 和 supportsContext 分别表示计费单位、克隆时是否需要参考音频对应的文字、参考音频数量上限和是否支持上下文参考音频。列表中的模式不保证当前一定可用。

pricing 包含：

字段含义
pricePerToken每个输入字符的价格
advancedPricePerSecondadvanced 每秒输出音频的价格
advancedMaxSecondsadvanced 提交时按此秒数冻结余额
minCharge单次最低收费

提交任务时先冻结一部分余额，任务完成后按实际用量扣费。advanced 按 advancedMaxSeconds 冻结，扣费后退回未使用的部分；任务失败或成功取消时，冻结的余额全部退回。实际扣费见结果中的 amountCharged。

单段参考音频合成 ​

以下示例使用 expressive 控制情感。referenceFile 是用户选择的音频 File，audio 是页面中的 <audio> 元素：

ts
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);
  },
});

if (result.url) audio.src = result.url;

voice 接受 File、Blob 或已上传音频的 { key }。使用 general 克隆时，还需通过 promptText 提供参考音频对应的文字，并使用该模式的 params 字段。

多段参考音频与字幕 ​

advanced 可传入多段参考音频并按传入顺序使用，还可以要求返回字幕。speakerReference 和 contextReference 是事先准备好的音频 File 或 { key }：

ts
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。

参数与状态 ​

按所选 mode 设置 params：general 使用 GeneralTtsParams，expressive 使用 ExpressiveTtsParams，advanced 使用 AdvancedTtsParams。

onProgress(status, queuePosition) 回调会收到任务状态和排队位置：

状态含义
queued排队中，queuePosition 从 1 开始
warming、processing正在准备或生成音频，继续等待
done任务完成，函数返回合成结果
failed、cancelled任务失败或已取消，函数抛出错误

timeoutMs 默认 300000 毫秒。超时只表示 SDK 不再等待，任务仍可能在服务端继续执行；超时或网络中断后，先在账户使用记录中确认任务是否已完成，不要自动重新提交合成。

通过 signal 中止时，SDK 停止等待并尝试取消任务。只有尚未开始执行的任务可以取消。任务失败、取消、超时或中止时函数抛出错误。

结果 ​

字段含义
key、url音频文件的存储标识和临时访问地址；没有生成临时地址时 url 为 null
mode实际使用的模式，可能为 null
billingQuantity、billingUnit实际计费数量及其单位 CHAR 或 SECOND
audioDurationSec合成音频时长，单位为秒
amountCharged、balanceAfter本次扣费金额与扣费后余额
subtitle服务返回的字幕时间轴数据；未启用字幕或没有字幕时为 null

tokenCount 表示输入字符数；查看计费结果时请使用 billingQuantity 和 billingUnit。

参考音频限制 ​

参考音频支持 mp3、wav、ogg、flac、m4a 和 aac，单文件最大 100 MB；advanced 每段参考音频不能超过 10 MB。参考音频必须属于签发 SDK 令牌的账户，数量和对应文字须符合所选模式的要求。

优先传入保留真实文件名的 File。直接传入 Blob 时，SDK 使用默认文件名 audio.wav，这不会改变音频编码；音频实际不是 WAV 格式时，应创建带正确文件名的 File。