cURL

curl --request POST \
  --url https://api.typecast.ai/v1/text-to-speech/with-timestamps \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data @- <<EOF
{
  "voice_id": "tc_60e5426de8b95f1d3000d7b5",
  "text": "Try a 5-minute stretch when you lose focus.",
  "model": "ssfm-v30",
  "language": "eng",
  "prompt": {
    "emotion_type": "preset",
    "emotion_preset": "normal",
    "emotion_intensity": 1.0
  }
}
EOF

import base64
import requests

API_HOST = "https://api.typecast.ai"
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json",
}
payload = {
    "voice_id": "tc_60e5426de8b95f1d3000d7b5",
    "text": "Try a 5-minute stretch when you lose focus.",
    "model": "ssfm-v30",
    "language": "eng",
    "prompt": {
        "emotion_type": "preset",
        "emotion_preset": "normal",
        "emotion_intensity": 1.0,
    },
}

response = requests.post(
    f"{API_HOST}/v1/text-to-speech/with-timestamps",
    headers=headers,
    json=payload,
    timeout=60,
)
response.raise_for_status()
data = response.json()

with open("output.wav", "wb") as f:
    f.write(base64.b64decode(data["audio"]))
print(f"Saved {len(data['audio'])} base64 chars; duration={data['audio_duration']}s")
for w in (data.get("words") or [])[:3]:
    print(f"  word: {w['text']!r} {w['start']:.3f}s - {w['end']:.3f}s")

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    voice_id: 'tc_60e5426de8b95f1d3000d7b5',
    text: 'Everything is so incredibly perfect that I feel like I\'m dreaming.',
    model: 'ssfm-v30',
    language: 'eng',
    prompt: {
      emotion_type: 'smart',
      previous_text: 'I feel like I\'m walking on air and I just want to scream with joy!',
      next_text: 'I am literally bursting with happiness and I never want this feeling to end!'
    },
    output: {
      target_lufs: -14,
      volume: 100,
      audio_pitch: 0,
      audio_tempo: 1,
      audio_format: 'wav'
    },
    seed: 42
  })
};

fetch('https://api.typecast.ai/v1/text-to-speech/with-timestamps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.typecast.ai/v1/text-to-speech/with-timestamps",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'voice_id' => 'tc_60e5426de8b95f1d3000d7b5',
    'text' => 'Everything is so incredibly perfect that I feel like I\'m dreaming.',
    'model' => 'ssfm-v30',
    'language' => 'eng',
    'prompt' => [
        'emotion_type' => 'smart',
        'previous_text' => 'I feel like I\'m walking on air and I just want to scream with joy!',
        'next_text' => 'I am literally bursting with happiness and I never want this feeling to end!'
    ],
    'output' => [
        'target_lufs' => -14,
        'volume' => 100,
        'audio_pitch' => 0,
        'audio_tempo' => 1,
        'audio_format' => 'wav'
    ],
    'seed' => 42
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.typecast.ai/v1/text-to-speech/with-timestamps"

	payload := strings.NewReader("{\n  \"voice_id\": \"tc_60e5426de8b95f1d3000d7b5\",\n  \"text\": \"Everything is so incredibly perfect that I feel like I'm dreaming.\",\n  \"model\": \"ssfm-v30\",\n  \"language\": \"eng\",\n  \"prompt\": {\n    \"emotion_type\": \"smart\",\n    \"previous_text\": \"I feel like I'm walking on air and I just want to scream with joy!\",\n    \"next_text\": \"I am literally bursting with happiness and I never want this feeling to end!\"\n  },\n  \"output\": {\n    \"target_lufs\": -14,\n    \"volume\": 100,\n    \"audio_pitch\": 0,\n    \"audio_tempo\": 1,\n    \"audio_format\": \"wav\"\n  },\n  \"seed\": 42\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.typecast.ai/v1/text-to-speech/with-timestamps")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voice_id\": \"tc_60e5426de8b95f1d3000d7b5\",\n  \"text\": \"Everything is so incredibly perfect that I feel like I'm dreaming.\",\n  \"model\": \"ssfm-v30\",\n  \"language\": \"eng\",\n  \"prompt\": {\n    \"emotion_type\": \"smart\",\n    \"previous_text\": \"I feel like I'm walking on air and I just want to scream with joy!\",\n    \"next_text\": \"I am literally bursting with happiness and I never want this feeling to end!\"\n  },\n  \"output\": {\n    \"target_lufs\": -14,\n    \"volume\": 100,\n    \"audio_pitch\": 0,\n    \"audio_tempo\": 1,\n    \"audio_format\": \"wav\"\n  },\n  \"seed\": 42\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.typecast.ai/v1/text-to-speech/with-timestamps")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"voice_id\": \"tc_60e5426de8b95f1d3000d7b5\",\n  \"text\": \"Everything is so incredibly perfect that I feel like I'm dreaming.\",\n  \"model\": \"ssfm-v30\",\n  \"language\": \"eng\",\n  \"prompt\": {\n    \"emotion_type\": \"smart\",\n    \"previous_text\": \"I feel like I'm walking on air and I just want to scream with joy!\",\n    \"next_text\": \"I am literally bursting with happiness and I never want this feeling to end!\"\n  },\n  \"output\": {\n    \"target_lufs\": -14,\n    \"volume\": 100,\n    \"audio_pitch\": 0,\n    \"audio_tempo\": 1,\n    \"audio_format\": \"wav\"\n  },\n  \"seed\": 42\n}"

