elevenlabs_client 0.1.0 → 0.3.0

data/lib/elevenlabs_client/client.rb

@@ -7,13 +7,21 @@ module ElevenlabsClient
   class Client
     DEFAULT_BASE_URL = "https://api.elevenlabs.io"
 
-    attr_reader :base_url, :api_key, :dubs
+    attr_reader :base_url, :api_key, :dubs, :text_to_speech, :text_to_speech_stream, :text_to_dialogue, :sound_generation, :text_to_voice, :models, :voices, :music
 
     def initialize(api_key: nil, base_url: nil, api_key_env: "ELEVENLABS_API_KEY", base_url_env: "ELEVENLABS_BASE_URL")
       @api_key = api_key || fetch_api_key(api_key_env)
       @base_url = base_url || fetch_base_url(base_url_env)
       @conn = build_connection
       @dubs = Dubs.new(self)
+      @text_to_speech = TextToSpeech.new(self)
+      @text_to_speech_stream = TextToSpeechStream.new(self)
+      @text_to_dialogue = TextToDialogue.new(self)
+      @sound_generation = SoundGeneration.new(self)
+      @text_to_voice = TextToVoice.new(self)
+      @models = Models.new(self)
+      @voices = Voices.new(self)
+      @music = Endpoints::Music.new(self)
     end
 
     # Makes an authenticated GET request
@@ -35,7 +43,19 @@ module ElevenlabsClient
     def post(path, body = nil)
       response = @conn.post(path) do |req|
         req.headers["xi-api-key"] = api_key
-        req.body = body if body
+        req.headers["Content-Type"] = "application/json"
+        req.body = body.to_json if body
+      end
+
+      handle_response(response)
+    end
+
+    # Makes an authenticated DELETE request
+    # @param path [String] API endpoint path
+    # @return [Hash] Response body
+    def delete(path)
+      response = @conn.delete(path) do |req|
+        req.headers["xi-api-key"] = api_key
       end
 
       handle_response(response)
@@ -54,6 +74,62 @@ module ElevenlabsClient
       handle_response(response)
     end
 
+    # Makes an authenticated POST request expecting binary response
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] Request body
+    # @return [String] Binary response body
+    def post_binary(path, body = nil)
+      response = @conn.post(path) do |req|
+        req.headers["xi-api-key"] = api_key
+        req.headers["Content-Type"] = "application/json"
+        req.body = body.to_json if body
+      end
+
+      handle_response(response)
+    end
+
+    # Makes an authenticated POST request with custom headers
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] Request body
+    # @param custom_headers [Hash] Additional headers
+    # @return [String] Response body (binary or text)
+    def post_with_custom_headers(path, body = nil, custom_headers = {})
+      response = @conn.post(path) do |req|
+        req.headers["xi-api-key"] = api_key
+        req.headers["Content-Type"] = "application/json"
+        custom_headers.each { |key, value| req.headers[key] = value }
+        req.body = body.to_json if body
+      end
+
+      # For streaming/binary responses, return raw body
+      if custom_headers["Accept"]&.include?("audio") || custom_headers["Transfer-Encoding"] == "chunked"
+        handle_response(response)
+      else
+        handle_response(response)
+      end
+    end
+
+    # Makes an authenticated POST request with streaming response
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] Request body
+    # @param block [Proc] Block to handle each chunk
+    # @return [Faraday::Response] Response object
+    def post_streaming(path, body = nil, &block)
+      response = @conn.post(path) do |req|
+        req.headers["xi-api-key"] = api_key
+        req.headers["Content-Type"] = "application/json"
+        req.headers["Accept"] = "audio/mpeg"
+        req.body = body.to_json if body
+        
+        # Set up streaming callback
+        req.options.on_data = proc do |chunk, _|
+          block.call(chunk) if block_given?
+        end
+      end
+
+      handle_response(response)
+    end
+
     # Helper method to create Faraday::Multipart::FilePart
     # @param file_io [IO] File IO object
     # @param filename [String] Original filename
