eleven_rb 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed711abcce18771ad13f10bcb29754605be61f7d02f7114f0e0b28b0dad4d556
-  data.tar.gz: 146285726bc80b0c3eab0b307a7ec4b788a8f3465903992bb12fc2b34bc1694b
+  metadata.gz: 18424bceaba545d05f991cb1ae674fdc36572a7a9573ef769701deb35537b393
+  data.tar.gz: a5c2a3814295f5d19945b1731b639fe21ae0f0111ef51741fdb99bae5a978cf7
 SHA512:
-  metadata.gz: 6bf8e216c83287bb099e4a6bbed4ef718329f361fb7dfb4c70bf122f2512c74916eb1540fe6a1dfd4ae01e0edc53edc05408a017946f504c09611a54a6c2370b
-  data.tar.gz: 1839c52e3adf4efed58c410f08fa5c5e4818fde0964922e0752019b6606d726ed66a4f48a767b4e2110aa3b0cf98e7f4666eaef64552ec9f0f976378b1ef5094
+  metadata.gz: af3da66572e56a9173b5f427a3fa30212ebd686a5820b060ab5c81e5e41d60ae64a74e7956e0ddad4365d0f8e68ceefaa5572d97f485a0e424609c195f34be31
+  data.tar.gz: 3af1d07b75e5405724c50e87d3b89f88061d3540043716b38242acce0941f5152294148cd1d9109c20f05bbd05f5131e6b1225260bd373371b45061ad4bbca26

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-30
+
+### Added
+
+- Eleven v4 support (`eleven_v4`, `eleven_v4_turbo`) across Text-to-Speech and Text-to-Dialogue
+- `ElevenRb::ModelCapabilities` — per model-family table of honoured voice settings, max text length, SSML `<break>` support, audio-tag support and continuity support (`for`, `supported_voice_settings`, `max_text_length`, `supports?`)
+- `Objects::VoiceSettings.for_model(model_id, overrides)` → `[settings, dropped_keys]`, building only the settings a model honours
+- `Configuration#strict_voice_settings` (default `false`): raise `ValidationError` instead of warning when a voice setting the model ignores is passed
+- Optional TTS keywords on `generate`, `stream` and `generate_with_timestamps` (omitted from the body when nil): `language_code`, `apply_text_normalization`, `seed`, `previous_text`, `next_text`, `previous_request_ids`, `next_request_ids`, `pronunciation_dictionary_locators`, `use_pvc_as_ivc`
+- Response metadata: `Objects::Audio#request_id`, `#character_cost` (from the `request-id` / `character-cost` headers) and `#dropped_settings`; `on_audio_generated` also receives `request_id:` (nil for streams)
+- `TextToSpeech#generate_with_timestamps` now also returns `normalized_alignment`, `request_id` and `character_cost`
+- `TextToDialogue#generate_with_timestamps` (`POST /v1/text-to-dialogue/with-timestamps`) returning `audio`, `alignment`, `normalized_alignment`, `voice_segments` and `request_id`
+- Text-to-Dialogue keywords `use_pvc_as_ivc`, `previous_text`, `future_text`, `previous_request_ids`, `next_request_ids`, `pronunciation_dictionary_locators`; a logger warning above `RECOMMENDED_MAX_TEXT_LENGTH` (2,000 characters)
+- `HTTP::Client#post(..., with_meta: true)` returning `{ body:, headers: }`, and `Resources::Base#post_with_meta` / `#post_binary_with_meta`
+- `Models#find(model_id)`
+- `Objects::Model#model_rates`, `#maximum_text_length_per_request`, `#requires_alpha_access`, `#supported_voice_settings`
+- `CostInfo::COST_PER_1K_CHARS` entries for `eleven_v4` ($0.30), `eleven_v4_turbo` ($0.15) and `eleven_v3_conversational` ($0.15)
+- `opus_*` output formats map to the `ogg` extension and `audio/ogg` content type
+
+### Changed
+
+- Voice settings are filtered per model: known keys a model ignores (`stability`, `similarity_boost`, `style`, `use_speaker_boost`, `speed` minus the model's supported set) are dropped from the request (logged, and listed on `audio.dropped_settings`); unknown voice-setting keys pass through untouched on every model, so a new API field is never swallowed. `eleven_v3` / `eleven_v4` now send only `stability` and `similarity_boost` by default; `eleven_multilingual_v2` requests are byte-identical to 1.0.0. Override keys are symbolized and nil values removed (a nil override is never reported as dropped)
+- Text length is capped per model (`ModelCapabilities.max_text_length`): 5,000 for `eleven_v3`, 10,000 for `eleven_v4` and `eleven_multilingual_v2`, 30,000 / 40,000 for the flash and turbo models. `TextToSpeech::MAX_TEXT_LENGTH` stays defined but is no longer the cap
+- `TextToDialogue::DEFAULT_MODEL` is now `eleven_v4`
+- Text-to-Dialogue's hard text cap now follows the model (10,000 characters on `eleven_v4`, 5,000 on `eleven_v3`) instead of a flat 5,000; `TextToDialogue::MAX_TEXT_LENGTH` stays defined but is no longer the cap
+- `Models#latest` returns `eleven_v4`, else `eleven_v3`, else the default model
+- `TextToSpeech::OUTPUT_FORMATS` refreshed to the current list (documentation only, not validated)
+- Callbacks that declare their keywords explicitly (no `**rest`) receive only the keywords they declare, so callbacks written for 1.0.0 keep working as new keywords are added
+
+### Fixed
+
+- `Models#list` (and everything built on it: `get`, `default`, `latest`, `multilingual`, `turbo`, `tts_capable`, `ids`, `TTSAdapter#list_models`) recursed until `SystemStackError`, because `Models#get(model_id)` shadowed `Resources::Base#get`
+
 ## [1.0.0] - 2026-03-10
 
 ### Added

data/README.md

@@ -11,6 +11,7 @@ A Ruby client for the [ElevenLabs](https://try.elevenlabs.io/qyk2j8gumrjz) Text-
 - Text-to-Speech generation and streaming
 - Speech-to-Speech voice conversion
 - Text-to-Dialogue multi-speaker generation with audio tags
+- Eleven v4 support, with per-model voice-settings filtering and text caps
 - Sound effects generation from text descriptions
 - Music generation from prompts or composition plans
 - Voice management (list, get, create, update, delete)
@@ -74,7 +75,7 @@ audio.save_to_file("output.mp3")
 audio = client.tts.generate(
   "Hello world",
   voice_id: "voice_id",
-  model_id: "eleven_v3",             # Most expressive, 70+ languages, audio tags
+  model_id: "eleven_v4",             # Most expressive; audio tags; see "Eleven v4" below
   voice_settings: {
     stability: 0.5,
     similarity_boost: 0.75
@@ -88,8 +89,72 @@ File.open("output.mp3", "wb") do |file|
     file.write(chunk)
   end
 end
+
+# Word-level timestamps
+result = client.tts.generate_with_timestamps("Hello world", voice_id: "voice_id")
+result[:audio]                 # => ElevenRb::Objects::Audio
+result[:alignment]             # => { "characters" => [...], "character_start_times_seconds" => [...], ... }
+result[:normalized_alignment]
+result[:request_id]            # from the request-id response header
+result[:character_cost]        # Integer, from the character-cost response header
+```
+
+Optional keywords on `generate`, `stream` and `generate_with_timestamps` (each is left out of the request when nil):
+`language_code`, `apply_text_normalization`, `seed`, `previous_text`, `next_text`, `previous_request_ids`,
+`next_request_ids`, `pronunciation_dictionary_locators`, `use_pvc_as_ivc`.
+
+### Eleven v4
+
+`eleven_v4` (and the cheaper, faster `eleven_v4_turbo`) take up to 10,000 characters per request.
+
+```ruby
+audio = client.tts.generate(
+  "[sighs] Right... let's try that one more time.",
+  voice_id: "voice_id",
+  model_id: "eleven_v4",
+  voice_settings: { stability: 0.5, similarity_boost: 0.75 },
+  seed: 42,                                   # reproducible re-rolls
+  previous_text: "That did not go to plan.",  # continuity with the take before
+  next_text: "Here we go."                    # ...and the one after
+)
+audio.request_id        # pass as previous_request_ids: / next_request_ids: on neighbouring takes
+audio.character_cost
+audio.dropped_settings  # => [] (voice settings the gem removed, see below)
+```
+
+- **Only `stability` and `similarity_boost` take effect.** The API accepts `speed`, `style` and
+  `use_speaker_boost` on v4 and silently ignores them, so the gem drops them from the request, logs a
+  warning through `logger`, and lists them on `audio.dropped_settings`. Set
+  `strict_voice_settings: true` on the client to raise `ElevenRb::Errors::ValidationError` instead.
+  Only those known keys are ever dropped: a voice-setting key the gem does not know passes through
+  unchanged on every model, so new API fields keep working.
+  Pace a v4 take with the text (ellipses, pause tags), not `speed`.
+- **SSML `<break time="…"/>` tags are ignored** by v4 (no pause is produced). Use an audio tag or
+  punctuation for pauses.
+- **Audio tags** go in square brackets inside the text: `[sighs]`, `[whispers]`, `[laughs]`,
+  `[short pause]`. Note that tags appear in the returned alignment like any other characters.
+- **Continuity**: `previous_text` / `next_text` (or `previous_request_ids` / `next_request_ids`) tell the
+  model what surrounds a take, so stitched takes keep a consistent delivery.
+- **`seed`** makes v4 generation reproducible, so a re-roll changes one thing at a time.
+
+`ElevenRb::ModelCapabilities` answers these questions for any model id:
+
+```ruby
+ElevenRb::ModelCapabilities.supported_voice_settings("eleven_v4")  # => [:stability, :similarity_boost]
+ElevenRb::ModelCapabilities.max_text_length("eleven_v3")           # => 5000
+ElevenRb::ModelCapabilities.supports?("eleven_v4", :audio_tags)     # => true
+ElevenRb::ModelCapabilities.supports?("eleven_v4", :ssml_break)     # => false
 ```
 
+| Model family | Voice settings honoured | Max chars | Audio tags | SSML breaks |
+|---|---|---|---|---|
+| `eleven_v4`, `eleven_v4_turbo` | stability, similarity_boost | 10,000 | yes | no |
+| `eleven_v3` | stability, similarity_boost | 5,000 | yes | no |
+| `eleven_v3_conversational` | stability, similarity_boost, use_speaker_boost | 5,000 | yes | no |
+| `eleven_flash_v2_5`, `eleven_turbo_v2_5` | all five (incl. style, speed) | 40,000 | no | yes |
+| `eleven_flash_v2`, `eleven_turbo_v2` | all five | 30,000 | no | yes |
+| `eleven_multilingual_v2` and others | all five | 10,000 | no | yes |
+
 ### Speech-to-Speech
 
 ```ruby
@@ -123,30 +188,42 @@ audio = client.text_to_dialogue.generate([
 ])
 audio.save_to_file("dialogue.mp3")
 
-# With options
+# With options (the default model is eleven_v4)
 audio = client.dialogue.generate(
   inputs,
-  model_id: "eleven_v3",
+  model_id: "eleven_v4",
   language_code: "en",
-  settings: { stability: 0.5 },
+  settings: { stability: 0.5, similarity: 0.75 },  # sent to the API unchanged
   seed: 42,
+  previous_text: "Earlier in the scene...",
   output_format: "mp3_44100_192"
 )
+
+# With timestamps and per-speaker segments
+result = client.dialogue.generate_with_timestamps(inputs)
+result[:audio]           # => ElevenRb::Objects::Audio
+result[:alignment]       # character timings
+result[:voice_segments]  # which voice speaks when
+result[:request_id]
 ```
 
+The hard text cap follows the model (10,000 characters for `eleven_v4`, 5,000 for `eleven_v3`); above
+2,000 characters the gem logs a warning, since shorter dialogue requests give more reliable results.
+
 ### Audio Tags
 
-The `eleven_v3` model supports inline audio tags for expressive speech:
+The `eleven_v4` and `eleven_v3` models support inline audio tags, in square brackets, for expressive speech
+(`ElevenRb::ModelCapabilities.supports?(model_id, :audio_tags)`):
 
 ```ruby
 audio = client.tts.generate(
   "[excited] Oh wow, this is AMAZING! [laughs] I can't believe it...",
   voice_id: "voice_id",
-  model_id: "eleven_v3"
+  model_id: "eleven_v4"
 )
 ```
 
-Supported tags include `[laughs]`, `[whispers]`, `[sighs]`, `[excited]`, `[sarcastic]`, `[curious]`, `[pause]`, and more. Use CAPS for emphasis, `...` for pauses, and `—` for interruptions. See the [ElevenLabs v3 documentation](https://elevenlabs.io/docs/guides/audio-tags) for the full list.
+Supported tags include `[laughs]`, `[whispers]`, `[sighs]`, `[excited]`, `[sarcastic]`, `[curious]`, `[short pause]`, and more. Use CAPS for emphasis, `...` for pauses, and `—` for interruptions. See the [ElevenLabs audio tags documentation](https://elevenlabs.io/docs/guides/audio-tags) for the full list.
 
 ### Sound Effects
 
@@ -289,7 +366,7 @@ client = ElevenRb::Client.new(
     Sentry.capture_exception(error, extra: { path: path })
   },
 
-  # Cost tracking
+  # Cost tracking (add request_id: to also receive the API's request id)
   on_audio_generated: ->(audio:, voice_id:, text:, cost_info:) {
     UsageRecord.create!(
       characters: cost_info[:character_count],
@@ -311,8 +388,11 @@ client = ElevenRb::Client.new(
 models = client.models.list
 models.each { |m| puts "#{m.name} (#{m.model_id})" }
 
-# Get the latest/most capable model
-client.models.latest  # => "eleven_v3"
+# Find one model
+client.models.find("eleven_v4")  # => ElevenRb::Objects::Model (get is an alias)
+
+# Get the latest/most capable model: eleven_v4, else eleven_v3, else the default
+client.models.latest.model_id  # => "eleven_v4"
 
 # Get multilingual models
 client.models.multilingual
@@ -343,7 +423,8 @@ client = ElevenRb::Client.new(
   open_timeout: 10,          # Connection timeout
   max_retries: 3,            # Max retry attempts
   retry_delay: 1.0,          # Base delay between retries
-  logger: Rails.logger       # Optional logger
+  logger: Rails.logger,      # Optional logger (receives dropped-setting warnings)
+  strict_voice_settings: false # true: raise instead of dropping settings a model ignores
 )
 ```
 

data/lib/eleven_rb/callbacks.rb

@@ -28,6 +28,10 @@ module ElevenRb
 
     # Trigger a callback if it's configured
     #
+    # A callback that names its keywords explicitly (no `**rest`) receives only
+    # the keywords it declares, so callbacks written before a keyword was added
+    # (e.g. `request_id:` on on_audio_generated in 1.1.0) keep working.
+    #
     # @param callback_name [Symbol] the name of the callback
     # @param kwargs [Hash] keyword arguments to pass to the callback
     # @return [Object, nil] the return value of the callback, or nil
@@ -36,12 +40,32 @@ module ElevenRb
       return unless callback.respond_to?(:call)
 
       begin
-        callback.call(**kwargs)
+        callback.call(**accepted_callback_kwargs(callback, kwargs))
       rescue StandardError => e
         # Don't let callback errors break the main flow
         warn "[ElevenRb] Callback error in #{callback_name}: #{e.message}"
         nil
       end
     end
+
+    private
+
+    def accepted_callback_kwargs(callback, kwargs)
+      params = callback_parameters(callback)
+      return kwargs if params.nil? || params.any? { |type, _| type == :keyrest }
+
+      accepted = params.filter_map { |type, name| name if %i[key keyreq].include?(type) }
+      return kwargs if accepted.empty?
+
+      kwargs.slice(*accepted)
+    end
+
+    def callback_parameters(callback)
+      return callback.parameters if callback.respond_to?(:parameters)
+
+      callback.method(:call).parameters
+    rescue NameError
+      nil
+    end
   end
 end

data/lib/eleven_rb/configuration.rb

@@ -21,12 +21,13 @@ module ElevenRb
       open_timeout: 10,
       max_retries: 3,
       retry_delay: 1.0,
-      retry_statuses: [429, 500, 502, 503, 504].freeze
+      retry_statuses: [429, 500, 502, 503, 504].freeze,
+      strict_voice_settings: false
     }.freeze
 
     attr_accessor :api_key, :base_url, :timeout, :open_timeout,
                   :max_retries, :retry_delay, :retry_statuses,
-                  :logger
+                  :logger, :strict_voice_settings
 
     # Initialize a new configuration
     #
@@ -39,6 +40,8 @@ module ElevenRb
     # @option options [Float] :retry_delay Base delay between retries in seconds (default: 1.0)
     # @option options [Array<Integer>] :retry_statuses HTTP status codes to retry (default: [429, 500, 502, 503, 504])
     # @option options [Logger] :logger Logger instance for debug output
+    # @option options [Boolean] :strict_voice_settings Raise instead of warn when a voice setting the
+    #   model does not honour is passed (default: false)
     # @option options [Proc] :on_request Callback before each request
     # @option options [Proc] :on_response Callback after successful response
     # @option options [Proc] :on_error Callback when an error occurs
@@ -87,7 +90,8 @@ module ElevenRb
         timeout: timeout,
         open_timeout: open_timeout,
         max_retries: max_retries,
-        retry_delay: retry_delay
+        retry_delay: retry_delay,
+        strict_voice_settings: strict_voice_settings
       }
     end
   end

data/lib/eleven_rb/http/client.rb

@@ -32,9 +32,11 @@ module ElevenRb
       # @param path [String] the API path
       # @param body [Hash] request body
       # @param response_type [Symbol] :json or :binary
-      # @return [Hash, Array, String] parsed response
-      def post(path, body = {}, response_type: :json)
-        request(:post, path, body: body, response_type: response_type)
+      # @param with_meta [Boolean] when true, return `{ body:, headers: }` instead of the body alone
+      #   (headers as a Hash of lower-cased String keys to String values)
+      # @return [Hash, Array, String] parsed response (or `{ body:, headers: }` with with_meta)
+      def post(path, body = {}, response_type: :json, with_meta: false)
+        request(:post, path, body: body, response_type: response_type, with_meta: with_meta)
       end
 
       # Make a DELETE request
@@ -68,7 +70,7 @@ module ElevenRb
       private
 
       def request(method, path, body: nil, params: nil, response_type: :json, multipart: false, stream: false,
-                  attempt: 1, &block)
+                  attempt: 1, with_meta: false, &block)
         config.validate!
         url = "#{config.base_url}#{path}"
         start_time = Time.now
@@ -86,15 +88,12 @@ module ElevenRb
           # Trigger after response callback
           config.trigger(:on_response, method: method, path: path, response: response, duration: duration)
 
-          # Return binary data directly
-          return response.body if response_type == :binary && response.success?
-
-          handle_response(response)
+          build_result(response, response_type, with_meta)
         rescue Errors::RateLimitError => e
           config.trigger(:on_rate_limit, retry_after: e.retry_after, error: e)
-          handle_retry(e, method, path, body, params, response_type, multipart, stream, attempt, &block)
+          handle_retry(e, method, path, body, params, response_type, multipart, stream, attempt, with_meta, &block)
         rescue Errors::ServerError => e
-          handle_retry(e, method, path, body, params, response_type, multipart, stream, attempt, &block)
+          handle_retry(e, method, path, body, params, response_type, multipart, stream, attempt, with_meta, &block)
         rescue Errors::Base => e
           config.trigger(:on_error, error: e, method: method, path: path,
                                     context: { body: sanitize_body_for_logging(body) })
@@ -107,6 +106,17 @@ module ElevenRb
         end
       end
 
+      def build_result(response, response_type, with_meta)
+        # Return binary data directly
+        result = if response_type == :binary && response.success?
+                   response.body
+                 else
+                   handle_response(response)
+                 end
+
+        with_meta ? { body: result, headers: normalize_headers(response) } : result
+      end
+
       def execute_request(method, url, body, params, multipart, stream, &block)
         options = build_options(body, params, multipart, stream, &block)
 
@@ -210,7 +220,7 @@ module ElevenRb
         raise error_class.new(message, **error_kwargs)
       end
 
-      def handle_retry(error, method, path, body, params, response_type, multipart, stream, attempt, &block)
+      def handle_retry(error, method, path, body, params, response_type, multipart, stream, attempt, with_meta, &block)
         raise error if attempt > config.max_retries || !config.retry_statuses.include?(error.http_status)
 
         delay = if error.is_a?(Errors::RateLimitError) && error.retry_after
@@ -224,7 +234,17 @@ module ElevenRb
         sleep(delay)
 
         request(method, path,
-                body: body, params: params, response_type: response_type, multipart: multipart, stream: stream, attempt: attempt + 1, &block)
+                body: body, params: params, response_type: response_type, multipart: multipart, stream: stream,
+                attempt: attempt + 1, with_meta: with_meta, &block)
+      end
+
+      # Response headers as a plain Hash of lower-cased String keys to String values
+      # (HTTParty exposes multi-value arrays; the first value is kept)
+      def normalize_headers(response)
+        raw = response.headers.respond_to?(:to_hash) ? response.headers.to_hash : response.headers.to_h
+        raw.each_with_object({}) do |(key, value), out|
+          out[key.to_s.downcase] = value.is_a?(Array) ? value.first : value
+        end
       end
 
       def wrap_error(error)