response = http.request(request)
puts response.read_body

{
  "audio": "UklGRs...(base64-encoded audio omitted)",
  "audio_format": "wav",
  "audio_duration": 3.38,
  "words": [
    {
      "text": "Try",
      "start": 0.08,
      "end": 0.38
    },
    {
      "text": "a",
      "start": 0.42,
      "end": 0.52
    },
    {
      "text": "5-minute",
      "start": 0.56,
      "end": 1.26
    },
    {
      "text": "stretch",
      "start": 1.3,
      "end": 1.88
    },
    {
      "text": "when",
      "start": 1.92,
      "end": 2.18
    },
    {
      "text": "you",
      "start": 2.22,
      "end": 2.42
    },
    {
      "text": "lose",
      "start": 2.46,
      "end": 2.78
    },
    {
      "text": "focus.",
      "start": 2.82,
      "end": 3.38
    }
  ],
  "characters": [
    {
      "text": "T",
      "start": 0.08,
      "end": 0.18
    },
    {
      "text": "r",
      "start": 0.18,
      "end": 0.27
    },
    {
      "text": "y",
      "start": 0.27,
      "end": 0.38
    },
    {
      "text": " ",
      "start": 0.38,
      "end": 0.42
    },
    {
      "text": "a",
      "start": 0.42,
      "end": 0.52
    },
    {
      "text": " ",
      "start": 0.52,
      "end": 0.56
    },
    {
      "text": "5",
      "start": 0.56,
      "end": 0.7
    },
    {
      "text": "-",
      "start": 0.7,
      "end": 0.76
    },
    {
      "text": "m",
      "start": 0.76,
      "end": 0.86
    },
    {
      "text": "i",
      "start": 0.86,
      "end": 0.94
    },
    {
      "text": "n",
      "start": 0.94,
      "end": 1.04
    },
    {
      "text": "u",
      "start": 1.04,
      "end": 1.12
    },
    {
      "text": "t",
      "start": 1.12,
      "end": 1.2
    },
    {
      "text": "e",
      "start": 1.2,
      "end": 1.26
    },
    {
      "text": " ",
      "start": 1.26,
      "end": 1.3
    },
    {
      "text": "s",
      "start": 1.3,
      "end": 1.4
    },
    {
      "text": "t",
      "start": 1.4,
      "end": 1.47
    },
    {
      "text": "r",
      "start": 1.47,
      "end": 1.56
    },
    {
      "text": "e",
      "start": 1.56,
      "end": 1.64
    },
    {
      "text": "t",
      "start": 1.64,
      "end": 1.72
    },
    {
      "text": "c",
      "start": 1.72,
      "end": 1.8
    },
    {
      "text": "h",
      "start": 1.8,
      "end": 1.88
    },
    {
      "text": " ",
      "start": 1.88,
      "end": 1.92
    },
    {
      "text": "w",
      "start": 1.92,
      "end": 2.02
    },
    {
      "text": "h",
      "start": 2.02,
      "end": 2.08
    },
    {
      "text": "e",
      "start": 2.08,
      "end": 2.14
    },
    {
      "text": "n",
      "start": 2.14,
      "end": 2.18
    },
    {
      "text": " ",
      "start": 2.18,
      "end": 2.22
    },
    {
      "text": "y",
      "start": 2.22,
      "end": 2.3
    },
    {
      "text": "o",
      "start": 2.3,
      "end": 2.38
    },
    {
      "text": "u",
      "start": 2.38,
      "end": 2.42
    },
    {
      "text": " ",
      "start": 2.42,
      "end": 2.46
    },
    {
      "text": "l",
      "start": 2.46,
      "end": 2.56
    },
    {
      "text": "o",
      "start": 2.56,
      "end": 2.64
    },
    {
      "text": "s",
      "start": 2.64,
      "end": 2.72
    },
    {
      "text": "e",
      "start": 2.72,
      "end": 2.78
    },
    {
      "text": " ",
      "start": 2.78,
      "end": 2.82
    },
    {
      "text": "f",
      "start": 2.82,
      "end": 2.92
    },
    {
      "text": "o",
      "start": 2.92,
      "end": 3.02
    },
    {
      "text": "c",
      "start": 3.02,
      "end": 3.12
    },
    {
      "text": "u",
      "start": 3.12,
      "end": 3.22
    },
    {
      "text": "s",
      "start": 3.22,
      "end": 3.32
    },
    {
      "text": ".",
      "start": 3.32,
      "end": 3.38
    }
  ]
}