@@ -97,14 +173,58 @@ module ElevenlabsClient
       case response.status
       when 200..299
         response.body
+      when 400
+        error_message = extract_error_message(response.body)
+        raise BadRequestError, error_message.empty? ? "Bad request - invalid parameters" : error_message
       when 401
-        raise AuthenticationError, "Invalid API key or authentication failed"
+        error_message = extract_error_message(response.body)
+        raise AuthenticationError, error_message.empty? ? "Invalid API key or authentication failed" : error_message
+      when 404
+        error_message = extract_error_message(response.body)
+        raise NotFoundError, error_message.empty? ? "Resource not found" : error_message
+      when 422
+        error_message = extract_error_message(response.body)
+        raise UnprocessableEntityError, error_message.empty? ? "Unprocessable entity - invalid data" : error_message
       when 429
-        raise RateLimitError, "Rate limit exceeded"
+        error_message = extract_error_message(response.body)
+        raise RateLimitError, error_message.empty? ? "Rate limit exceeded" : error_message
       when 400..499
-        raise ValidationError, response.body.inspect
+        error_message = extract_error_message(response.body)
+        raise ValidationError, error_message.empty? ? "Client error occurred with status #{response.status}" : error_message
       else
-        raise APIError, "API request failed with status #{response.status}: #{response.body.inspect}"
+        error_message = extract_error_message(response.body)
+        raise APIError, error_message.empty? ? "API request failed with status #{response.status}" : error_message
+      end
+    end
+
+    private
+
+    def extract_error_message(response_body)
+      return "" if response_body.nil? || response_body.empty?
+      
+      # Handle non-string response bodies
+      body_str = response_body.is_a?(String) ? response_body : response_body.to_s
+      
+      begin
+        error_info = JSON.parse(body_str)
+        
+        # Try different common error message fields
+        message = error_info["detail"] || 
+                 error_info["message"] || 
+                 error_info["error"] ||
+                 error_info["errors"]
+        
+        # Handle nested detail objects
+        if message.is_a?(Hash)
+          message = message["message"] || message.to_s
+        elsif message.is_a?(Array)
+          message = message.first.to_s
+        end
+        
+        message.to_s
+      rescue JSON::ParserError, TypeError
+        # If not JSON or can't be parsed, return the raw body (truncated if too long)
+        body_str.length > 200 ? "#{body_str[0..200]}..." : body_str
       end
     end
 

data/lib/elevenlabs_client/endpoints/models.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class Models
+    def initialize(client)
+      @client = client
+    end
+
+    # GET /v1/models
+    # Gets a list of available models
+    # Documentation: https://elevenlabs.io/docs/api-reference/models/list
+    #
+    # @return [Hash] The JSON response containing an array of models
+    def list
+      endpoint = "/v1/models"
+      @client.get(endpoint)
+    end
+
+    # Alias for backward compatibility and convenience
+    alias_method :list_models, :list
+
+    private
+
+    attr_reader :client
+  end
+end

