Unidirectional Streaming Speech Synthesis HTTP API

This document describes the input and output parameters of the Unidirectional Streaming Speech Synthesis API for your reference when using the interface. A unidirectional streaming synthesis interface based on the HTTP Chunked protocol. It takes text as input once and returns audio in a streaming manner, supporting multiple languages and dialects such as Chinese, English, Japanese, Spanish, etc.

 

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

Request Parameters

Request Information

Item	Value
Request Method	POST
Official Request URL	https://ai-tokenhub.com/api/v2/tts/unidirectional
Content-Type	application/json
Authentication	API Key Authentication (Bearer Token)
Transfer Mode	Unidirectional Streaming (NDJSON)

Request Headers

Field Name	Required	Description
Authorization	✓	Format: Bearer <$YOUR_API_KEY>, where <$YOUR_API_KEY> is the long-term API key you obtained from the Tianshu platform
Content-Type	✓	Fixed value: application/json
Connection		Recommended: keep-alive

Request Body

---

model string

The specific model version, used when the speaker parameter is a cloned voice. Default value seed-tts-2.0.

Note This model version does not support the voice instruction context_texts

---

req_params object Required

The speech synthesis request parameter object, containing the text to synthesize, voice, audio parameters, and extended capabilities.

text string Required

The input text to synthesize. Supports 10+ languages including Chinese, English, Japanese, Korean, French, and German, as well as Markdown text and LaTeX formulas.

The character count of this field is the pre-freeze billing basis for this request (1 Chinese character, letter, punctuation mark, space, or line break counts as 1 character). The final settlement is based on usage.text_words in the response. The unit price is 3 RMB / 10,000 characters.

---

speaker string Required

The voice ID, which can be obtained from the Doubao Speech Synthesis Model 2.0 Voice List.

---

ssml string

SSML markup text. When enabled, text is parsed according to SSML rules.

Currently only Chinese and English voices support ssml. See the Doubao Speech Synthesis Model 2.0 Voice List.

---

audio_params object Required

Audio parameters.

Note In streaming scenarios, pcm is recommended; wav is not recommended

Properties:

• format string Required: Audio format, supports mp3 / pcm / ogg_opus / wav, default value mp3.

• sample_rate integer Required: Audio sample rate, in Hz. Optional values: 8000, 16000, 22050, 24000, 32000, 44100, 48000.

• bit_rate integer: Audio bit rate, in bps, default range [64000, 160000]. Only takes effect for mp3 format.

• speech_rate integer: Speaking rate, range [-50, 100], where 100 means 2.0x speed and -50 means 0.5x speed.

• loudness_rate integer: Volume, range [-50, 100], where 100 means 2.0x volume and -50 means 0.5x volume.

• enable_subtitle boolean: Whether to enable the subtitle service. When enabled, word-level timestamps are returned. Default false.

  Note Only supported by Doubao Speech Synthesis Large Model 2.0, currently only for Chinese and English

---

additions string
Extended capability configuration. The value is a JSON-serialized string (not a JSON object). Used to enable advanced capabilities such as text filtering, formula reading, and context-aware synthesis

additions must be a JSON string, not a JSON object. That is, you must first serialize the configuration object with JSON.stringify() before assigning it to this field. The default values of each extended capability follow the upstream model conventions. When additions is not passed, synthesis proceeds with the default configuration.

Properties:

• max_length_to_filter_parenthesis integer: Whether to filter the content inside parentheses. 0 means no filtering, 100 means filter.

• silence_duration integer: Add silence duration at the end of the text, in ms, range [0, 30000], default 0.

• disable_markdown_filter boolean: Whether to enable Markdown parsing and filtering. true to enable (parses and removes Markdown syntax, e.g. **hello** is read as "hello"), false to keep original characters. Default false.

• disable_emoji_filter boolean: Whether to enable Emoji parsing and filtering. Default false.

• enable_latex_tn boolean: Whether to enable LaTeX text reading capability. Default false.

• latex_parser string: Whether to enable a stronger LaTeX text reading capability, optional value v2. Suitable for education scenarios; enabling it increases latency. When enabled, set disable_markdown_filter to true.