{
  "detail": "Invalid voice_id"
}

{
  "detail": "Invalid API key"
}

{
  "detail": "Insufficient credit"
}

{
  "detail": "Voice not found"
}

{
  "detail": "Invalid request format"
}

{
  "detail": "Too many requests"
}

{
  "detail": "An unexpected error occurred"
}

Text-to-Speech

Text To Speech with Timestamps

Generate speech from text and return word/character-level timestamps aligned with the audio. Useful for subtitle sync, per-character highlight animation, and speech-region visualization.

The request body matches the standard /v1/text-to-speech endpoint (voice_id, text, model, language, prompt, output, seed). Instead of raw audio bytes, this endpoint returns a JSON object containing base64-encoded audio plus words and characters arrays.

Use the optional granularity query parameter to return only word-level or only character-level timestamps and reduce payload size.

Language note. For languages that do not use whitespace between words — such as Japanese (jpn) and Chinese (zho) — word-level alignment collapses the entire sentence into a single “word”. For those languages, always request granularity=char to receive usable per-character timestamps.

See Listing all voices for available voices.

POST

text-to-speech

with-timestamps

cURL

curl --request POST \
  --url https://api.typecast.ai/v1/text-to-speech/with-timestamps \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data @- <<EOF
{
  "voice_id": "tc_60e5426de8b95f1d3000d7b5",
  "text": "Try a 5-minute stretch when you lose focus.",
  "model": "ssfm-v30",
  "language": "eng",
  "prompt": {
    "emotion_type": "preset",
    "emotion_preset": "normal",
    "emotion_intensity": 1.0
  }
}
EOF

import base64
import requests

API_HOST = "https://api.typecast.ai"
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json",
}
payload = {
    "voice_id": "tc_60e5426de8b95f1d3000d7b5",
    "text": "Try a 5-minute stretch when you lose focus.",
    "model": "ssfm-v30",
    "language": "eng",
    "prompt": {
        "emotion_type": "preset",
        "emotion_preset": "normal",
        "emotion_intensity": 1.0,
    },
}

response = requests.post(
    f"{API_HOST}/v1/text-to-speech/with-timestamps",
    headers=headers,
    json=payload,
    timeout=60,
)
response.raise_for_status()
data = response.json()

with open("output.wav", "wb") as f:
    f.write(base64.b64decode(data["audio"]))
print(f"Saved {len(data['audio'])} base64 chars; duration={data['audio_duration']}s")
for w in (data.get("words") or [])[:3]:
    print(f"  word: {w['text']!r} {w['start']:.3f}s - {w['end']:.3f}s")

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    voice_id: 'tc_60e5426de8b95f1d3000d7b5',
    text: 'Everything is so incredibly perfect that I feel like I\'m dreaming.',
    model: 'ssfm-v30',
    language: 'eng',
    prompt: {
      emotion_type: 'smart',
      previous_text: 'I feel like I\'m walking on air and I just want to scream with joy!',
      next_text: 'I am literally bursting with happiness and I never want this feeling to end!'
    },
    output: {
      target_lufs: -14,
      volume: 100,
      audio_pitch: 0,
      audio_tempo: 1,
      audio_format: 'wav'
    },
    seed: 42
  })
};

