Skip to main content
POST
/
tts
/
retroactive
Submit a retroactive TTS generation request
curl --request POST \
  --url https://restapi.deepdub.ai/api/v1/tts/retroactive \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "model": "dd-etts-3.0",
  "targetText": "Hello world, welcome to Deepdub.",
  "locale": "en-US",
  "voicePromptId": "bd1b00bb-be1c-4679-8eaa-0fcbfd4ff773"
}
'
{
  "url": "https://restapi.deepdub.ai/api/v1/tts/retroactive/abc123-def456"
}

​
When to use the retroactive endpoint

POST /tts/retroactive accepts the same request body as POST /tts, but instead of streaming audio in the HTTP response it queues the generation and returns a URL. Fetch that URL later (with the same x-api-key header) to retrieve the audio via GET /tts/retroactive/{id}.
Use this whenUse streaming POST /tts when
You’re generating a long script and don’t need bytes immediatelyYou need audio to start playing as soon as possible
You’re orchestrating a batch workflow (e.g., dubbing, prerendering)You’re building a real-time interaction
You want to retry the download without re-running generationThe request fits comfortably in a single HTTP response
The returned URL embeds the generation id. Store it (or the id) so you can retrieve the audio later.

Authorizations

​
x-api-key
string
header
required

API key for authentication. Must start with dd- prefix.

Headers

​
x-api-key
string
default:dd-00000000000000000000000065c9cbfe
required

API Key

Body

application/json

Request structure for TTS generation endpoints.

Optional parameters (not shown in playground): generationId (string), targetDuration (number, seconds), tempo (number, 0.5–2.0), variance (number, 0.0–1.0), seed (integer), temperature (number, 0.0–1.0), sampleRate (integer), format (string: mp3/opus/mulaw — default mp3), promptBoost (boolean), superStretch (boolean), realtime (boolean), cleanAudio (boolean, default true), autoGain (boolean), publish (boolean), accentControl (object with accentBaseLocale, accentLocale, accentRatio), performanceReferencePromptId (string), voiceReference (string, base64-encoded audio).

​
model
string
default:dd-etts-3.0
required

Model ID to use for generation

Example:

"dd-etts-3.0"

​
targetText
string
required

Text to be converted to speech

Example:

"Hello world, welcome to Deepdub."

​
locale
string
required

Language locale code (e.g., en-US, fr-FR)

Example:

"en-US"

​
voicePromptId
string
required

ID of the voice prompt to use for generation

Example:

"bd1b00bb-be1c-4679-8eaa-0fcbfd4ff773"

Response

Generation accepted. Returns a URL to fetch the generated audio when ready.

Response containing a URL where the asynchronously generated TTS audio can be retrieved

​
url
string
required

URL to fetch the generated audio (issue a GET request with the same x-api-key header).

Example:

"https://restapi.deepdub.ai/api/v1/tts/retroactive/abc123-def456"