data/lib/elevenlabs_client/endpoints/music.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  module Endpoints
+    class Music
+      def initialize(client)
+        @client = client
+      end
+
+      # POST /v1/music
+      # Compose music and return binary audio data
+      # Documentation: https://elevenlabs.io/docs/api-reference/music/compose
+      #
+      # @param options [Hash] Music composition parameters
+      # @option options [String] :prompt Text description of the music to generate
+      # @option options [Hash] :composition_plan Detailed composition structure (optional)
+      # @option options [Integer] :music_length_ms Length of music in milliseconds (optional)
+      # @option options [String] :model_id Model to use for generation (default: "music_v1")
+      # @option options [String] :output_format Audio format (e.g., "mp3_44100_128")
+      # @return [String] Binary audio data
+      def compose(options = {})
+        endpoint = "/v1/music"
+        request_body = build_music_request_body(options)
+        
+        query_params = {}
+        query_params[:output_format] = options[:output_format] if options[:output_format]
+        
+        endpoint_with_query = query_params.empty? ? endpoint : "#{endpoint}?#{URI.encode_www_form(query_params)}"
+        
+        @client.post_binary(endpoint_with_query, request_body)
+      end
+
+      # POST /v1/music/stream
+      # Compose music with streaming audio response
+      # Documentation: https://elevenlabs.io/docs/api-reference/music/compose-stream
+      #
+      # @param options [Hash] Music composition parameters
+      # @option options [String] :prompt Text description of the music to generate
+      # @option options [Hash] :composition_plan Detailed composition structure (optional)
+      # @option options [Integer] :music_length_ms Length of music in milliseconds (optional)
+      # @option options [String] :model_id Model to use for generation (default: "music_v1")
+      # @option options [String] :output_format Audio format (e.g., "mp3_44100_128")
+      # @param block [Proc] Block to handle streaming audio chunks
+      # @return [nil] Audio is streamed via the block
+      def compose_stream(options = {}, &block)
+        endpoint = "/v1/music/stream"
+        request_body = build_music_request_body(options)
+        
+        query_params = {}
+        query_params[:output_format] = options[:output_format] if options[:output_format]
+        
+        endpoint_with_query = query_params.empty? ? endpoint : "#{endpoint}?#{URI.encode_www_form(query_params)}"
+        
+        @client.post_streaming(endpoint_with_query, request_body, &block)
+      end
+
+      # POST /v1/music/detailed
+      # Compose music and return detailed response with metadata and audio
+      # Documentation: https://elevenlabs.io/docs/api-reference/music/compose-detailed
+      #
+      # @param options [Hash] Music composition parameters
+      # @option options [String] :prompt Text description of the music to generate
+      # @option options [Hash] :composition_plan Detailed composition structure (optional)
+      # @option options [Integer] :music_length_ms Length of music in milliseconds (optional)
+      # @option options [String] :model_id Model to use for generation (default: "music_v1")
+      # @option options [String] :output_format Audio format (e.g., "mp3_44100_128")
+      # @return [String] Multipart response with JSON metadata and binary audio
+      def compose_detailed(options = {})
+        endpoint = "/v1/music/detailed"
+        request_body = build_music_request_body(options)
+        
+        query_params = {}
+        query_params[:output_format] = options[:output_format] if options[:output_format]
+        
+        endpoint_with_query = query_params.empty? ? endpoint : "#{endpoint}?#{URI.encode_www_form(query_params)}"
+        
+        # Use post_with_custom_headers to handle multipart response
+        @client.post_with_custom_headers(
+          endpoint_with_query,
+          request_body,
+          { "Accept" => "multipart/mixed" }
+        )
+      end
+
+      # POST /v1/music/plan
+      # Create a composition plan for music generation
+      # Documentation: https://elevenlabs.io/docs/api-reference/music/create-plan
+      #
+      # @param options [Hash] Plan creation parameters
+      # @option options [String] :prompt Text description of the music style/structure
+      # @option options [Integer] :music_length_ms Desired length of music in milliseconds
+      # @option options [Hash] :source_composition_plan Base plan to modify (optional)
+      # @option options [String] :model_id Model to use for plan generation (default: "music_v1")
+      # @return [Hash] JSON response containing the composition plan
+      def create_plan(options = {})
+        endpoint = "/v1/music/plan"
+        request_body = {
+          prompt: options[:prompt],
+          music_length_ms: options[:music_length_ms],
+          source_composition_plan: options[:source_composition_plan],
+          model_id: options[:model_id] || "music_v1"
+        }.compact
+        
+        @client.post(endpoint, request_body)
+      end
+
+      # Alias methods for convenience
+      alias_method :compose_music, :compose
+      alias_method :compose_music_stream, :compose_stream
+      alias_method :compose_music_detailed, :compose_detailed
+      alias_method :create_music_plan, :create_plan
+
+      private
+
+      attr_reader :client
+
+      def build_music_request_body(options)
+        {
+          prompt: options[:prompt],
+          composition_plan: options[:composition_plan],
+          music_length_ms: options[:music_length_ms],
+          model_id: options[:model_id] || "music_v1"
+        }.compact
+      end
+    end
+  end
+end