• explicit_language string: Explicitly specify the reading language. When enabled, only the text in the specified language is read; other languages will be skipped or fail. Values: zh-cn (Chinese-English mixed), en, ja, es-mx, id, pt-br, pt, ko, it, de, fr, th, vi, ru, fil, ms, ar, pl, tr, sv.

  Note The input text must contain the specified language, otherwise the request will not return normally

• explicit_dialect string: Specify a dialect, values dongbei (Northeastern), shaanxi (Shaanxi), sichuan (Sichuan).

  Note When used, speaker must be set to a voice that supports dialects

• aigc_watermark boolean: AIGC generation identifier. When enabled, a rhythm identifier is added at the end of the synthesized audio. Default false.

• aigc_metadata object: Add a meta watermark to the synthesized audio, supports mp3 / wav / ogg_opus.

  • enable boolean: Whether to enable the meta implicit watermark. Default false.
  • content_producer string: The name or code of the synthesis service provider.
  • produce_id string: Content production number.
  • content_propagator string: The name or code of the content propagation service provider.
  • propagate_id string: Content propagation number.

• cache_config object: Cache-related configuration.

  • text_type integer: Text type identifier. Must be used together with use_cache; set to 0 to enable caching.
  • use_cache boolean: Whether to enable caching. Must be used together with text_type; pass true to enable caching.

• post_process object: Post-processing configuration.

  • pitch integer: Pitch, range [-12, 12].

• context_texts array of string: Voice instructions, dynamically adjusting tone, pauses, and emotional expression based on the context.

  When speaker is set to a Doubao Speech Synthesis Model 2.0 voice, voice instructions can be used directly; not supported for cloned voices. The text in this field is not billed.

  Example: "context_texts": ["Can you speak in a particularly heartbroken tone?"]

• section_id string: Paragraph identifier, used for cross-packet semantic consistency. Supports Doubao Speech Synthesis Model 2.0 voices and Doubao Voice Cloning Large Model 2.0 voices.

• tone_fidelity boolean: Whether to enable restoration mode. When enabled, the model will restore the timbre and speaking style (emotion, prosody, accent, etc.) of the training prompt audio as much as possible. Default false.

  Note Only applicable to Doubao Voice Cloning Large Model 2.0 voices, only supports synthesizing text in the same language as the training audio, does not support cross-language synthesis, and does not support the bidirectional streaming interface

Response Parameters

The response is a continuous stream of JSON objects (NDJSON). Each chunk is an independent JSON object on its own line. The client must read and parse it line by line.

Streaming Response Handling Logic

Determine the type of each chunk via the code field:

code	Meaning	Handling
0	Normal audio data frame	Parse the data field, base64-decode it, and concatenate it into the complete audio
20000000	Synthesis completed	Stop reading; this synthesis is complete
Other positive numbers	Error	Parse message for the error information and terminate this synthesis

• Audio segments must be base64-decoded in the order returned and concatenated in sequence. The concatenated binary data is the complete audio file.
• When code is 0 but data is null, the frame carries no audio data. It is usually a subtitle frame or a trailing frame before the end and can be safely skipped.
• Billing settlement is based on the last data frame that carries the usage field.

Response Fields

---

X-Tt-Logid string

The logid returned by the server, used to locate issues when consulting or providing feedback.

---

code integer

Status code. Values:

• 0: Normal data frame
• 20000000: Synthesis completed
• Other positive numbers: Error code

---

message string

Status details. Usually empty when code is 0; contains the error description on error.

---

data string

Synthesized audio data, base64 encoded. Carried when code is 0; base64-decode it and concatenate it with other segments in order.

---

sentence object

Subtitle information. Returned only when audio_params.enable_subtitle is true in the request.

Properties:

• text string: Synthesized audio text.
• phonemes array: Phoneme-related timestamps.
• words array of object: Word-level timestamps.
  • word string: Word text.
  • startTime number: Start time (seconds).
  • endTime number: End time (seconds).
  • confidence number: Timestamp confidence, range 0~1.

---

usage object

Resource consumption statistics for this request, used for billing settlement.

Properties:

• text_words integer: The billed text word count for this request (including punctuation). The final settlement is based on this field; any over-frozen amount during pre-freeze is automatically released.