天枢AI-TokenHub

简体中文

English

简体中文

English

Appearance

Request
Response

单向流式语音合成 HTTP 接口 ​

本文介绍单向流式语音合成 API 的输入输出参数，供您使用接口时查阅字段含义。基于 HTTP Chunked 协议的单向流式合成接口，一次性输入文本，流式返回音频，支持中、英、日、西等多语种及多种方言口音。

 

POST https://ai-tokenhub.com/api/v2/tts/unidirectional

请求参数 ​

请求信息 ​

项值
请求方法POST
官方请求地址https://ai-tokenhub.com/api/v2/tts/unidirectional
Content-Typeapplication/json
鉴权方式API Key 鉴权（Bearer Token）
传输方式单向流式（NDJSON）

请求头 ​

字段名必填说明
Authorization✓格式: Bearer <$YOUR_API_KEY>，其中 <$YOUR_API_KEY> 为您在天枢平台获取的长效 API 密钥
Content-Type✓固定值: application/json
Connection建议设置: keep-alive

请求体 ​

model string ​

具体模型版本，当 speaker 参数为复刻音色时使用，默认值 seed-tts-2.0。

注意 该模型版本不支持使用语音指令 context_texts

req_params object 必选 ​

语音合成请求参数对象，包含待合成文本、音色、音频参数与扩展能力。

text string 必选 ​

待合成的输入文本。支持中、英、日、韩、法、德等十余种语言，支持 Markdown 文本、LaTeX 公式。

该字段的字符数为本次请求的预冻结计费依据（1 个汉字、字母、标点、空格、回车均计 1 字符），最终结算以响应中 usage.text_words 为准。计费单价为 3 元 / 万字符。

speaker string 必选 ​

音色 ID，可从 豆包语音合成模型 2.0 音色列表 获取。

ssml string ​

SSML 标记文本，启用后按 SSML 规则解析 text。

目前仅中英文音色支持 ssml，音色详见 豆包语音合成模型 2.0 音色列表。

audio_params object 必选 ​

音频参数。

注意 流式场景推荐使用 pcm，不建议使用 wav

属性：

  • format string 必选：音频格式，支持 mp3 / pcm / ogg_opus / wav，默认值 mp3。

  • sample_rate integer 必选：音频采样率，单位 Hz。可选值：8000、16000、22050、24000、32000、44100、48000。

  • bit_rate integer：音频比特率，单位 bps，默认范围 [64000, 160000]。仅对 mp3 格式生效。

  • speech_rate integer：语速，取值范围 [-50, 100]，其中 100 代表 2.0 倍速，-50 代表 0.5 倍速。

  • loudness_rate integer：音量，取值范围 [-50, 100]，其中 100 代表 2.0 倍音量，-50 代表 0.5 倍音量。

  • enable_subtitle boolean：是否开启字幕服务，开启后返回字级别的时间戳。默认值 false。

    注意 仅豆包语音合成大模型 2.0 支持该参数，目前仅支持中文、英文

additions string
扩展能力配置，值为 JSON 序列化后的字符串（非 JSON 对象）。用于开启文本过滤、公式播报、上下文感知等高级能力

additions 必须是 JSON 字符串，而非 JSON 对象。即需要先将配置对象用 JSON.stringify() 序列化后再赋值给该字段。各项扩展能力默认值遵循上游模型约定，未传 additions 时按默认配置合成。