data/lib/elevenlabs_client/endpoints/sound_generation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class SoundGeneration
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/sound-generation
+    # Convert text to sound effects and retrieve audio (binary data)
+    # Documentation: https://elevenlabs.io/docs/api-reference/sound-generation
+    #
+    # @param text [String] Text prompt describing the sound effect
+    # @param options [Hash] Optional parameters
+    # @option options [Boolean] :loop Whether to create a looping sound effect (default: false)
+    # @option options [Float] :duration_seconds Duration in seconds (0.5 to 30, default: nil for auto-detection)
+    # @option options [Float] :prompt_influence Prompt influence (0.0 to 1.0, default: 0.3)
+    # @option options [String] :output_format Output format (e.g., "mp3_22050_32", default: "mp3_44100_128")
+    # @return [String] The binary audio data (usually an MP3)
+    def generate(text, **options)
+      endpoint = "/v1/sound-generation"
+      request_body = { text: text }
+
+      # Add optional parameters if provided
+      request_body[:loop] = options[:loop] unless options[:loop].nil?
+      request_body[:duration_seconds] = options[:duration_seconds] if options[:duration_seconds]
+      request_body[:prompt_influence] = options[:prompt_influence] if options[:prompt_influence]
+
+      # Handle output_format as query parameter
+      query_params = {}
+      query_params[:output_format] = options[:output_format] if options[:output_format]
+
+      # Build endpoint with query parameters if any
+      full_endpoint = query_params.any? ? "#{endpoint}?#{URI.encode_www_form(query_params)}" : endpoint
+
+      @client.post_binary(full_endpoint, request_body)
+    end
+
+    # Alias for backward compatibility and convenience
+    alias_method :sound_generation, :generate
+
+    private
+
+    attr_reader :client
+  end
+end

data/lib/elevenlabs_client/endpoints/text_to_dialogue.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class TextToDialogue
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/text-to-dialogue
+    # Converts a list of text and voice ID pairs into speech (dialogue) and returns audio.
+    # Documentation: https://elevenlabs.io/docs/api-reference/text-to-dialogue/convert
+    #
+    # @param inputs [Array<Hash>] A list of dialogue inputs, each containing text and a voice ID
+    # @option inputs [String] :text The text to be converted to speech
+    # @option inputs [String] :voice_id The voice ID to use for this text
+    # @param options [Hash] Optional parameters
+    # @option options [String] :model_id Identifier of the model to be used
+    # @option options [Hash] :settings Settings controlling the dialogue generation
+    # @option options [Integer] :seed Best effort to sample deterministically
+    # @return [String] The binary audio data (usually an MP3)
+    def convert(inputs, **options)
+      endpoint = "/v1/text-to-dialogue"
+      request_body = { inputs: inputs }
+
+      # Add optional parameters
+      request_body[:model_id] = options[:model_id] if options[:model_id]
+      request_body[:settings] = options[:settings] if options[:settings] && !options[:settings].empty?
+      request_body[:seed] = options[:seed] if options[:seed]
+
+      @client.post_binary(endpoint, request_body)
+    end
+
+    # Alias for backward compatibility and convenience
+    alias_method :text_to_dialogue, :convert
+
+    private
+
+    attr_reader :client
+  end
+end

