Synthesize audio preview

Generate a TTS audio preview using an existing cache entry’s voice and provider configuration. Returns WAV audio without saving to cache, allowing you to preview how different text or tuning settings would sound before committing changes.

POST /v1/agents/{agentId}/audio-cache/{entryId}/synthesize

Synthesize audio preview

cURL

curl --request POST \
  --url https://api.us.poly.ai/v1/agents/{agentId}/audio-cache/{entryId}/synthesize \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "text": "<string>",
  "config": {
    "stability": 123,
    "similarityBoost": 123,
    "speed": 123,
    "modelId": "<string>",
    "engine": "<string>",
    "emotion": "<string>",
    "volume": 123,
    "version": "<string>",
    "voiceDescription": "<string>",
    "instantMode": true
  },
  "language": "<string>"
}
'

import requests

url = "https://api.us.poly.ai/v1/agents/{agentId}/audio-cache/{entryId}/synthesize"

payload = {
    "text": "<string>",
    "config": {
        "stability": 123,
        "similarityBoost": 123,
        "speed": 123,
        "modelId": "<string>",
        "engine": "<string>",
        "emotion": "<string>",
        "volume": 123,
        "version": "<string>",
        "voiceDescription": "<string>",
        "instantMode": True
    },
    "language": "<string>"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: '<string>',
    config: {
      stability: 123,
      similarityBoost: 123,
      speed: 123,
      modelId: '<string>',
      engine: '<string>',
      emotion: '<string>',
      volume: 123,
      version: '<string>',
      voiceDescription: '<string>',
      instantMode: true
    },
    language: '<string>'
  })
};

fetch('https://api.us.poly.ai/v1/agents/{agentId}/audio-cache/{entryId}/synthesize', 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.us.poly.ai/v1/agents/{agentId}/audio-cache/{entryId}/synthesize",
  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([
    'text' => '<string>',
    'config' => [
        'stability' => 123,
        'similarityBoost' => 123,
        'speed' => 123,
        'modelId' => '<string>',
        'engine' => '<string>',
        'emotion' => '<string>',
        'volume' => 123,
        'version' => '<string>',
        'voiceDescription' => '<string>',
        'instantMode' => true
    ],
    'language' => '<string>'
  ]),
  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.us.poly.ai/v1/agents/{agentId}/audio-cache/{entryId}/synthesize"

	payload := strings.NewReader("{\n  \"text\": \"<string>\",\n  \"config\": {\n    \"stability\": 123,\n    \"similarityBoost\": 123,\n    \"speed\": 123,\n    \"modelId\": \"<string>\",\n    \"engine\": \"<string>\",\n    \"emotion\": \"<string>\",\n    \"volume\": 123,\n    \"version\": \"<string>\",\n    \"voiceDescription\": \"<string>\",\n    \"instantMode\": true\n  },\n  \"language\": \"<string>\"\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.us.poly.ai/v1/agents/{agentId}/audio-cache/{entryId}/synthesize")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"<string>\",\n  \"config\": {\n    \"stability\": 123,\n    \"similarityBoost\": 123,\n    \"speed\": 123,\n    \"modelId\": \"<string>\",\n    \"engine\": \"<string>\",\n    \"emotion\": \"<string>\",\n    \"volume\": 123,\n    \"version\": \"<string>\",\n    \"voiceDescription\": \"<string>\",\n    \"instantMode\": true\n  },\n  \"language\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.us.poly.ai/v1/agents/{agentId}/audio-cache/{entryId}/synthesize")

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  \"text\": \"<string>\",\n  \"config\": {\n    \"stability\": 123,\n    \"similarityBoost\": 123,\n    \"speed\": 123,\n    \"modelId\": \"<string>\",\n    \"engine\": \"<string>\",\n    \"emotion\": \"<string>\",\n    \"volume\": 123,\n    \"version\": \"<string>\",\n    \"voiceDescription\": \"<string>\",\n    \"instantMode\": true\n  },\n  \"language\": \"<string>\"\n}"

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

200

"<string>"

{
  "success": false,
  "error": "<string>",
  "error_id": "<string>",
  "error_code": "<string>",
  "error_message": "<string>",
  "data": "<unknown>"
}

{
  "success": false,
  "error": "<string>",
  "error_id": "<string>",
  "error_code": "<string>",
  "error_message": "<string>",
  "data": "<unknown>"
}

{
  "success": false,
  "error": "<string>",
  "error_id": "<string>",
  "error_code": "<string>",
  "error_message": "<string>",
  "data": "<unknown>"
}

{
  "success": false,
  "error": "<string>",
  "error_id": "<string>",
  "error_code": "<string>",
  "error_message": "<string>",
  "data": "<unknown>"
}

Authorizations

X-API-KEY · string · header · required

Path Parameters

agentId · string · required

entryId · string · required

Audio cache entry ID

Body

application/json

text · string · required

Text to synthesize

config · object · required

Provider-specific voice tuning settings. All fields are optional — each TTS provider uses a different subset.

Show child attributes

language · string

BCP-47 language tag, e.g. 'en-US'

Response

200

audio/wav

Synthesized audio

The response is of type file.