data/lib/eleven_rb/model_capabilities.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  # What each ElevenLabs model family accepts, keyed by model-id family.
+  #
+  # The API silently ignores voice settings a model does not honour (Eleven v4
+  # accepts `speed`, `style` and `use_speaker_boost` and does nothing with them),
+  # so the gem uses this table to send only the settings that take effect, to
+  # cap text length per model, and to answer feature questions (audio tags,
+  # SSML `<break>` tags, request continuity via previous_text / next_text).
+  #
+  # @example
+  #   ElevenRb::ModelCapabilities.supported_voice_settings('eleven_v4')
+  #   # => [:stability, :similarity_boost]
+  #   ElevenRb::ModelCapabilities.max_text_length('eleven_flash_v2_5') # => 40_000
+  #   ElevenRb::ModelCapabilities.supports?('eleven_v4', :audio_tags)  # => true
+  module ModelCapabilities
+    # Capability record for one model family
+    Capabilities = Struct.new(:voice_settings, :max_text_length, :ssml_break, :audio_tags, :continuity,
+                              keyword_init: true) do
+      def ssml_break? = ssml_break
+      def audio_tags? = audio_tags
+      def continuity? = continuity
+    end
+
+    ALL_VOICE_SETTINGS = %i[stability similarity_boost style use_speaker_boost speed].freeze
+
+    def self.build(voice_settings:, max_text_length:, ssml_break:, audio_tags:, continuity:)
+      Capabilities.new(
+        voice_settings: voice_settings.freeze,
+        max_text_length: max_text_length,
+        ssml_break: ssml_break,
+        audio_tags: audio_tags,
+        continuity: continuity
+      ).freeze
+    end
+    private_class_method :build
+
+    V4 = build(voice_settings: %i[stability similarity_boost], max_text_length: 10_000,
+               ssml_break: false, audio_tags: true, continuity: true)
+    V3_CONVERSATIONAL = build(voice_settings: %i[stability similarity_boost use_speaker_boost], max_text_length: 5_000,
+                              ssml_break: false, audio_tags: true, continuity: true)
+    V3 = build(voice_settings: %i[stability similarity_boost], max_text_length: 5_000,
+               ssml_break: false, audio_tags: true, continuity: true)
+    V2_5_FAST = build(voice_settings: ALL_VOICE_SETTINGS, max_text_length: 40_000,
+                      ssml_break: true, audio_tags: false, continuity: true)
+    V2_FAST = build(voice_settings: ALL_VOICE_SETTINGS, max_text_length: 30_000,
+                    ssml_break: true, audio_tags: false, continuity: true)
+    DEFAULT = build(voice_settings: ALL_VOICE_SETTINGS, max_text_length: 10_000,
+                    ssml_break: true, audio_tags: false, continuity: true)
+
+    # Ordered [matcher, capabilities] pairs; the first match wins.
+    FAMILIES = [
+      [/\Aeleven_v4/, V4],
+      [/\Aeleven_v3_conversational/, V3_CONVERSATIONAL],
+      [/\Aeleven_v3/, V3],
+      [/\Aeleven_(flash|turbo)_v2_5/, V2_5_FAST],
+      [/\Aeleven_(flash|turbo)_v2/, V2_FAST]
+    ].freeze
+
+    FEATURES = %i[audio_tags ssml_break continuity].freeze
+
+    module_function
+
+    # Capabilities for a model id (unknown ids get the permissive default)
+    #
+    # @param model_id [String, Symbol, nil]
+    # @return [Capabilities] frozen
+    def for(model_id)
+      id = model_id.to_s
+      FAMILIES.each { |matcher, caps| return caps if matcher.match?(id) }
+      DEFAULT
+    end
+
+    # Voice settings keys the model honours
+    #
+    # @param model_id [String]
+    # @return [Array<Symbol>]
+    def supported_voice_settings(model_id)
+      self.for(model_id).voice_settings
+    end
+
+    # Maximum characters per request for the model
+    #
+    # @param model_id [String]
+    # @return [Integer]
+    def max_text_length(model_id)
+      self.for(model_id).max_text_length
+    end
+
+    # Whether the model supports a feature
+    #
+    # @param model_id [String]
+    # @param feature [Symbol] :audio_tags, :ssml_break or :continuity
+    # @return [Boolean]
+    def supports?(model_id, feature)
+      feature = feature.to_sym
+      raise ArgumentError, "Unknown feature #{feature.inspect} (expected one of #{FEATURES.join(', ')})" unless FEATURES.include?(feature)
+
+      self.for(model_id).public_send(feature) ? true : false
+    end
+  end
+end

