eleven_rb 0.4.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa71eff851a0c6b80f139e801962bceaf1bb371f6e9a0cd325c47b2ee6f4994c
-  data.tar.gz: aa640970faba75afe3cbacdc16958ee63c1f2ecfb009512cd9e8182117e16d29
+  metadata.gz: 18424bceaba545d05f991cb1ae674fdc36572a7a9573ef769701deb35537b393
+  data.tar.gz: a5c2a3814295f5d19945b1731b639fe21ae0f0111ef51741fdb99bae5a978cf7
 SHA512:
-  metadata.gz: a537ba9de014afc366c348a71613f257b6380ae784979fb42cd55522610c85661e0e34907c770642fa268051cbb91b24110e00d5e8b7305d5c913a81e04705a6
-  data.tar.gz: c1f4e236fb327b737b4e6346bf3a71bfec357d4f7f09a0e1eaf9c8889ef2251ff40b8eeb3be959e98b58e2a76ff6305e7391d64f0c33a9ce1fb38897b958f1fa
+  metadata.gz: af3da66572e56a9173b5f427a3fa30212ebd686a5820b060ab5c81e5e41d60ae64a74e7956e0ddad4365d0f8e68ceefaa5572d97f485a0e424609c195f34be31
+  data.tar.gz: 3af1d07b75e5405724c50e87d3b89f88061d3540043716b38242acce0941f5152294148cd1d9109c20f05bbd05f5131e6b1225260bd373371b45061ad4bbca26

data/CHANGELOG.md

@@ -7,6 +7,56 @@ 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
+
+- Text-to-Dialogue multi-speaker audio generation via `client.text_to_dialogue.generate` (`POST /v1/text-to-dialogue`)
+- `Client#text_to_dialogue` resource with `dialogue` alias
+- Multi-speaker input validation (max 10 unique voices, 5000 character limit)
+- `eleven_v3` model added to `CostInfo::COST_PER_1K_CHARS` ($0.30/1K chars)
+- `Models#latest` method returning the most capable model (`eleven_v3`)
+- Audio tags support via v3 model (`[laughs]`, `[whispers]`, `[excited]`, etc.)
+- `CostInfo` now accepts `character_count:` keyword as alternative to `text:`
+- TTS generation with word-level timestamps via `client.tts.generate_with_timestamps`
+
+### Changed
+
+- `CostInfo#initialize` signature: `text:` is now optional when `character_count:` is provided (backwards-compatible)
+
 ## [0.4.0] - 2026-03-10
 
 ### Added

data/README.md

@@ -4,12 +4,14 @@
 [![CI](https://github.com/webventures/eleven_rb/actions/workflows/ci.yml/badge.svg)](https://github.com/webventures/eleven_rb/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Ruby client for the [ElevenLabs](https://try.elevenlabs.io/qyk2j8gumrjz) Text-to-Speech, Speech-to-Speech, Sound Effects, and Music API.
+A Ruby client for the [ElevenLabs](https://try.elevenlabs.io/qyk2j8gumrjz) Text-to-Speech, Speech-to-Speech, Text-to-Dialogue, Sound Effects, and Music API.
 
 ## Features
 
 - 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)
@@ -73,7 +75,7 @@ audio.save_to_file("output.mp3")
 audio = client.tts.generate(
   "Hello world",
   voice_id: "voice_id",
-  model_id: "eleven_multilingual_v2",
+  model_id: "eleven_v4",             # Most expressive; audio tags; see "Eleven v4" below
   voice_settings: {
     stability: 0.5,
     similarity_boost: 0.75
@@ -87,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
@@ -111,6 +177,54 @@ io = File.open("input.mp3", "rb")
 audio = client.sts.convert(io, voice_id: "voice_id")
 ```
 
+### Text-to-Dialogue
+
+```ruby
+# Generate multi-speaker dialogue
+audio = client.text_to_dialogue.generate([
+  { text: "[excited] Welcome to the show!", voice_id: "voice_abc" },
+  { text: "[laughs] Thanks for having me.", voice_id: "voice_xyz" },
+  { text: "So tell us about your project...", voice_id: "voice_abc" }
+])
+audio.save_to_file("dialogue.mp3")
+
+# With options (the default model is eleven_v4)
+audio = client.dialogue.generate(
+  inputs,
+  model_id: "eleven_v4",
+  language_code: "en",
+  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_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_v4"
+)
+```
+
+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
 
 ```ruby
@@ -252,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],
@@ -274,6 +388,12 @@ client = ElevenRb::Client.new(
 models = client.models.list
 models.each { |m| puts "#{m.name} (#{m.model_id})" }
 
+# 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
 
@@ -303,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/client.rb

@@ -101,6 +101,14 @@ module ElevenRb
       @music ||= Resources::Music.new(http_client)
     end
 
+    # Text-to-dialogue resource
+    #
+    # @return [Resources::TextToDialogue]
+    def text_to_dialogue
+      @text_to_dialogue ||= Resources::TextToDialogue.new(http_client)
+    end
+    alias dialogue text_to_dialogue
+
     # Voice slot manager
     #
     # @return [VoiceSlotManager]

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

@@ -12,6 +12,10 @@ module ElevenRb
         'eleven_monolingual_v1' => 0.30,
         '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,
@@ -23,11 +27,12 @@ module ElevenRb
 
       # Initialize cost info
       #
-      # @param text [String] the text being converted
+      # @param text [String, nil] the text being converted
+      # @param character_count [Integer, nil] direct character count (alternative to text)
       # @param voice_id [String] the voice ID
       # @param model_id [String] the model ID
-      def initialize(text:, voice_id:, model_id:)
-        @character_count = text.length
+      def initialize(voice_id:, model_id:, text: nil, character_count: nil)
+        @character_count = character_count || text&.length || 0
         @voice_id = voice_id
         @model_id = model_id
       end

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
       #