fetch('https://api.typecast.ai/v1/text-to-speech/with-timestamps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.typecast.ai/v1/text-to-speech/with-timestamps",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'voice_id' => 'tc_60e5426de8b95f1d3000d7b5',
    'text' => 'Everything is so incredibly perfect that I feel like I\'m dreaming.',
    'model' => 'ssfm-v30',
    'language' => 'eng',
    'prompt' => [
        'emotion_type' => 'smart',
        'previous_text' => 'I feel like I\'m walking on air and I just want to scream with joy!',
        'next_text' => 'I am literally bursting with happiness and I never want this feeling to end!'
    ],
    'output' => [
        'target_lufs' => -14,
        'volume' => 100,
        'audio_pitch' => 0,
        'audio_tempo' => 1,
        'audio_format' => 'wav'
    ],
    'seed' => 42
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.typecast.ai/v1/text-to-speech/with-timestamps"

	payload := strings.NewReader("{\n  \"voice_id\": \"tc_60e5426de8b95f1d3000d7b5\",\n  \"text\": \"Everything is so incredibly perfect that I feel like I'm dreaming.\",\n  \"model\": \"ssfm-v30\",\n  \"language\": \"eng\",\n  \"prompt\": {\n    \"emotion_type\": \"smart\",\n    \"previous_text\": \"I feel like I'm walking on air and I just want to scream with joy!\",\n    \"next_text\": \"I am literally bursting with happiness and I never want this feeling to end!\"\n  },\n  \"output\": {\n    \"target_lufs\": -14,\n    \"volume\": 100,\n    \"audio_pitch\": 0,\n    \"audio_tempo\": 1,\n    \"audio_format\": \"wav\"\n  },\n  \"seed\": 42\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.typecast.ai/v1/text-to-speech/with-timestamps")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voice_id\": \"tc_60e5426de8b95f1d3000d7b5\",\n  \"text\": \"Everything is so incredibly perfect that I feel like I'm dreaming.\",\n  \"model\": \"ssfm-v30\",\n  \"language\": \"eng\",\n  \"prompt\": {\n    \"emotion_type\": \"smart\",\n    \"previous_text\": \"I feel like I'm walking on air and I just want to scream with joy!\",\n    \"next_text\": \"I am literally bursting with happiness and I never want this feeling to end!\"\n  },\n  \"output\": {\n    \"target_lufs\": -14,\n    \"volume\": 100,\n    \"audio_pitch\": 0,\n    \"audio_tempo\": 1,\n    \"audio_format\": \"wav\"\n  },\n  \"seed\": 42\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.typecast.ai/v1/text-to-speech/with-timestamps")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"voice_id\": \"tc_60e5426de8b95f1d3000d7b5\",\n  \"text\": \"Everything is so incredibly perfect that I feel like I'm dreaming.\",\n  \"model\": \"ssfm-v30\",\n  \"language\": \"eng\",\n  \"prompt\": {\n    \"emotion_type\": \"smart\",\n    \"previous_text\": \"I feel like I'm walking on air and I just want to scream with joy!\",\n    \"next_text\": \"I am literally bursting with happiness and I never want this feeling to end!\"\n  },\n  \"output\": {\n    \"target_lufs\": -14,\n    \"volume\": 100,\n    \"audio_pitch\": 0,\n    \"audio_tempo\": 1,\n    \"audio_format\": \"wav\"\n  },\n  \"seed\": 42\n}"

response = http.request(request)
puts response.read_body