data/lib/eleven_rb/objects/audio.rb

@@ -6,7 +6,8 @@ module ElevenRb
   module Objects
     # Represents generated audio data
     class Audio
-      attr_reader :data, :format, :voice_id, :text, :model_id
+      attr_reader :data, :format, :voice_id, :text, :model_id,
+                  :request_id, :character_cost, :dropped_settings
 
       # Initialize audio object
       #
@@ -15,12 +16,20 @@ module ElevenRb
       # @param voice_id [String] the voice ID used
       # @param text [String] the text that was converted
       # @param model_id [String, nil] the model ID used
-      def initialize(data:, format:, voice_id:, text:, model_id: nil)
+      # @param request_id [String, nil] the API's `request-id` response header (usable as
+      #   previous_request_ids / next_request_ids on a later request)
+      # @param character_cost [Integer, nil] the API's `character-cost` response header
+      # @param dropped_settings [Array<Symbol>] voice settings the gem dropped because the model ignores them
+      def initialize(data:, format:, voice_id:, text:, model_id: nil, request_id: nil, character_cost: nil,
+                     dropped_settings: [])
         @data = data
         @format = format
         @voice_id = voice_id
         @text = text
         @model_id = model_id
+        @request_id = request_id
+        @character_cost = character_cost
+        @dropped_settings = Array(dropped_settings).dup.freeze
       end
 
       # Save audio to a file
