Create or add a version to a voice design
Creates a new voice design (version 1) when voice_design_id is omitted. When voice_design_id is provided, adds a new version to the existing design instead. A design can have at most 50 versions.
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
const voiceDesign = await client.voiceDesigns.create({
prompt: 'Speak in a warm, friendly tone',
text: 'Hello, welcome to our service.',
});
console.log(voiceDesign.data);import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
voice_design = client.voice_designs.create(
prompt="Speak in a warm, friendly tone",
text="Hello, welcome to our service.",
)
print(voice_design.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
voiceDesign, err := client.VoiceDesigns.New(context.TODO(), telnyx.VoiceDesignNewParams{
Prompt: "Speak in a warm, friendly tone",
Text: "Hello, welcome to our service.",
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", voiceDesign.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.voicedesigns.VoiceDesignCreateParams;
import com.telnyx.sdk.models.voicedesigns.VoiceDesignCreateResponse;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
VoiceDesignCreateParams params = VoiceDesignCreateParams.builder()
.prompt("Speak in a warm, friendly tone")
.text("Hello, welcome to our service.")
.build();
VoiceDesignCreateResponse voiceDesign = client.voiceDesigns().create(params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
voice_design = telnyx.voice_designs.create(
prompt: "Speak in a warm, friendly tone",
text: "Hello, welcome to our service."
)
puts(voice_design)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$voiceDesign = $client->voiceDesigns->create(
prompt: 'Speak in a warm, friendly tone',
text: 'Hello, welcome to our service.',
language: 'Auto',
maxNewTokens: 100,
name: 'friendly-narrator',
provider: 'telnyx',
repetitionPenalty: 1,
temperature: 0,
topK: 1,
topP: 0,
voiceDesignID: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
var_dump($voiceDesign);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx voice-designs create \
--api-key 'My API Key' \
--prompt 'Speak in a warm, friendly tone' \
--text 'Hello, welcome to our service.'curl --request POST \
--url https://api.telnyx.com/v2/voice_designs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "friendly-narrator",
"text": "Hello, welcome to our service.",
"prompt": "Speak in a warm, friendly tone",
"language": "Auto",
"provider": "telnyx"
}
'{
"data": {
"record_type": "voice_design",
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "friendly-narrator",
"version": 1,
"text": "Hello, welcome.",
"prompt": "Speak in a warm tone",
"voice_sample_size": 48000,
"version_created_at": "2024-01-01T00:00:00Z",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"provider": "Telnyx",
"provider_supported_models": [
"Qwen3TTS"
],
"provider_voice_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Request body for creating a new voice design or adding a version to an existing one. Omit voice_design_id to create a new design; include it to add a new version.
Sample text to synthesize for this voice design.
Natural language description of the voice style, e.g. 'Speak in a warm, friendly tone with a slight British accent'.
Name for the voice design. Required when creating a new design (voice_design_id is not provided); ignored when adding a version. Cannot be a UUID.
1 - 255ID of an existing voice design to add a new version to. When provided, a new version is created instead of a new design.
Language for synthesis. Supported values: Auto, Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, Italian. Defaults to Auto.
Sampling temperature controlling randomness. Higher values produce more varied output. Default: 0.9.
0 <= x <= 2Top-k sampling parameter — limits the token vocabulary considered at each step. Default: 50.
1 <= x <= 1000Top-p (nucleus) sampling parameter — cumulative probability cutoff for token selection. Default: 1.0.
0 <= x <= 1Repetition penalty to reduce repeated patterns in generated audio. Default: 1.05.
1 <= x <= 2Maximum number of tokens to generate. Default: 2048.
100 <= x <= 4096Voice synthesis provider. telnyx uses the Qwen3TTS model; minimax uses the Minimax speech models. Case-insensitive. Defaults to telnyx.
telnyx, minimax, Telnyx, Minimax Response
Voice design created or new version added successfully.
Response envelope for a single voice design with full version detail.
A voice design object with full version detail.
Show child attributes
Show child attributes
Was this page helpful?
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
const voiceDesign = await client.voiceDesigns.create({
prompt: 'Speak in a warm, friendly tone',
text: 'Hello, welcome to our service.',
});
console.log(voiceDesign.data);import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
voice_design = client.voice_designs.create(
prompt="Speak in a warm, friendly tone",
text="Hello, welcome to our service.",
)
print(voice_design.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
voiceDesign, err := client.VoiceDesigns.New(context.TODO(), telnyx.VoiceDesignNewParams{
Prompt: "Speak in a warm, friendly tone",
Text: "Hello, welcome to our service.",
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", voiceDesign.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.voicedesigns.VoiceDesignCreateParams;
import com.telnyx.sdk.models.voicedesigns.VoiceDesignCreateResponse;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
VoiceDesignCreateParams params = VoiceDesignCreateParams.builder()
.prompt("Speak in a warm, friendly tone")
.text("Hello, welcome to our service.")
.build();
VoiceDesignCreateResponse voiceDesign = client.voiceDesigns().create(params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
voice_design = telnyx.voice_designs.create(
prompt: "Speak in a warm, friendly tone",
text: "Hello, welcome to our service."
)
puts(voice_design)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$voiceDesign = $client->voiceDesigns->create(
prompt: 'Speak in a warm, friendly tone',
text: 'Hello, welcome to our service.',
language: 'Auto',
maxNewTokens: 100,
name: 'friendly-narrator',
provider: 'telnyx',
repetitionPenalty: 1,
temperature: 0,
topK: 1,
topP: 0,
voiceDesignID: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
var_dump($voiceDesign);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx voice-designs create \
--api-key 'My API Key' \
--prompt 'Speak in a warm, friendly tone' \
--text 'Hello, welcome to our service.'curl --request POST \
--url https://api.telnyx.com/v2/voice_designs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "friendly-narrator",
"text": "Hello, welcome to our service.",
"prompt": "Speak in a warm, friendly tone",
"language": "Auto",
"provider": "telnyx"
}
'{
"data": {
"record_type": "voice_design",
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "friendly-narrator",
"version": 1,
"text": "Hello, welcome.",
"prompt": "Speak in a warm tone",
"voice_sample_size": 48000,
"version_created_at": "2024-01-01T00:00:00Z",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"provider": "Telnyx",
"provider_supported_models": [
"Qwen3TTS"
],
"provider_voice_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "Voice design not found"
}
]
}