属性：

  • max_length_to_filter_parenthesis integer：是否过滤括号内的部分，0 为不过滤，100 为过滤。

  • silence_duration integer：在文本末尾增加静音时长，单位 ms，范围 [0, 30000]，默认 0。

  • disable_markdown_filter boolean：是否开启 Markdown 解析过滤。true 开启（会解析并去除 Markdown 语法，如 **你好** 朗读为"你好"），false 关闭（保留原始字符）。默认 false。

  • disable_emoji_filter boolean：是否开启 Emoji 解析过滤。默认 false。

  • enable_latex_tn boolean：是否启用 LaTeX 文本朗读能力。默认 false。

  • latex_parser string：是否启用更强的 LaTeX 文本朗读能力，可选值 v2。适用于教育场景，启用后时延会增加；开启时需将 disable_markdown_filter 设置为 true。

  • explicit_language string：显式指定朗读语种。开启后仅朗读指定语种的文本，其他语种会被跳过或合成失败。取值：zh-cn（中英混读）、en、ja、es-mx、id、pt-br、pt、ko、it、de、fr、th、vi、ru、fil、ms、ar、pl、tr、sv。

    注意 启用后输入文本须包含指定语种内容，否则无法正常返回

  • explicit_dialect string：指定方言，取值 dongbei（东北话）、shaanxi（陕西话）、sichuan（四川话）。

    注意 使用时 speaker 需设置支持方言的音色

  • aigc_watermark boolean：AIGC 生成标识，开启后会在音频合成结尾添加节奏标识。默认 false。

  • aigc_metadata object：在合成音频中添加 meta 水印，支持 mp3 / wav / ogg_opus。

    • enable boolean：是否启用 meta 隐式水印。默认 false。
    • content_producer string：合成服务提供者的名称或编码。
    • produce_id string：内容制作编号。
    • content_propagator string：内容传播服务提供者的名称或编码。
    • propagate_id string：内容传播编号。

  • cache_config object：缓存相关配置。

    • text_type integer：文本类型标识。需和 use_cache 一起使用，需要开启缓存时取 0。
    • use_cache boolean：是否启用缓存。需和 text_type 一起使用，需要开启缓存时传 true。

  • post_process object：后处理配置。

    • pitch integer：音调，取值范围 [-12, 12]。

  • context_texts array of string：语音指令，可根据语境动态调整语气、停顿与情感表达。

    当 speaker 设置为 豆包语音合成模型 2.0 音色 时，可直接使用语音指令；设置为复刻音色时暂不支持。该字段文本不参与计费。

    示例："context_texts": ["Can you speak in a really, really sorrowful tone?"]

  • section_id string：段落标识，用于跨包语义保持。支持 豆包语音合成模型 2.0 音色、豆包声音复刻大模型 2.0 音色。

  • tone_fidelity boolean：是否开启还原模式，开启后模型将尽可能还原训练 prompt 音频的音色和说话风格（情感、韵律、口音等）。默认 false。

    注意 仅适用于豆包声音复刻大模型 2.0 音色，仅支持合成和训练音频同语种的文本，不支持跨语种合成，不支持双向流合成接口

响应参数 ​

响应为连续 JSON 对象流（NDJSON），每个 chunk 为一行独立的 JSON 对象，客户端需按行读取并解析。

流式响应处理逻辑 ​

每个 chunk 通过 code 字段判断类型：

code含义处理方式
0正常音频数据帧解析 data 字段，base64 解码后拼接为完整音频
20000000合成结束结束读取，本次合成完成
其他正数错误解析 message 获取错误信息，终止本次合成
  • 音频片段需按返回顺序逐段 base64 解码并顺序拼接，拼接后的二进制数据即为完整的音频文件。
  • 当 code 为 0 但 data 为 null 时，该帧不携带音频数据，通常为字幕帧或结束前的尾帧，可安全跳过。
  • 计费结算以最后一个携带 usage 字段的数据帧为准。

响应字段 ​

X-Tt-Logid string ​

服务端返回的 logid，用于在咨询或者反馈时定位问题。

code integer ​

状态码。取值：

  • 0：正常数据帧
  • 20000000：合成结束
  • 其他正数：错误码

message string ​

状态详情。code 为 0 时通常为空，错误时为错误描述。

data string ​

合成音频数据，base64 编码。code 为 0 时携带，需 base64 解码后与其它片段顺序拼接。

sentence object ​

字幕信息。仅当请求中 audio_params.enable_subtitle 为 true 时返回。

属性：

  • text string：合成音频文本。
  • phonemes array：音素相关时间戳。
  • words array of object：字级别时间戳。
    • word string：单字 / 词文本。
    • startTime number：起始时间（秒）。
    • endTime number：结束时间（秒）。
    • confidence number：时间戳置信度，范围 0~1。

usage object ​

本次请求的资源消耗统计，用于计费结算。

属性：

  • text_words integer：本次请求计费的文本字数（含标点）。最终结算以此字段为准，预冻结时多冻结的额度会自动释放。