@@ -62,7 +71,7 @@ module ElevenRb
           'audio/mpeg'
         when /pcm/
           'audio/pcm'
-        when /ogg/
+        when /ogg|opus/
           'audio/ogg'
         when /wav/
           'audio/wav'
@@ -82,7 +91,7 @@ module ElevenRb
           'mp3'
         when /pcm/
           'pcm'
-        when /ogg/
+        when /ogg|opus/
           'ogg'
         when /wav/
           'wav'

data/lib/eleven_rb/objects/cost_info.rb

@@ -13,6 +13,9 @@ module ElevenRb
         'eleven_multilingual_v1' => 0.30,
         'eleven_multilingual_v2' => 0.30,
         'eleven_v3' => 0.30,
+        'eleven_v3_conversational' => 0.15,
+        'eleven_v4' => 0.30,
+        'eleven_v4_turbo' => 0.15,
         'eleven_turbo_v2' => 0.18,
         'eleven_turbo_v2_5' => 0.18,
         'eleven_english_sts_v2' => 0.30,

data/lib/eleven_rb/objects/model.rb

@@ -18,6 +18,16 @@ module ElevenRb
       attribute :max_characters_request_free_user
       attribute :max_characters_request_subscribed_user
       attribute :concurrency_group
+      attribute :model_rates
+      attribute :maximum_text_length_per_request
+      attribute :requires_alpha_access, type: :boolean
+
+      # Voice settings keys this model honours (from ModelCapabilities)
+      #
+      # @return [Array<Symbol>]
+      def supported_voice_settings
+        ModelCapabilities.supported_voice_settings(model_id)
+      end
 
       # Check if this model supports a given language
       #

