Convert Text to Audio - Dify Docs

POST

/

text-to-audio

Convert Text to Audio

curl --request POST \
  --url https://{api_base_url}/text-to-audio \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "Hello, welcome to our service.",
  "user": "abc-123",
  "voice": "alloy",
  "streaming": false
}
'

import requests

url = "https://{api_base_url}/text-to-audio"

payload = {
    "text": "Hello, welcome to our service.",
    "user": "abc-123",
    "voice": "alloy",
    "streaming": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: 'Hello, welcome to our service.',
    user: 'abc-123',
    voice: 'alloy',
    streaming: false
  })
};

fetch('https://{api_base_url}/text-to-audio', 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_base_url}/text-to-audio",
  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' => 'Hello, welcome to our service.',
    'user' => 'abc-123',
    'voice' => 'alloy',
    'streaming' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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_base_url}/text-to-audio"

	payload := strings.NewReader("{\n  \"text\": \"Hello, welcome to our service.\",\n  \"user\": \"abc-123\",\n  \"voice\": \"alloy\",\n  \"streaming\": false\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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_base_url}/text-to-audio")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"Hello, welcome to our service.\",\n  \"user\": \"abc-123\",\n  \"voice\": \"alloy\",\n  \"streaming\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{api_base_url}/text-to-audio")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"Hello, welcome to our service.\",\n  \"user\": \"abc-123\",\n  \"voice\": \"alloy\",\n  \"streaming\": false\n}"

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

"<string>"

Authorizations

Authorization

string

header

required

Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Body

application/json

Request body for text-to-audio conversion. Provide either message_id or text.

message_id

string<uuid>

ID of the message whose answer to voice. Takes priority over text when both are provided. Get message IDs from List Conversation Messages.

text

string

Text to synthesize into speech.

user

string

End-user identifier, defined by your app and unique within it. See End User Identity.

voice

string

Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the voice value from Get App Parameters → text_to_speech.voice for the default.

streaming

boolean

Accepted for backward compatibility but has no effect. Whether the audio is streamed is determined by the configured TTS provider's output, not by this field.

Response

Returns the generated audio. The Content-Type header reflects the provider's audio container, verified from the response bytes when recognizable.

The body can be AAC, FLAC, MP4, MP3, Ogg, WAV, or WebM. Output that cannot be recognized is labeled with the provider's declared type, or audio/mpeg when none is declared.

Streamed provider output is delivered with chunked transfer encoding; the request streaming field does not control this.

The response is of type file.

Last modified on August 24, 2026

Convert Text to Audio

curl --request POST \
  --url https://{api_base_url}/text-to-audio \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "Hello, welcome to our service.",
  "user": "abc-123",
  "voice": "alloy",
  "streaming": false
}
'

import requests

url = "https://{api_base_url}/text-to-audio"

payload = {
    "text": "Hello, welcome to our service.",
    "user": "abc-123",
    "voice": "alloy",
    "streaming": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: 'Hello, welcome to our service.',
    user: 'abc-123',
    voice: 'alloy',
    streaming: false
  })
};

fetch('https://{api_base_url}/text-to-audio', 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_base_url}/text-to-audio",
  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' => 'Hello, welcome to our service.',
    'user' => 'abc-123',
    'voice' => 'alloy',
    'streaming' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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_base_url}/text-to-audio"

	payload := strings.NewReader("{\n  \"text\": \"Hello, welcome to our service.\",\n  \"user\": \"abc-123\",\n  \"voice\": \"alloy\",\n  \"streaming\": false\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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_base_url}/text-to-audio")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"Hello, welcome to our service.\",\n  \"user\": \"abc-123\",\n  \"voice\": \"alloy\",\n  \"streaming\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{api_base_url}/text-to-audio")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"Hello, welcome to our service.\",\n  \"user\": \"abc-123\",\n  \"voice\": \"alloy\",\n  \"streaming\": false\n}"

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

"<string>"