{
  "audio": "UklGRs...(base64-encoded audio omitted)",
  "audio_format": "wav",
  "audio_duration": 3.38,
  "words": [
    {
      "text": "Try",
      "start": 0.08,
      "end": 0.38
    },
    {
      "text": "a",
      "start": 0.42,
      "end": 0.52
    },
    {
      "text": "5-minute",
      "start": 0.56,
      "end": 1.26
    },
    {
      "text": "stretch",
      "start": 1.3,
      "end": 1.88
    },
    {
      "text": "when",
      "start": 1.92,
      "end": 2.18
    },
    {
      "text": "you",
      "start": 2.22,
      "end": 2.42
    },
    {
      "text": "lose",
      "start": 2.46,
      "end": 2.78
    },
    {
      "text": "focus.",
      "start": 2.82,
      "end": 3.38
    }
  ],
  "characters": [
    {
      "text": "T",
      "start": 0.08,
      "end": 0.18
    },
    {
      "text": "r",
      "start": 0.18,
      "end": 0.27
    },
    {
      "text": "y",
      "start": 0.27,
      "end": 0.38
    },
    {
      "text": " ",
      "start": 0.38,
      "end": 0.42
    },
    {
      "text": "a",
      "start": 0.42,
      "end": 0.52
    },
    {
      "text": " ",
      "start": 0.52,
      "end": 0.56
    },
    {
      "text": "5",
      "start": 0.56,
      "end": 0.7
    },
    {
      "text": "-",
      "start": 0.7,
      "end": 0.76
    },
    {
      "text": "m",
      "start": 0.76,
      "end": 0.86
    },
    {
      "text": "i",
      "start": 0.86,
      "end": 0.94
    },
    {
      "text": "n",
      "start": 0.94,
      "end": 1.04
    },
    {
      "text": "u",
      "start": 1.04,
      "end": 1.12
    },
    {
      "text": "t",
      "start": 1.12,
      "end": 1.2
    },
    {
      "text": "e",
      "start": 1.2,
      "end": 1.26
    },
    {
      "text": " ",
      "start": 1.26,
      "end": 1.3
    },
    {
      "text": "s",
      "start": 1.3,
      "end": 1.4
    },
    {
      "text": "t",
      "start": 1.4,
      "end": 1.47
    },
    {
      "text": "r",
      "start": 1.47,
      "end": 1.56
    },
    {
      "text": "e",
      "start": 1.56,
      "end": 1.64
    },
    {
      "text": "t",
      "start": 1.64,
      "end": 1.72
    },
    {
      "text": "c",
      "start": 1.72,
      "end": 1.8
    },
    {
      "text": "h",
      "start": 1.8,
      "end": 1.88
    },
    {
      "text": " ",
      "start": 1.88,
      "end": 1.92
    },
    {
      "text": "w",
      "start": 1.92,
      "end": 2.02
    },
    {
      "text": "h",
      "start": 2.02,
      "end": 2.08
    },
    {
      "text": "e",
      "start": 2.08,
      "end": 2.14
    },
    {
      "text": "n",
      "start": 2.14,
      "end": 2.18
    },
    {
      "text": " ",
      "start": 2.18,
      "end": 2.22
    },
    {
      "text": "y",
      "start": 2.22,
      "end": 2.3
    },
    {
      "text": "o",
      "start": 2.3,
      "end": 2.38
    },
    {
      "text": "u",
      "start": 2.38,
      "end": 2.42
    },
    {
      "text": " ",
      "start": 2.42,
      "end": 2.46
    },
    {
      "text": "l",
      "start": 2.46,
      "end": 2.56
    },
    {
      "text": "o",
      "start": 2.56,
      "end": 2.64
    },
    {
      "text": "s",
      "start": 2.64,
      "end": 2.72
    },
    {
      "text": "e",
      "start": 2.72,
      "end": 2.78
    },
    {
      "text": " ",
      "start": 2.78,
      "end": 2.82
    },
    {
      "text": "f",
      "start": 2.82,
      "end": 2.92
    },
    {
      "text": "o",
      "start": 2.92,
      "end": 3.02
    },
    {
      "text": "c",
      "start": 3.02,
      "end": 3.12
    },
    {
      "text": "u",
      "start": 3.12,
      "end": 3.22
    },
    {
      "text": "s",
      "start": 3.22,
      "end": 3.32
    },
    {
      "text": ".",
      "start": 3.32,
      "end": 3.38
    }
  ]
}

{
  "detail": "Invalid voice_id"
}

{
  "detail": "Invalid API key"
}

{
  "detail": "Insufficient credit"
}

{
  "detail": "Voice not found"
}

{
  "detail": "Invalid request format"
}

{
  "detail": "Too many requests"
}

{
  "detail": "An unexpected error occurred"
}

Authorizations

X-API-KEY

string

header

required

API key for authentication. You can obtain an API key from the Typecast API Console.

Query Parameters

granularity

enum<string>

Filter for which timestamp arrays to return.

Omitted: returns both words and characters.
word: returns words only (characters is null).
char: returns characters only (words is null).

Languages without whitespace (e.g., jpn, zho): word alignment yields a single segment covering the whole sentence, so use char to obtain meaningful timestamps.

Available options:

word,

char

Body

application/json

Text-to-speech request parameters

voice_id

string

required

Voice identifier. Two prefixes are supported:

tc_ — Built-in Typecast voices (e.g., tc_60e5426de8b95f1d3000d7b5). See Listing all voices for available IDs.
uc_ — Custom voices created via Instant cloning (e.g., uc_64a1b2c3d4e5f6a7b8c9d0e1). Only the owner of a cloned voice can use it.

Case-sensitive: must use lowercase prefix.

Example:

"tc_60e5426de8b95f1d3000d7b5"

text

string

required