data/lib/eleven_rb/objects/voice_settings.rb

@@ -25,6 +25,39 @@ module ElevenRb
         from_response(DEFAULTS.merge(overrides))
       end
 
+      # Voice-setting keys the capability table knows about. Only these can be
+      # dropped for a model; any other key is passed through untouched so a
+      # future API field is never swallowed.
+      KNOWN_KEYS = ModelCapabilities::ALL_VOICE_SETTINGS
+
+      # Build the voice_settings hash a model actually honours
+      #
+      # Starts from DEFAULTS filtered to the model's supported keys and merges the
+      # overrides (keys symbolized). Known keys the model does not support are
+      # dropped; unknown keys pass through after the supported ones, in the
+      # caller's order; nil values are removed. Only non-nil override keys count
+      # as dropped: defaults the model does not take are filtered silently.
+      #
+      # @example
+      #   VoiceSettings.for_model('eleven_multilingual_v2')
+      #   # => [{ stability: 0.5, similarity_boost: 0.75, style: 0.0, use_speaker_boost: true }, []]
+      #   VoiceSettings.for_model('eleven_v4', speed: 1.1)
+      #   # => [{ stability: 0.5, similarity_boost: 0.75 }, [:speed]]
+      #
+      # @param model_id [String] the model ID
+      # @param overrides [Hash] caller settings (String or Symbol keys)
+      # @return [Array(Hash, Array<Symbol>)] the settings hash and the dropped override keys
+      def self.for_model(model_id, overrides = {})
+        supported = ModelCapabilities.supported_voice_settings(model_id)
+        requested = (overrides || {}).to_h.transform_keys(&:to_sym)
+
+        dropped = requested.compact.keys & (KNOWN_KEYS - supported)
+        unknown = requested.except(*KNOWN_KEYS)
+        settings = DEFAULTS.slice(*supported).merge(requested.slice(*supported)).merge(unknown).compact
+
+        [settings, dropped]
+      end
+
       # Convert to hash suitable for API request
       #
       # @return [Hash]

data/lib/eleven_rb/resources/base.rb

@@ -51,6 +51,24 @@ module ElevenRb
         http_client.post(path, body, response_type: :binary)
       end
 
+      # Make a JSON POST request and also return the response headers
+      #
+      # @param path [String]
+      # @param body [Hash]
+      # @return [Hash] `{ body: Hash, headers: Hash<String, String> }`
+      def post_with_meta(path, body = {})
+        http_client.post(path, body, response_type: :json, with_meta: true)
+      end
+
+      # Make a binary POST request and also return the response headers
+      #
+      # @param path [String]
+      # @param body [Hash]
+      # @return [Hash] `{ body: String, headers: Hash<String, String> }`
+      def post_binary_with_meta(path, body = {})
+        http_client.post(path, body, response_type: :binary, with_meta: true)
+      end
+
       # Make a streaming POST request
       #
       # @param path [String]

data/lib/eleven_rb/resources/models.rb

@@ -9,23 +9,36 @@ module ElevenRb
     #
     # @example Find multilingual models
     #   client.models.multilingual
+    #
+    # @example Find one model
+    #   client.models.find('eleven_v4')
     class Models < Base
       # List all available models
       #
       # @return [Array<Objects::Model>]
       def list
-        response = get('/models')
+        # Call the HTTP client directly: #get below is the model lookup (kept for
+        # compatibility) and shadows Base#get, which made this method recurse.
+        response = http_client.get('/models')
         response.map { |m| Objects::Model.from_response(m) }
       end
 
-      # Get a specific model by ID
+      # Find a specific model by ID
       #
       # @param model_id [String] the model ID
       # @return [Objects::Model, nil]
-      def get(model_id)
+      def find(model_id)
         list.find { |m| m.model_id == model_id }
       end
 
+      # Alias of {#find}, kept for backwards compatibility
+      #
+      # @param model_id [String] the model ID
+      # @return [Objects::Model, nil]
+      def get(model_id)
+        find(model_id)
+      end
+
       # Get all multilingual models
       #
       # @return [Array<Objects::Model>]
@@ -51,14 +64,20 @@ module ElevenRb
       #
       # @return [Objects::Model, nil]
       def default
-        get('eleven_multilingual_v2') || tts_capable.first
+        default_from(list)
       end
 
-      # Get the latest/most capable model
+      # Get the latest/most capable model available to the account:
+      # eleven_v4, else eleven_v3, else {#default} (one /models request)
       #
       # @return [Objects::Model, nil]
       def latest
-        get('eleven_v3') || default
+        models = list
+        %w[eleven_v4 eleven_v3].each do |model_id|
+          model = models.find { |m| m.model_id == model_id }
+          return model if model
+        end
+        default_from(models)
       end
 
       # Get model IDs as array
@@ -67,6 +86,13 @@ module ElevenRb
       def ids
         list.map(&:model_id)
       end
+
+      private
+
+      # eleven_multilingual_v2, else the first TTS-capable model, from an already-fetched list
+      def default_from(models)
+        models.find { |m| m.model_id == 'eleven_multilingual_v2' } || models.find(&:can_do_text_to_speech)
+      end
     end
   end
 end

data/lib/eleven_rb/resources/text_to_dialogue.rb

@@ -10,20 +10,51 @@ module ElevenRb
     #     { text: "[laughs] Thanks!", voice_id: "voice_xyz" }
     #   ])
     #   audio.save_to_file("dialogue.mp3")
+    #
+    # @example Dialogue with timestamps and per-speaker segments
+    #   result = client.dialogue.generate_with_timestamps(inputs, seed: 7)
+    #   result[:voice_segments] # => [{ "voice_id" => ..., "start_time_seconds" => ... }, ...]
     class TextToDialogue < Base