data/lib/elevenlabs_client/endpoints/text_to_speech.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class TextToSpeech
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/text-to-speech/{voice_id}
+    # Convert text to speech and retrieve audio (binary data)
+    # Documentation: https://elevenlabs.io/docs/api-reference/text-to-speech/convert
+    #
+    # @param voice_id [String] The ID of the voice to use
+    # @param text [String] Text to synthesize
+    # @param options [Hash] Optional TTS parameters
+    # @option options [String] :model_id Model to use (e.g. "eleven_monolingual_v1" or "eleven_multilingual_v1")
+    # @option options [Hash] :voice_settings Voice configuration (stability, similarity_boost, style, use_speaker_boost, etc.)
+    # @option options [Boolean] :optimize_streaming Whether to receive chunked streaming audio
+    # @return [String] The binary audio data (usually an MP3)
+    def convert(voice_id, text, **options)
+      endpoint = "/v1/text-to-speech/#{voice_id}"
+      request_body = { text: text }
+
+      # Add optional parameters
+      request_body[:model_id] = options[:model_id] if options[:model_id]
+      request_body[:voice_settings] = options[:voice_settings] if options[:voice_settings]
+
+      # Handle streaming optimization
+      if options[:optimize_streaming]
+        @client.post_with_custom_headers(endpoint, request_body, streaming_headers)
+      else
+        @client.post_binary(endpoint, request_body)
+      end
+    end
+
+    # Alias for backward compatibility and convenience
+    alias_method :text_to_speech, :convert
+
+    private
+
+    attr_reader :client
+
+    def streaming_headers
+      {
+        "Accept" => "audio/mpeg",
+        "Transfer-Encoding" => "chunked"
+      }
+    end
+  end
+end

data/lib/elevenlabs_client/endpoints/text_to_speech_stream.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class TextToSpeechStream
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/text-to-speech/{voice_id}/stream
+    # Stream text-to-speech audio in real-time chunks
+    #
+    # @param voice_id [String] The ID of the voice to use
+    # @param text [String] Text to synthesize
+    # @param options [Hash] Optional TTS parameters
+    # @option options [String] :model_id Model to use (defaults to "eleven_multilingual_v2")
+    # @option options [String] :output_format Output format (defaults to "mp3_44100_128")
+    # @option options [Hash] :voice_settings Voice configuration
+    # @param block [Proc] Block to handle each audio chunk
+    # @return [Faraday::Response] The response object
+    def stream(voice_id, text, **options, &block)
+      output_format = options[:output_format] || "mp3_44100_128"
+      endpoint = "/v1/text-to-speech/#{voice_id}/stream?output_format=#{output_format}"
+      
+      request_body = {
+        text: text,
+        model_id: options[:model_id] || "eleven_multilingual_v2"
+      }
+      
+      # Add voice_settings if provided
+      request_body[:voice_settings] = options[:voice_settings] if options[:voice_settings]
+
+      @client.post_streaming(endpoint, request_body, &block)
+    end
+
+    # Alias for backward compatibility
+    alias_method :text_to_speech_stream, :stream
+
+    private
+
+    attr_reader :client
+  end
+end