Text to convert to speech. Minimum 1 character, maximum 2000 characters. Credits consumed based on text length. Supports multiple languages including English, Korean, Japanese, and Chinese. Special characters and punctuation are handled automatically.

Required string length: 1 - 2000

Example:

"Everything is so incredibly perfect that I feel like I'm dreaming."

model

enum<string>

required

Voice model to use for speech synthesis.

ssfm-v30: Latest model with improved prosody and additional emotion presets (recommended)
ssfm-v21: Stable production model with reliable quality

Available options:

ssfm-v30,

ssfm-v21

Example:

"ssfm-v30"

language

string

Language code following ISO 639-3 standard. Case-insensitive (both "ENG" and "eng" are accepted). If not provided, will be auto-detected based on text content.

ssfm-v30 Supported Languages (37)

Code	Language	Code	Language	Code	Language
ARA	Arabic	IND	Indonesian	POR	Portuguese
BEN	Bengali	ITA	Italian	RON	Romanian
BUL	Bulgarian	JPN	Japanese	RUS	Russian
CES	Czech	KOR	Korean	SLK	Slovak
DAN	Danish	MSA	Malay	SPA	Spanish
DEU	German	NAN	Min Nan	SWE	Swedish
ELL	Greek	NLD	Dutch	TAM	Tamil
ENG	English	NOR	Norwegian	TGL	Tagalog
FIN	Finnish	PAN	Punjabi	THA	Thai
FRA	French	POL	Polish	TUR	Turkish
HIN	Hindi	UKR	Ukrainian	VIE	Vietnamese
HRV	Croatian	YUE	Cantonese	ZHO	Chinese
HUN	Hungarian

ssfm-v21 Supported Languages (27)

Code	Language	Code	Language	Code	Language
ARA	Arabic	IND	Indonesian	RON	Romanian
BUL	Bulgarian	ITA	Italian	RUS	Russian
CES	Czech	JPN	Japanese	SLK	Slovak
DAN	Danish	KOR	Korean	SPA	Spanish
DEU	German	MSA	Malay	SWE	Swedish
ELL	Greek	NLD	Dutch	TAM	Tamil
ENG	English	POL	Polish	TGL	Tagalog
FIN	Finnish	POR	Portuguese	UKR	Ukrainian
FRA	French	HRV	Croatian	ZHO	Chinese

Timestamp endpoint note. For languages without inter-word whitespace — Japanese (jpn) and Chinese (zho) — word-level alignment collapses the whole sentence into a single segment. Always pair these languages with granularity=char to receive usable per-character timestamps.

Example:

"eng"

prompt

SmartPrompt (ssfm-v30) · object

Emotion and style settings for the generated speech.

SmartPrompt (ssfm-v30)
PresetPrompt (ssfm-v30)
Prompt (ssfm-v21)

Show child attributes

Example:

{
  "emotion_type": "smart",
  "previous_text": "I feel like I'm walking on air and I just want to scream with joy!",
  "next_text": "I am literally bursting with happiness and I never want this feeling to end!"
}

output

Output · object

Audio output settings including volume (0-200), pitch (-12 to +12 semitones), tempo (0.5x to 2.0x), and format (wav/mp3) for controlling the final audio characteristics

Show child attributes

seed

integer<uint32>

Unsigned integer seed for reproducible speech generation. The same seed with the same input parameters will produce identical audio output.

Must be a non-negative integer (≥ 0). Negative values are not accepted.
If omitted, the server generates a random seed each time, producing slight variations.

Required range: 0 <= x <= 4294967295

Example:

42

Response

Success - Returns base64 audio and timestamps

Response payload for POST /v1/text-to-speech/with-timestamps — base64-encoded audio plus per-word and per-character timestamps aligned with the generated speech.

audio

string

required

Base64-encoded audio bytes. Decode and write to a file using the audio_format extension.

audio_format

enum<string>

required

Audio encoding format of the bytes in audio — either wav or mp3, mirroring the request's output.audio_format.

Available options:

wav,

mp3

audio_duration

number

required

Length of the generated audio in seconds.

words

AlignmentSegmentWord · object[] | null

required

Word-level timestamps (with attached punctuation). null when the request uses granularity=char.

Show child attributes

characters

AlignmentSegmentCharacter · object[] | null

required

Character-level timestamps (including punctuation and whitespace). null when the request uses granularity=word.

Show child attributes

Compose Text To Speech Streaming Text To Speech

⌘I

Text-to-Speech

Voices

Subscription

Text To Speech with Timestamps

Authorizations

Query Parameters

Body

Response