-      DEFAULT_MODEL = 'eleven_v3'
+      DEFAULT_MODEL = 'eleven_v4'
       MAX_VOICES_PER_REQUEST = 10
+
+      # Kept for compatibility. The hard cap now comes from
+      # ModelCapabilities.max_text_length(model_id) (5,000 for eleven_v3).
       MAX_TEXT_LENGTH = 5000
 
+      # Above this many characters the API recommends splitting the dialogue;
+      # the gem logs a warning but still sends the request.
+      RECOMMENDED_MAX_TEXT_LENGTH = 2_000
+
+      # Optional request-body keys, in the order they are written to the body.
+      # Each is omitted from the body when nil.
+      OPTIONAL_BODY_KEYS = %i[
+        language_code
+        settings
+        seed
+        use_pvc_as_ivc
+        previous_text
+        future_text
+        previous_request_ids
+        next_request_ids
+        pronunciation_dictionary_locators
+      ].freeze
+
       # Generate dialogue audio from multiple speaker inputs
       #
       # @param inputs [Array<Hash>] Array of { text:, voice_id: } hashes
-      # @param model_id [String] Model to use (only eleven_v3 supported)
+      # @param model_id [String] Model to use (default: eleven_v4)
       # @param language_code [String, nil] ISO 639-1 language code
-      # @param settings [Hash, nil] Generation settings (stability: 0.0-1.0)
+      # @param settings [Hash, nil] Generation settings, sent unchanged (e.g. stability, similarity)
       # @param seed [Integer, nil] Seed for reproducibility
       # @param output_format [String] Audio output format
       # @param apply_text_normalization [String] "auto", "on", or "off"
+      # @param use_pvc_as_ivc [Boolean, nil] use the IVC version of professional voices
+      # @param previous_text [String, nil] text that comes before this dialogue (continuity)
+      # @param future_text [String, nil] text that comes after this dialogue (continuity)
+      # @param previous_request_ids [Array<String>, nil] request IDs of preceding generations
+      # @param next_request_ids [Array<String>, nil] request IDs of following generations
+      # @param pronunciation_dictionary_locators [Array<Hash>, nil] pronunciation dictionaries to apply
       # @return [Objects::Audio]
       def generate(
         inputs,
@@ -32,45 +63,92 @@ module ElevenRb
         settings: nil,
         seed: nil,
         output_format: 'mp3_44100_128',
-        apply_text_normalization: 'auto'
+        apply_text_normalization: 'auto',
+        use_pvc_as_ivc: nil,
+        previous_text: nil,
+        future_text: nil,
+        previous_request_ids: nil,
+        next_request_ids: nil,
+        pronunciation_dictionary_locators: nil
       )
-        validate_inputs!(inputs)
+        validate_inputs!(inputs, model_id)
 
-        body = build_request_body(inputs, model_id, language_code, settings, seed,
-                                  apply_text_normalization)
+        body = build_request_body(inputs, model_id, apply_text_normalization, optional_values(binding))
+        response = post_binary_with_meta("/text-to-dialogue?output_format=#{output_format}", body)
 
-        response = post_binary(
-          "/text-to-dialogue?output_format=#{output_format}",
-          body
-        )
+        build_audio_response(response[:body], inputs, output_format, model_id,
+                             request_id: response[:headers]['request-id'])
+      end
 
-        build_audio_response(response, inputs, output_format, model_id)
+      # Generate dialogue audio with character timestamps and per-voice segments
+      #
+      # Takes the same keywords as {#generate}.
+      #
+      # @param inputs [Array<Hash>] Array of { text:, voice_id: } hashes
+      # @return [Hash] `{ audio:, alignment:, normalized_alignment:, voice_segments:, request_id: }`
+      def generate_with_timestamps(
+        inputs,
+        model_id: DEFAULT_MODEL,
+        language_code: nil,
+        settings: nil,
+        seed: nil,
+        output_format: 'mp3_44100_128',
+        apply_text_normalization: 'auto',
+        use_pvc_as_ivc: nil,
+        previous_text: nil,
+        future_text: nil,
+        previous_request_ids: nil,
+        next_request_ids: nil,
+        pronunciation_dictionary_locators: nil
+      )
+        validate_inputs!(inputs, model_id)
+
+        body = build_request_body(inputs, model_id, apply_text_normalization, optional_values(binding))
+        result = post_with_meta("/text-to-dialogue/with-timestamps?output_format=#{output_format}", body)
+        response = result[:body]
+        request_id = result[:headers]['request-id']
+
+        audio_data = Base64.decode64(response['audio_base64']) if response['audio_base64']
+        audio = (build_audio_response(audio_data, inputs, output_format, model_id, request_id: request_id) if audio_data)
+
+        {
+          audio: audio,
+          alignment: response['alignment'],
+          normalized_alignment: response['normalized_alignment'],
+          voice_segments: response['voice_segments'],
+          request_id: request_id
+        }
       end
 
       private
 
-      def build_request_body(inputs, model_id, language_code, settings, seed,
-                             apply_text_normalization)
+      # The optional keyword values of the calling method, keyed by OPTIONAL_BODY_KEYS
+      def optional_values(caller_binding)
+        OPTIONAL_BODY_KEYS.to_h { |key| [key, caller_binding.local_variable_get(key)] }
+      end
+
+      def build_request_body(inputs, model_id, apply_text_normalization, options)
         body = {
           inputs: inputs.map { |i| { text: i[:text], voice_id: i[:voice_id] } },
           model_id: model_id,
           apply_text_normalization: apply_text_normalization
         }
 
-        body[:language_code] = language_code if language_code
-        body[:settings] = settings if settings
-        body[:seed] = seed if seed
+        OPTIONAL_BODY_KEYS.each do |key|
+          body[key] = options[key] unless options[key].nil?
+        end
         body
       end
 