data/lib/elevenlabs_client/endpoints/text_to_voice.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class TextToVoice
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/text-to-voice/design
+    # Designs a voice based on a description
+    # Documentation: https://elevenlabs.io/docs/api-reference/text-to-voice/design
+    #
+    # @param voice_description [String] Description of the voice (20-1000 characters)
+    # @param options [Hash] Optional parameters
+    # @option options [String] :output_format Output format (e.g., "mp3_44100_192")
+    # @option options [String] :model_id Model to use (e.g., "eleven_multilingual_ttv_v2", "eleven_ttv_v3")
+    # @option options [String] :text Text to generate (100-1000 characters, optional)
+    # @option options [Boolean] :auto_generate_text Auto-generate text (default: false)
+    # @option options [Float] :loudness Loudness level (-1 to 1, default: 0.5)
+    # @option options [Integer] :seed Random seed (0 to 2147483647, optional)
+    # @option options [Float] :guidance_scale Guidance scale (0 to 100, default: 5)
+    # @option options [Boolean] :stream_previews Stream previews (default: false)
+    # @option options [String] :remixing_session_id Remixing session ID (optional)
+    # @option options [String] :remixing_session_iteration_id Remixing session iteration ID (optional)
+    # @option options [Float] :quality Quality level (-1 to 1, optional)
+    # @option options [String] :reference_audio_base64 Base64 encoded reference audio (optional, requires eleven_ttv_v3)
+    # @option options [Float] :prompt_strength Prompt strength (0 to 1, optional, requires eleven_ttv_v3)
+    # @return [Hash] JSON response containing previews and text
+    def design(voice_description, **options)
+      endpoint = "/v1/text-to-voice/design"
+      request_body = { voice_description: voice_description }
+
+      # Add optional parameters if provided
+      request_body[:output_format] = options[:output_format] if options[:output_format]
+      request_body[:model_id] = options[:model_id] if options[:model_id]
+      request_body[:text] = options[:text] if options[:text]
+      request_body[:auto_generate_text] = options[:auto_generate_text] unless options[:auto_generate_text].nil?
+      request_body[:loudness] = options[:loudness] if options[:loudness]
+      request_body[:seed] = options[:seed] if options[:seed]
+      request_body[:guidance_scale] = options[:guidance_scale] if options[:guidance_scale]
+      request_body[:stream_previews] = options[:stream_previews] unless options[:stream_previews].nil?
+      request_body[:remixing_session_id] = options[:remixing_session_id] if options[:remixing_session_id]
+      request_body[:remixing_session_iteration_id] = options[:remixing_session_iteration_id] if options[:remixing_session_iteration_id]
+      request_body[:quality] = options[:quality] if options[:quality]
+      request_body[:reference_audio_base64] = options[:reference_audio_base64] if options[:reference_audio_base64]
+      request_body[:prompt_strength] = options[:prompt_strength] if options[:prompt_strength]
+
+      @client.post(endpoint, request_body)
+    end
+
+    # POST /v1/text-to-voice
+    # Creates a voice from the designed voice generated_voice_id
+    # Documentation: https://elevenlabs.io/docs/api-reference/text-to-voice
+    #
+    # @param voice_name [String] Name of the voice
+    # @param voice_description [String] Description of the voice (20-1000 characters)
+    # @param generated_voice_id [String] The generated voice ID from design_voice
+    # @param options [Hash] Optional parameters
+    # @option options [Hash] :labels Optional metadata for the voice
+    # @option options [Array<String>] :played_not_selected_voice_ids Optional list of voice IDs played but not selected
+    # @return [Hash] JSON response containing voice_id and other voice details
+    def create(voice_name, voice_description, generated_voice_id, **options)
+      endpoint = "/v1/text-to-voice"
+      request_body = {
+        voice_name: voice_name,
+        voice_description: voice_description,
+        generated_voice_id: generated_voice_id
+      }
+
+      # Add optional parameters if provided
+      request_body[:labels] = options[:labels] if options[:labels]
+      request_body[:played_not_selected_voice_ids] = options[:played_not_selected_voice_ids] if options[:played_not_selected_voice_ids]
+
+      @client.post(endpoint, request_body)
+    end
+
+    # GET /v1/voices
+    # Retrieves all voices associated with your Elevenlabs account
+    # Documentation: https://elevenlabs.io/docs/api-reference/voices
+    #
+    # @return [Hash] The JSON response containing an array of voices
+    def list_voices
+      endpoint = "/v1/voices"
+      @client.get(endpoint)
+    end
+
+    # Alias methods for backward compatibility and convenience
+    alias_method :design_voice, :design
+    alias_method :create_from_generated_voice, :create
+
+    private
+
+    attr_reader :client
+  end
+end