Class: Telnyx::Resources::VoiceDesigns

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/resources/voice_designs.rb

Overview

Create and manage AI-generated voice designs using natural language prompts.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ VoiceDesigns

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of VoiceDesigns.

Parameters:



223
224
225
 
# File 'lib/telnyx/resources/voice_designs.rb', line 223

def initialize(client:)
  @client = client
end

Instance Method Details

#create(prompt:, text:, language: nil, max_new_tokens: nil, name: nil, provider: nil, repetition_penalty: nil, temperature: nil, top_k: nil, top_p: nil, voice_design_id: nil, request_options: {}) ⇒ Telnyx::Models::VoiceDesignCreateResponse

Some parameter documentations has been truncated, see Models::VoiceDesignCreateParams for more details.

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.

Parameters:

  • prompt (String) —

    Natural language description of the voice style, e.g. ‘Speak in a warm, friendly

  • text (String) —

    Sample text to synthesize for this voice design.

  • language (String) —

    Language for synthesis. Supported values: Auto, Chinese, English, Japanese, Kore

  • max_new_tokens (Integer) —

    Maximum number of tokens to generate. Default: 2048.

  • name (String) —

    Name for the voice design. Required when creating a new design (‘voice_design_id

  • provider (Symbol, Telnyx::Models::VoiceDesignCreateParams::Provider) —

    Voice synthesis provider. ‘telnyx` uses the Qwen3TTS model; `minimax` uses the M

  • repetition_penalty (Float) —

    Repetition penalty to reduce repeated patterns in generated audio. Default: 1.05

  • temperature (Float) —

    Sampling temperature controlling randomness. Higher values produce more varied o

  • top_k (Integer) —

    Top-k sampling parameter — limits the token vocabulary considered at each step.

  • top_p (Float) —

    Top-p (nucleus) sampling parameter — cumulative probability cutoff for token sel

  • voice_design_id (String) —

    ID of an existing voice design to add a new version to. When provided, a new ver

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



43
44
45
46
47
48
49
50
51
52
 
# File 'lib/telnyx/resources/voice_designs.rb', line 43

def create(params)
  parsed, options = Telnyx::VoiceDesignCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "voice_designs",
    body: parsed,
    model: Telnyx::Models::VoiceDesignCreateResponse,
    options: options
  )
end

#delete(id, request_options: {}) ⇒ nil

Permanently deletes a voice design and all of its versions. This action cannot be undone.

Parameters:

  • id (String) —

    The voice design UUID or name.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



128
129
130
131
132
133
134
135
 
# File 'lib/telnyx/resources/voice_designs.rb', line 128

def delete(id, params = {})
  @client.request(
    method: :delete,
    path: ["voice_designs/%1$s", id],
    model: NilClass,
    options: params[:request_options]
  )
end

#delete_version(version, id:, request_options: {}) ⇒ nil

Permanently deletes a specific version of a voice design. The version number must be a positive integer.

Parameters:

  • version (Integer) —

    The version number to delete.

  • id (String) —

    The voice design UUID or name.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/telnyx/resources/voice_designs.rb', line 151

def delete_version(version, params)
  parsed, options = Telnyx::VoiceDesignDeleteVersionParams.dump_request(params)
  id =
    parsed.delete(:id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :delete,
    path: ["voice_designs/%1$s/versions/%2$s", id, version],
    model: NilClass,
    options: options
  )
end

#download_sample(id, version: nil, request_options: {}) ⇒ StringIO

Some parameter documentations has been truncated, see Models::VoiceDesignDownloadSampleParams for more details.

Downloads the WAV audio sample for the voice design. Returns the latest version’s sample by default, or a specific version when ‘?version=N` is provided. The `id` parameter accepts either a UUID or the design name.

Parameters:

  • id (String) —

    The voice design UUID or name.

  • version (Integer) —

    Specific version number to download the sample for. Defaults to the latest versi

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (StringIO)

See Also:



183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/telnyx/resources/voice_designs.rb', line 183

def download_sample(id, params = {})
  parsed, options = Telnyx::VoiceDesignDownloadSampleParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["voice_designs/%1$s/sample", id],
    query: query,
    headers: {"accept" => "audio/wav"},
    model: StringIO,
    options: options
  )
end

#list(filter_name: nil, page_number: nil, page_size: nil, sort: nil, request_options: {}) ⇒ Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::VoiceDesignListResponse>

Returns a paginated list of voice designs belonging to the authenticated account.

Parameters:

  • filter_name (String) —

    Case-insensitive substring filter on the name field.

  • page_number (Integer) —

    Page number for pagination (1-based).

  • page_size (Integer) —

    Number of results per page.

  • sort (Symbol, Telnyx::Models::VoiceDesignListParams::Sort) —

    Sort order. Prefix with ‘-` for descending. Defaults to `-created_at`.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/telnyx/resources/voice_designs.rb', line 99

def list(params = {})
  parsed, options = Telnyx::VoiceDesignListParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "voice_designs",
    query: query.transform_keys(
      filter_name: "filter[name]",
      page_number: "page[number]",
      page_size: "page[size]"
    ),
    page: Telnyx::Internal::DefaultFlatPagination,
    model: Telnyx::Models::VoiceDesignListResponse,
    options: options
  )
end

#rename(id, name:, request_options: {}) ⇒ Telnyx::Models::VoiceDesignRenameResponse

Updates the name of a voice design. All versions retain their other properties.

Parameters:

  • id (String) —

    The voice design UUID or name.

  • name (String) —

    New name for the voice design.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



209
210
211
212
213
214
215
216
217
218
 
# File 'lib/telnyx/resources/voice_designs.rb', line 209

def rename(id, params)
  parsed, options = Telnyx::VoiceDesignRenameParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["voice_designs/%1$s", id],
    body: parsed,
    model: Telnyx::Models::VoiceDesignRenameResponse,
    options: options
  )
end

#retrieve(id, version: nil, request_options: {}) ⇒ Telnyx::Models::VoiceDesignRetrieveResponse

Returns the latest version of a voice design, or a specific version when ‘?version=N` is provided. The `id` parameter accepts either a UUID or the design name.

Parameters:

  • id (String) —

    The voice design UUID or name.

  • version (Integer) —

    Specific version number to retrieve. Defaults to the latest version.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/telnyx/resources/voice_designs.rb', line 69

def retrieve(id, params = {})
  parsed, options = Telnyx::VoiceDesignRetrieveParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["voice_designs/%1$s", id],
    query: query,
    model: Telnyx::Models::VoiceDesignRetrieveResponse,
    options: options
  )
end