-      def build_audio_response(response, inputs, output_format, model_id)
+      def build_audio_response(data, inputs, output_format, model_id, request_id: nil)
         total_text = inputs.map { |i| i[:text] }.join("\n")
         total_chars = inputs.sum { |i| i[:text].length }
         primary_voice = inputs.first[:voice_id]
 
         audio = Objects::Audio.new(
-          data: response, format: output_format,
-          voice_id: primary_voice, text: total_text, model_id: model_id
+          data: data, format: output_format,
+          voice_id: primary_voice, text: total_text, model_id: model_id,
+          request_id: request_id
         )
 
         cost_info = Objects::CostInfo.new(
@@ -80,13 +158,14 @@ module ElevenRb
         http_client.config.trigger(
           :on_audio_generated,
           audio: audio, voice_id: primary_voice,
-          text: total_text, cost_info: cost_info.to_h
+          text: total_text, cost_info: cost_info.to_h,
+          request_id: request_id
         )
 
         audio
       end
 
-      def validate_inputs!(inputs)
+      def validate_inputs!(inputs, model_id = DEFAULT_MODEL)
         raise Errors::ValidationError, 'inputs must be a non-empty array' unless inputs.is_a?(Array) && !inputs.empty?
 
         inputs.each_with_index do |input, i|
@@ -101,12 +180,23 @@ module ElevenRb
                 "(got #{unique_voices.length})"
         end
 
-        total_chars = inputs.sum { |i| i[:text].length }
-        return unless total_chars > MAX_TEXT_LENGTH
+        validate_text_length!(inputs.sum { |i| i[:text].length }, model_id)
+      end
+
+      def validate_text_length!(total_chars, model_id)
+        max_length = ModelCapabilities.max_text_length(model_id)
+        if total_chars > max_length
+          raise Errors::ValidationError,
+                "Total text length #{total_chars} exceeds maximum " \
+                "#{max_length} characters for #{model_id}"
+        end
+
+        return unless total_chars > RECOMMENDED_MAX_TEXT_LENGTH
 
-        raise Errors::ValidationError,
-              "Total text length #{total_chars} exceeds maximum " \
-              "#{MAX_TEXT_LENGTH} characters"
+        http_client.config.logger&.warn(
+          "[ElevenRb] text-to-dialogue text is #{total_chars} characters; " \
+          "#{RECOMMENDED_MAX_TEXT_LENGTH} or fewer per request is recommended"
+        )
       end
     end
   end

data/lib/eleven_rb/resources/text_to_speech.rb

@@ -12,18 +12,67 @@ module ElevenRb
     #   client.tts.stream("Hello world", voice_id: "voice_id") do |chunk|
     #     io.write(chunk)
     #   end
+    #
+    # @example Eleven v4 with continuity and a fixed seed
+    #   audio = client.tts.generate(
+    #     "[sighs] Right. Let's try that again.",
+    #     voice_id: "voice_id",
+    #     model_id: "eleven_v4",
+    #     seed: 42,
+    #     previous_text: "That did not go to plan."
+    #   )
+    #   audio.request_id # => "abc123" (from the request-id response header)
     class TextToSpeech < Base
       DEFAULT_MODEL = 'eleven_multilingual_v2'
+
+      # Kept for compatibility. The per-request cap now comes from
+      # ModelCapabilities.max_text_length(model_id) (5,000 for eleven_v3).
       MAX_TEXT_LENGTH = 5000
 
+      # Output formats the API accepts (documentation only; not validated)
       OUTPUT_FORMATS = %w[
+        mp3_22050_32
+        mp3_24000_48
+        mp3_44100_32
+        mp3_44100_64
+        mp3_44100_96
         mp3_44100_128
         mp3_44100_192
+        opus_48000_32
+        opus_48000_64
+        opus_48000_96
+        opus_48000_128
+        opus_48000_192
+        pcm_8000
         pcm_16000
         pcm_22050
         pcm_24000
+        pcm_32000
         pcm_44100
+        pcm_48000
+        wav_8000
+        wav_16000
+        wav_22050
+        wav_24000
+        wav_32000
+        wav_44100
+        wav_48000
         ulaw_8000
+        alaw_8000
+      ].freeze
+
+      # Optional request-body keys, in the order they are written to the body.
+      # Each is omitted from the body when nil.
+      OPTIONAL_BODY_KEYS = %i[
+        language_code
+        apply_text_normalization
+        seed
+        previous_text
+        next_text
+        previous_request_ids
+        next_request_ids
+        pronunciation_dictionary_locators
+        use_pvc_as_ivc
       ].freeze
 
       # Generate audio from text
@@ -31,30 +80,39 @@ module ElevenRb
       # @param text [String] the text to convert
       # @param voice_id [String] the voice ID to use
       # @param model_id [String] the model to use (default: eleven_multilingual_v2)
-      # @param voice_settings [Hash] voice settings overrides
+      # @param voice_settings [Hash] voice settings overrides (keys the model ignores are dropped)
       # @param output_format [String] audio output format
-      # @return [Objects::Audio]
-      def generate(text, voice_id:, model_id: DEFAULT_MODEL, voice_settings: {}, output_format: 'mp3_44100_128')
-        validate_text!(text)
+      # @param language_code [String, nil] ISO 639-1 language code to enforce
+      # @param apply_text_normalization [String, nil] "auto", "on" or "off"
+      # @param seed [Integer, nil] seed for reproducible generation
+      # @param previous_text [String, nil] text that comes before this request (continuity)
+      # @param next_text [String, nil] text that comes after this request (continuity)
+      # @param previous_request_ids [Array<String>, nil] request IDs of preceding generations
+      # @param next_request_ids [Array<String>, nil] request IDs of following generations
+      # @param pronunciation_dictionary_locators [Array<Hash>, nil] `{ pronunciation_dictionary_id:, version_id: }`
+      # @param use_pvc_as_ivc [Boolean, nil] use the IVC version of a professional voice
+      # @return [Objects::Audio] with request_id, character_cost and dropped_settings
+      def generate(text, voice_id:, model_id: DEFAULT_MODEL, voice_settings: {}, output_format: 'mp3_44100_128',
+                   language_code: nil, apply_text_normalization: nil, seed: nil, previous_text: nil,
+                   next_text: nil, previous_request_ids: nil, next_request_ids: nil,
+                   pronunciation_dictionary_locators: nil, use_pvc_as_ivc: nil)
+        validate_text!(text, model_id)
         validate_presence!(voice_id, 'voice_id')
-
-        settings = Objects::VoiceSettings::DEFAULTS.merge(voice_settings)
-
-        body = {
-          text: text,
-          model_id: model_id,
-          voice_settings: settings
-        }
+        body, dropped = build_body(text, model_id, voice_settings, optional_values(binding))
 
         path = "/text-to-speech/#{voice_id}?output_format=#{output_format}"
-        response = post_binary(path, body)
+        response = post_binary_with_meta(path, body)
+        headers = response[:headers]
 
         audio = Objects::Audio.new(
-          data: response,
+          data: response[:body],
           format: output_format,
           voice_id: voice_id,
           text: text,
-          model_id: model_id
+          model_id: model_id,
+          request_id: headers['request-id'],
+          character_cost: integer_header(headers, 'character-cost'),
+          dropped_settings: dropped
         )
 
         # Trigger cost tracking callback
@@ -64,7 +122,8 @@ module ElevenRb
           audio: audio,
           voice_id: voice_id,
           text: text,
-          cost_info: cost_info.to_h
+          cost_info: cost_info.to_h,
+          request_id: audio.request_id
         )
 
         audio
@@ -72,6 +131,8 @@ module ElevenRb
 
       # Stream audio from text
       #
+      # Takes the same optional keywords as {#generate}.
+      #
       # @param text [String] the text to convert
       # @param voice_id [String] the voice ID to use
       # @param model_id [String] the model to use
@@ -79,18 +140,15 @@ module ElevenRb
       # @param output_format [String] audio output format
       # @yield [String] each chunk of audio data
       # @return [void]
-      def stream(text, voice_id:, model_id: DEFAULT_MODEL, voice_settings: {}, output_format: 'mp3_44100_128', &block)
-        validate_text!(text)
+      def stream(text, voice_id:, model_id: DEFAULT_MODEL, voice_settings: {}, output_format: 'mp3_44100_128',
+                 language_code: nil, apply_text_normalization: nil, seed: nil, previous_text: nil,
+                 next_text: nil, previous_request_ids: nil, next_request_ids: nil,
+                 pronunciation_dictionary_locators: nil, use_pvc_as_ivc: nil, &block)
+        validate_text!(text, model_id)
         validate_presence!(voice_id, 'voice_id')
         raise ArgumentError, 'Block required for streaming' unless block_given?
 
-        settings = Objects::VoiceSettings::DEFAULTS.merge(voice_settings)
-
-        body = {
-          text: text,
-          model_id: model_id,
-          voice_settings: settings
-        }
+        body, = build_body(text, model_id, voice_settings, optional_values(binding))
 
         path = "/text-to-speech/#{voice_id}/stream?output_format=#{output_format}"
         post_stream(path, body, &block)
@@ -102,33 +160,35 @@ module ElevenRb
           audio: nil, # No audio object for streaming
           voice_id: voice_id,
           text: text,
-          cost_info: cost_info.to_h
+          cost_info: cost_info.to_h,
+          request_id: nil
         )
       end
 
       # Generate audio with timestamps
       #
+      # Takes the same optional keywords as {#generate}.
+      #
       # @param text [String] the text to convert
       # @param voice_id [String] the voice ID to use
       # @param model_id [String] the model to use
       # @param voice_settings [Hash] voice settings overrides
       # @param output_format [String] audio output format
-      # @return [Hash] contains :audio and :alignment data
+      # @return [Hash] `{ audio:, alignment:, normalized_alignment:, request_id:, character_cost: }`
       def generate_with_timestamps(text, voice_id:, model_id: DEFAULT_MODEL, voice_settings: {},
-                                   output_format: 'mp3_44100_128')
-        validate_text!(text)
+                                   output_format: 'mp3_44100_128', language_code: nil,
+                                   apply_text_normalization: nil, seed: nil, previous_text: nil,
+                                   next_text: nil, previous_request_ids: nil, next_request_ids: nil,
+                                   pronunciation_dictionary_locators: nil, use_pvc_as_ivc: nil)
+        validate_text!(text, model_id)
         validate_presence!(voice_id, 'voice_id')
-
-        settings = Objects::VoiceSettings::DEFAULTS.merge(voice_settings)
-
-        body = {
-          text: text,
-          model_id: model_id,
-          voice_settings: settings
-        }
+        body, dropped = build_body(text, model_id, voice_settings, optional_values(binding))
 
         path = "/text-to-speech/#{voice_id}/with-timestamps?output_format=#{output_format}"
-        response = post(path, body)
+        result = post_with_meta(path, body)
+        response = result[:body]
+        request_id = result[:headers]['request-id']
+        character_cost = integer_header(result[:headers], 'character-cost')
 
         # Decode base64 audio
         audio_data = Base64.decode64(response['audio_base64']) if response['audio_base64']
@@ -139,25 +199,72 @@ module ElevenRb
                     format: output_format,
                     voice_id: voice_id,
                     text: text,
-                    model_id: model_id
+                    model_id: model_id,
+                    request_id: request_id,
+                    character_cost: character_cost,
+                    dropped_settings: dropped
                   )
                 end
 
         {
           audio: audio,
-          alignment: response['alignment']
+          alignment: response['alignment'],
+          normalized_alignment: response['normalized_alignment'],
+          request_id: request_id,
+          character_cost: character_cost
         }
       end
 
       private
 
-      def validate_text!(text)
+      # Shared request body for generate / stream / generate_with_timestamps
+      #
+      # @return [Array(Hash, Array<Symbol>)] the body and the dropped voice-setting keys
+      def build_body(text, model_id, voice_settings, options)
+        settings, dropped = resolve_voice_settings(model_id, voice_settings)
+
+        body = { text: text, model_id: model_id, voice_settings: settings }
+        OPTIONAL_BODY_KEYS.each do |key|
+          body[key] = options[key] unless options[key].nil?
+        end
+
+        [body, dropped]
+      end
+
+      # The optional keyword values of the calling method, keyed by OPTIONAL_BODY_KEYS
+      def optional_values(caller_binding)
+        OPTIONAL_BODY_KEYS.to_h { |key| [key, caller_binding.local_variable_get(key)] }
+      end
+
+      def resolve_voice_settings(model_id, voice_settings)
+        settings, dropped = Objects::VoiceSettings.for_model(model_id, voice_settings)
+        return [settings, dropped] if dropped.empty?
+
+        message = "voice settings #{dropped.join(', ')} are not supported by #{model_id} " \
+                  "(supported: #{ModelCapabilities.supported_voice_settings(model_id).join(', ')})"
+        raise Errors::ValidationError, message if http_client.config.strict_voice_settings
+
+        http_client.config.logger&.warn("[ElevenRb] #{message}; dropped from the request")
+        [settings, dropped]
+      end
+
+      def integer_header(headers, name)
+        value = headers[name]
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        Integer(value.to_s.strip, 10)
+      rescue ArgumentError
+        nil
+      end
+
+      def validate_text!(text, model_id = DEFAULT_MODEL)
         validate_presence!(text, 'text')
 
-        return unless text.length > MAX_TEXT_LENGTH
+        max_length = ModelCapabilities.max_text_length(model_id)
+        return unless text.length > max_length
 
         raise Errors::ValidationError,
-              "text exceeds maximum length of #{MAX_TEXT_LENGTH} characters (got #{text.length})"
+              "text exceeds maximum length of #{max_length} characters for #{model_id} (got #{text.length})"
       end
     end
   end

data/lib/eleven_rb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ElevenRb
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/lib/eleven_rb.rb

@@ -60,6 +60,7 @@ module ElevenRb
         retry_delay: config.retry_delay,
         retry_statuses: config.retry_statuses,
         logger: config.logger,
+        strict_voice_settings: config.strict_voice_settings,
         on_request: config.on_request,
         on_response: config.on_response,
         on_error: config.on_error,
@@ -79,6 +80,7 @@ require_relative 'eleven_rb/errors'
 require_relative 'eleven_rb/callbacks'
 require_relative 'eleven_rb/instrumentation'
 require_relative 'eleven_rb/configuration'
+require_relative 'eleven_rb/model_capabilities'
 
 # HTTP layer
 require_relative 'eleven_rb/http/client'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eleven_rb
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Web Ventures Ltd
@@ -144,6 +144,7 @@ files:
 - lib/eleven_rb/errors.rb
 - lib/eleven_rb/http/client.rb
 - lib/eleven_rb/instrumentation.rb
+- lib/eleven_rb/model_capabilities.rb
 - lib/eleven_rb/objects/audio.rb
 - lib/eleven_rb/objects/base.rb
 - lib/eleven_rb/objects/cost_info.rb