ruby-gemini-api 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31487006e959d8d9a755743f6471b54e075a1bc91aa36718274203deb9fda84d
-  data.tar.gz: bc7dbbbea933ed2343b2ec1a32d3cf9b03fe41a4494801c47e5d83842bf31603
+  metadata.gz: 325e8812a1eb58643280cdfba86f4a8a9a8e3659d882d8fb5fc5e4ac2025a35c
+  data.tar.gz: 1bcf959e036341fe71a41a693accc9f0d85a0fe790f43811a2af7ae3b455e10b
 SHA512:
-  metadata.gz: cc033c4ab711800c56f2f1d8884c38a74359d7c3b66fb66ed39ea03b23b98c3748d08208dc560e3276ac3d6e25660ad3a2c5aef69ef25b523bbd6512a5b5d246
-  data.tar.gz: 998ca95babf2803241a9d0a01c00eefe7fcbd37990723ffc9378668bc30f5529a90daa92b20919e5c0e681f68f4e8a5d4206e66520eeec46da9aa18c169fc9be
+  metadata.gz: 243dd3d0f56a645305e1345de08ca7512088e0d7ae2dfd45f2b5747614c469ed35523991da8cb7d4bef08f060b0cbfb666903e0b5c262e18cebece66405753b9
+  data.tar.gz: fa2234b64394200ab6039010f88d5b9ac97c70e4e4266943b0ee57848e7f0141bebe3a50929d315bb54b4ddd88c990c07d3a26cf54f904b1e89727a53a4c8a12

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+### Added
+- Code Execution shortcut support via `code_execution: true` on `generate_content` / `generate_content_stream`
+- `Response` helpers for Code Execution results: `#code_execution?`, `#executable_code`, `#executable_codes`, `#code_execution_output`, `#code_execution_outcome`, `#code_execution_success?`, `#code_execution_results`
+
+## [1.2.0] - 2026-05-14
+
+### Added
+- TTS (speech generation) API support
+  - `client.tts.generate(text, voice:)` and `client.generate_speech(text, voice:)` shortcut
+  - Single-speaker mode via `voice:` and multi-speaker mode via `multi_speaker: [{ speaker:, voice: }, ...]`
+  - 30 prebuilt voices exposed as `Gemini::TTS::VOICES`
+  - Default model `gemini-2.5-flash-preview-tts` (override via `model:`)
+  - `Response` helpers: `#audio_data`, `#audio_mime_type`, `#audio_response?`, `#save_audio(path)` which auto-wraps L16 PCM in a RIFF/WAVE header
+  - Demos: `tts_demo.rb` / `tts_demo_ja.rb`
+- `countTokens` API support
+  - `client.tokens.count(input, ...)` and `client.count_tokens(input, ...)` shortcut
+  - Accepts String / Array / Hash inputs, full `contents:` array, plus optional `system_instruction:`, `tools:`, `generation_config:`, `cached_content:` (auto-wraps payload in `generateContentRequest` when extra fields are present)
+  - `Response` helpers: `#count_tokens`, `#prompt_tokens_details`, `#cached_content_token_count`, `#count_tokens_response?`
+  - Demos: `count_tokens_demo.rb` / `count_tokens_demo_ja.rb`
+
 ## [1.1.0] - 2026-04-29
 
 ### Added

data/README.md

@@ -31,7 +31,10 @@ This project is inspired by and pays homage to [ruby-openai](https://github.com/
 - Document processing (PDFs and other formats)
 - Context caching for efficient processing
 - Text embeddings (single and batch) with task type, title, and output dimensionality control
+- Token counting (`countTokens`) for prompts, chat history, and full requests with system instruction / tools / cached content
+- Speech generation (TTS) with 30 prebuilt voices, single-speaker and multi-speaker modes, and one-line WAV file output
 - Live API: real-time bidirectional conversations with text/audio/video and function calling (sync and async)
+- Code Execution: let the model generate and run Python code, then inspect generated code and execution results
 
 ### Function Calling
 
@@ -108,11 +111,65 @@ puts "After deleting a function: #{all_tools.list_functions}"
 # => After deleting a function: [:get_current_weather, :send_email]
 ```
 
+### Code Execution
+
+Pass `code_execution: true` to let Gemini generate and run Python code when it helps answer calculation or data-processing tasks.
+
+```ruby
+require 'gemini'
+
+client = Gemini::Client.new(ENV['GEMINI_API_KEY'])
+
+response = client.generate_content(
+  "Calculate the sum of the first 50 prime numbers and show the code you used",
+  model: "gemini-3.5-flash",
+  code_execution: true
+)
+
+puts response.text
+
+if response.code_execution?
+  puts response.executable_code
+  puts response.code_execution_outcome
+  puts response.code_execution_output
+end
+```
+
+You can also inspect all generated code and execution results:
+
+```ruby
+response.executable_codes          # => [{"language"=>"PYTHON", "code"=>"..."}]
+response.code_execution_results    # => [{"outcome"=>"OUTCOME_OK", "output"=>"..."}]
+response.code_execution_success?   # => true
+```
+
+Code Execution also works with image inputs. For Gemini 3 models, combine it with `thinking_level` when you want the model to inspect an image with code.
+
+```ruby
+response = client.generate_content(
+  [
+    { type: "text", text: "Read the small numbers in this image" },
+    { type: "image_file", image_file: { file_path: "meter.jpg" } }
+  ],
+  model: "gemini-3.5-flash",
+  code_execution: true,
+  thinking_level: :medium
+)
+```
+
+A complete example is available in `demo/code_execution_demo.rb`.
+
 ### Thinking Feature
 
 Gemini 2.5 and later models support the Thinking feature, which enables the model to perform internal reasoning processes for complex problems to generate higher-quality answers.
 
-#### Using with Gemini 2.5: `thinking_budget`
+#### Deprecation notice: thinking and sampling controls
+
+For Gemini 3 and later models, prefer `thinking_level` (`:minimal`, `:low`, `:medium`, `:high`) instead of `thinking_budget`. The `thinking_budget` option remains available for Gemini 2.5 compatibility, but it should be treated as a legacy control when targeting newer models.
+
+Sampling parameters such as `temperature`, `top_p`, and `top_k` are also considered legacy tuning knobs for newer Gemini models. Existing code can continue to pass them through for backward compatibility, but new integrations should rely on model defaults and Thinking controls first.
+
+#### Legacy Gemini 2.5 usage: `thinking_budget`
 
 ```ruby
 require 'gemini'
@@ -143,7 +200,7 @@ response = client.generate_content(
 )
 ```
 
-#### Using with Gemini 3: `thinking_level`
+#### Recommended Gemini 3 usage: `thinking_level`
 
 ```ruby
 # Specify thinking level (:minimal, :low, :medium, :high)
@@ -1263,6 +1320,181 @@ response.embedding_response?  # true if the payload contains embedding data
 
 A complete example is available in `demo/embeddings_demo.rb`.
 
+### Token Counting
+
+Estimate how many tokens an input would consume before sending it to a generation endpoint. Useful for cost/quota planning and for staying within a model's context window.
+
+#### Basic Usage
+
+```ruby
+require 'gemini'
+
+client = Gemini::Client.new(ENV['GEMINI_API_KEY'])
+
+response = client.count_tokens("The quick brown fox jumps over the lazy dog.")
+
+puts response.count_tokens             # => 9 (totalTokens)
+puts response.prompt_tokens_details    # => [{"modality"=>"TEXT", "tokenCount"=>9}]
+```
+
+By default the request goes to `gemini-2.5-flash`. Override it with `model:`:
+
+```ruby
+client.count_tokens("Hello", model: "gemini-2.5-pro")
+```
+
+#### Multi-turn Chat History
+
+Pass a fully formed `contents:` array (the same shape used by `generateContent`) to count tokens for an entire conversation:
+
+```ruby
+response = client.count_tokens(
+  contents: [
+    { role: "user",  parts: [{ text: "Hi, my name is Bob." }] },
+    { role: "model", parts: [{ text: "Hi Bob!" }] },
+    { role: "user",  parts: [{ text: "What's the weather like today?" }] }
+  ]
+)
+```
+
+#### With System Instruction, Tools, or Cached Content
+
+When you include `system_instruction:`, `tools:`, `generation_config:`, or `cached_content:`, the request is automatically wrapped as a `generateContentRequest` so the count reflects the full payload:
+
+```ruby
+response = client.count_tokens(
+  "What is the weather in Tokyo?",
+  system_instruction: "You are a concise weather assistant.",
+  tools: [
+    {
+      function_declarations: [
+        {
+          name: "get_weather",
+          description: "Get the current weather for a city.",
+          parameters: {
+            type: "object",
+            properties: { city: { type: "string" } },
+            required: ["city"]
+          }
+        }
+      ]
+    }
+  ]
+)
+
+puts response.count_tokens
+```
+
+#### Direct Access via `tokens`
+
+```ruby
+client.tokens.count("Hello", model: "gemini-2.5-flash")
+```
+
+#### Response Helpers
+
+```ruby
+response.count_tokens                # totalTokens from the API (Integer)
+response.prompt_tokens_details       # per-modality breakdown (Array<Hash>)
+response.cached_content_token_count  # tokens reused from cachedContent (Integer)
+response.count_tokens_response?      # true if the payload is a countTokens response
+```
+
+A complete example is available in `demo/count_tokens_demo.rb`.
+
+### Speech Generation (TTS)
+
+Generate spoken audio from text using Gemini's TTS preview models. The API returns 24 kHz, 16-bit, mono PCM (L16) audio; `Response#save_audio` wraps it in a RIFF/WAVE header so the result is directly playable.
+
+#### Single-Speaker
+
+```ruby
+require 'gemini'
+
+client = Gemini::Client.new(ENV['GEMINI_API_KEY'])
+
+response = client.generate_speech(
+  "Say cheerfully: Have a wonderful day!",
+  voice: "Kore"
+)
+
+if response.success?
+  response.save_audio("hello.wav")
+  puts response.audio_mime_type # => "audio/L16;codec=pcm;rate=24000"
+end
+```
+
+Phrase the prompt as an instruction to read text aloud (`Say ...:` / `Read the following:`); a bare phrase like `"Hello"` is treated as a chat message and rejected with a 400 error.
+
+#### Multi-Speaker
+
+Provide a `multi_speaker:` array to assign different voices to named speakers (up to 2 speakers in the current preview models). Reference the speakers by the same names in your prompt.
+
+```ruby
+script = <<~SCRIPT
+  TTS the following conversation between Joe and Jane:
+  Joe: How's it going today, Jane?
+  Jane: Not too bad, how about you?
+SCRIPT
+
+response = client.generate_speech(
+  script,
+  multi_speaker: [
+    { speaker: "Joe",  voice: "Kore" },
+    { speaker: "Jane", voice: "Puck" }
+  ]
+)
+
+response.save_audio("dialogue.wav")
+```
+
+#### Style Control
+
+You can steer tone, pace, and emotion in two ways.
+
+**1. Natural-language instruction** — describe the delivery as part of the prompt.
+
+```ruby
+client.generate_speech(
+  "Read this in a soft whisper: I have a secret... and you must never tell anyone.",
+  voice: "Zephyr"
+)
+```
+
+**2. Inline bracket tag** — put a directive like `[whispers]`, `[excited]`, `[laughs]`, `[sighs]`, `[shouting]`, etc. at the start of the text to apply that style to what follows.
+
+```ruby
+client.generate_speech(
+  "[whispers] I have a secret... and you must never tell anyone.",
+  voice: "Zephyr"
+)
+```
+
+Stick to **one style per call**: switching style mid-prompt (e.g. `[whispers] ... [excited] ...`) tends to leave the second segment in the first style or drop it entirely. If you need multiple styles, call `generate_speech` once per sentence and concatenate the audio yourself.
+
+#### Models and Voices
+
+- Default model: `gemini-2.5-flash-preview-tts` (override via `model:`)
+- Other models: `gemini-2.5-pro-preview-tts`, `gemini-3.1-flash-tts-preview`
+- 30 prebuilt voices are listed in `Gemini::TTS::VOICES` (Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, …). Unknown names raise `ArgumentError` at build time.
+
+#### Direct Access via `tts`
+
+```ruby
+client.tts.generate("Say hello.", voice: "Kore")
+```
+
+#### Response Helpers
+
+```ruby
+response.audio_data        # Base64-encoded PCM payload
+response.audio_mime_type   # e.g. "audio/L16;codec=pcm;rate=24000"
+response.audio_response?   # true if the payload contains audio inlineData
+response.save_audio(path)  # writes a playable .wav file and returns the path
+```
+
+A complete example is available in `demo/tts_demo.rb`.
+
 ### Structured Output with JSON Schema
 
 You can request responses in structured JSON format by specifying a JSON schema:
@@ -1498,6 +1730,7 @@ The gem includes several demo applications that showcase its functionality:
 - `demo/file_audio_demo.rb` - Audio transcription with large audio files
 - `demo/structured_output_demo.rb` - Structured JSON output with schema
 - `demo/enum_response_demo.rb` - Enum-constrained responses
+- `demo/code_execution_demo.rb` - Code Execution with generated Python code and execution output
 - `demo/thinking_demo.rb` - Thinking feature (Gemini 2.5)
 - `demo/thinking_gemini3_demo.rb` - Thinking feature (Gemini 3)
 - `demo/document_chat_demo.rb` - Document processing
@@ -1547,6 +1780,12 @@ ruby demo/structured_output_demo.rb
 # Enum-constrained responses
 ruby demo/enum_response_demo.rb
 
+# Code Execution
+ruby demo/code_execution_demo.rb
+
+# Code Execution with a different model
+GEMINI_MODEL=gemini-3.5-pro ruby demo/code_execution_demo.rb
+
 # Thinking feature (Gemini 2.5)
 ruby demo/thinking_demo.rb
 
@@ -1568,11 +1807,16 @@ ruby demo/embeddings_demo.rb
 
 ## Models
 
-The library supports various Gemini models:
+Model names can be passed as strings. Common examples:
 
+- `gemini-3.5-flash`
+- `gemini-3.5-pro`
+- `gemini-3-flash-preview`
 - `gemini-2.5-flash`
 - `gemini-2.5-pro`
 
+Use `client.models.list` to check models available to your API key.
+
 ## Requirements
 
 - Ruby 3.0 or higher
@@ -1589,4 +1833,4 @@ The library supports various Gemini models:
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/gemini/client.rb

@@ -80,6 +80,46 @@ module Gemini
       @embeddings_api ||= Gemini::Embeddings.new(client: self)
     end
 
+    # Token counting APIアクセサ
+    def tokens
+      @tokens ||= Gemini::Tokens.new(client: self)
+    end
+
+    # TTS (speech generation) APIアクセサ
+    def tts
+      @tts ||= Gemini::TTS.new(client: self)
+    end
+
+    # Convenience wrapper for TTS speech generation.
+    def generate_speech(text, voice: nil, multi_speaker: nil, model: Gemini::TTS::DEFAULT_MODEL,
+                        speech_config: nil, **parameters)
+      tts.generate(
+        text,
+        voice: voice,
+        multi_speaker: multi_speaker,
+        model: model,
+        speech_config: speech_config,
+        **parameters
+      )
+    end
+
+    # Convenience wrapper for countTokens.
+    # input can be a String, Array of parts/strings, Hash, or omitted when contents: is given.
+    def count_tokens(input = nil, model: Gemini::Tokens::DEFAULT_MODEL, contents: nil,
+                     system_instruction: nil, tools: nil, generation_config: nil,
+                     cached_content: nil, **parameters)
+      tokens.count(
+        input,
+        model: model,
+        contents: contents,
+        system_instruction: system_instruction,
+        tools: tools,
+        generation_config: generation_config,
+        cached_content: cached_content,
+        **parameters
+      )
+    end
+
     def reset_headers
       @extra_headers = {}
     end
@@ -162,6 +202,7 @@ module Gemini
     def generate_content(prompt, model: "gemini-2.5-flash", system_instruction: nil,
                         response_mime_type: nil, response_schema: nil, temperature: 0.5, tools: nil,
                         url_context: false, google_search: false,
+                        code_execution: false,
                         thinking_budget: nil, thinking_level: nil,
                         **parameters, &stream_callback)
       content = format_content(prompt)
@@ -190,7 +231,12 @@ module Gemini
       end
 
       # Handle tool shortcuts
-      tools = build_tools_array(tools, url_context: url_context, google_search: google_search)
+      tools = build_tools_array(
+        tools,
+        url_context: url_context,
+        google_search: google_search,
+        code_execution: code_execution
+      )
       params[:tools] = tools if tools && !tools.empty?
 
       params.merge!(parameters)
@@ -205,7 +251,8 @@ module Gemini
     # Streaming text generation
     def generate_content_stream(prompt, model: "gemini-2.5-flash", system_instruction: nil,
                               response_mime_type: nil, response_schema: nil, temperature: 0.5,
-                              url_context: false, google_search: false, **parameters, &block)
+                              url_context: false, google_search: false, code_execution: false,
+                              **parameters, &block)
       raise ArgumentError, "Block is required for streaming" unless block_given?
 
       content = format_content(prompt)
@@ -230,7 +277,12 @@ module Gemini
       params[:generation_config]["temperature"] = temperature
 
       # Handle tool shortcuts
-      tools = build_tools_array(nil, url_context: url_context, google_search: google_search)
+      tools = build_tools_array(
+        nil,
+        url_context: url_context,
+        google_search: google_search,
+        code_execution: code_execution
+      )
       params[:tools] = tools if tools && !tools.empty?
 
       # Merge other parameters
@@ -495,7 +547,7 @@ module Gemini
     end
 
     # Build tools array from explicit tools parameter and shortcuts
-    def build_tools_array(tools, url_context: false, google_search: false)
+    def build_tools_array(tools, url_context: false, google_search: false, code_execution: false)
       result_tools = []
 
       # Add existing tools if provided
@@ -511,6 +563,9 @@ module Gemini
       # Add google_search tool if requested
       result_tools << { google_search: {} } if google_search
 
+      # Add code_execution tool if requested
+      result_tools << { code_execution: {} } if code_execution
+
       # Remove duplicates based on tool keys and return
       return nil if result_tools.empty?
       result_tools.uniq { |tool| tool.keys.first }
@@ -645,4 +700,4 @@ module Gemini
       end
     end
   end
-end
+end

data/lib/gemini/response.rb

@@ -37,13 +37,135 @@ module Gemini
       
       parts.select { |part| part.key?("text") }.map { |part| part["text"] }
     end
+
+    # Get all executableCode parts returned by the Code Execution tool.
+    def executable_codes
+      return [] unless valid?
+
+      parts.map { |part| part["executableCode"] || part["executable_code"] }.compact
+    end
+
+    # Get the first generated code string from a Code Execution response.
+    def executable_code
+      code_part = executable_codes.first
+      return nil unless code_part
+
+      code_part["code"] || code_part[:code]
+    end
+
+    # Get all codeExecutionResult parts returned by the Code Execution tool.
+    def code_execution_results
+      return [] unless valid?
+
+      parts.map { |part| part["codeExecutionResult"] || part["code_execution_result"] }.compact
+    end
+
+    # Get the first execution output string from a Code Execution response.
+    def code_execution_output
+      result_part = code_execution_results.first
+      return nil unless result_part
+
+      result_part["output"] || result_part[:output]
+    end
+
+    # Get the first execution outcome (for example "OUTCOME_OK").
+    def code_execution_outcome
+      result_part = code_execution_results.first
+      return nil unless result_part
+
+      result_part["outcome"] || result_part[:outcome]
+    end
+
+    # True when the first Code Execution result completed successfully.
+    def code_execution_success?
+      code_execution_outcome == "OUTCOME_OK"
+    end
+
+    # True if the response contains generated code or execution results.
+    def code_execution?
+      !executable_codes.empty? || !code_execution_results.empty?
+    end
     
     # Get image parts (if any)
     def image_parts
       return [] unless valid?
-      
+
       parts.select { |part| part.key?("inline_data") && part["inline_data"]["mime_type"].start_with?("image/") }
     end
+
+    # Get the first audio inlineData part (TTS responses use camelCase "inlineData")
+    def audio_part
+      return nil unless valid?
+
+      parts.find do |part|
+        data_key = part["inlineData"] || part["inline_data"]
+        next false unless data_key
+        mt = data_key["mimeType"] || data_key["mime_type"]
+        mt.is_a?(String) && mt.start_with?("audio/")
+      end
+    end
+
+    # Base64-encoded audio data from a TTS response
+    def audio_data
+      part = audio_part
+      return nil unless part
+      data_key = part["inlineData"] || part["inline_data"]
+      data_key["data"]
+    end
+
+    # MIME type of the audio payload (e.g. "audio/L16;codec=pcm;rate=24000")
+    def audio_mime_type
+      part = audio_part
+      return nil unless part
+      data_key = part["inlineData"] || part["inline_data"]
+      data_key["mimeType"] || data_key["mime_type"]
+    end
+
+    # True if the response contains audio inlineData
+    def audio_response?
+      !audio_part.nil?
+    end
+
+    # Save audio to a file. PCM (L16) payloads are wrapped in a WAV header so
+    # the result is directly playable; other audio MIME types are written as-is.
+    # Returns the written file path or nil if no audio is present.
+    def save_audio(filepath)
+      data_b64 = audio_data
+      return nil unless data_b64
+
+      require 'base64'
+      raw = Base64.strict_decode64(data_b64)
+      mime = audio_mime_type.to_s
+
+      if mime.include?("L16") || mime.include?("pcm")
+        rate = mime[/rate=(\d+)/, 1]&.to_i || 24000
+        channels = 1
+        bits_per_sample = 16
+        byte_rate = rate * channels * bits_per_sample / 8
+        block_align = channels * bits_per_sample / 8
+        data_size = raw.bytesize
+
+        header = +""
+        header << "RIFF"
+        header << [36 + data_size].pack("V")
+        header << "WAVE"
+        header << "fmt "
+        header << [16].pack("V")
+        header << [1].pack("v")
+        header << [channels].pack("v")
+        header << [rate].pack("V")
+        header << [byte_rate].pack("V")
+        header << [block_align].pack("v")
+        header << [bits_per_sample].pack("v")
+        header << "data"
+        header << [data_size].pack("V")
+
+        File.binwrite(filepath, header + raw)
+      else
+        File.binwrite(filepath, raw)
+      end
+      filepath
+    end
     
     # Get all content with string representation
     def full_content
@@ -73,7 +195,8 @@ module Gemini
       !@raw_data.nil? &&
       ((@raw_data.key?("candidates") && !@raw_data["candidates"].empty?) ||
        (@raw_data.key?("predictions") && !@raw_data["predictions"].empty?) ||
-       embedding_response?)
+       embedding_response? ||
+       count_tokens_response?)
     end
 
     # Check if the raw response contains embedding data
@@ -231,6 +354,28 @@ module Gemini
     def total_tokens
       usage&.dig("totalTokens") || 0
     end
+
+    # Check whether this response is a countTokens API result
+    def count_tokens_response?
+      !@raw_data.nil? && @raw_data.key?("totalTokens") &&
+        !@raw_data.key?("candidates") && !@raw_data.key?("predictions") &&
+        !embedding_response?
+    end
+
+    # Total tokens reported by the countTokens API (top-level totalTokens)
+    def count_tokens
+      @raw_data&.dig("totalTokens")
+    end
+
+    # Cached content token count reported by countTokens
+    def cached_content_token_count
+      @raw_data&.dig("cachedContentTokenCount") || 0
+    end
+
+    # Per-modality token breakdown reported by countTokens
+    def prompt_tokens_details
+      @raw_data&.dig("promptTokensDetails") || []
+    end
     
     # Process chunks for streaming responses
     def stream_chunks
@@ -553,4 +698,4 @@ module Gemini
       end
     end
   end
-end
+end

data/lib/gemini/tokens.rb

@@ -0,0 +1,77 @@
+module Gemini
+  class Tokens
+    DEFAULT_MODEL = "gemini-2.5-flash".freeze
+
+    def initialize(client:)
+      @client = client
+    end
+
+    # Count tokens for the given input.
+    #
+    # input: String, Array of parts/contents, or Hash. Optional when `contents:` is given.
+    # contents: full Array of Content objects (overrides input).
+    # system_instruction: String or Content hash.
+    # tools: Array of tool definitions (passed via generateContentRequest form).
+    # generation_config: Hash forwarded as generationConfig.
+    # cached_content: cachedContents/* resource name.
+    def count(input = nil, model: DEFAULT_MODEL, contents: nil, system_instruction: nil,
+              tools: nil, generation_config: nil, cached_content: nil, **parameters)
+      normalized_model = normalize_model(model)
+
+      payload = build_payload(
+        model: normalized_model,
+        input: input,
+        contents: contents,
+        system_instruction: system_instruction,
+        tools: tools,
+        generation_config: generation_config,
+        cached_content: cached_content
+      ).merge(parameters)
+
+      response = @client.json_post(
+        path: "models/#{normalized_model}:countTokens",
+        parameters: payload
+      )
+      Gemini::Response.new(response)
+    end
+
+    private
+
+    def build_payload(model:, input:, contents:, system_instruction:, tools:, generation_config:, cached_content:)
+      resolved_contents = contents || [format_content(input)]
+
+      # Use generateContentRequest form when extra request fields are present
+      if system_instruction || tools || generation_config || cached_content
+        # model is required inside the nested GenerateContentRequest
+        gc_request = { model: "models/#{model}", contents: resolved_contents }
+        gc_request[:systemInstruction] = format_content(system_instruction) if system_instruction
+        gc_request[:tools] = tools if tools
+        gc_request[:generationConfig] = generation_config if generation_config
+        gc_request[:cachedContent] = cached_content if cached_content
+        { generateContentRequest: gc_request }
+      else
+        { contents: resolved_contents }
+      end
+    end
+
+    def format_content(input)
+      case input
+      when nil
+        raise ArgumentError, "input or contents parameter is required"
+      when String
+        { parts: [{ text: input }] }
+      when Array
+        { parts: input.map { |part| part.is_a?(String) ? { text: part } : part } }
+      when Hash
+        input.key?(:parts) || input.key?("parts") ? input : { parts: [input] }
+      else
+        { parts: [{ text: input.to_s }] }
+      end
+    end
+
+    def normalize_model(model)
+      model_str = model.to_s
+      model_str.start_with?("models/") ? model_str.delete_prefix("models/") : model_str
+    end
+  end
+end

data/lib/gemini/tts.rb

@@ -0,0 +1,83 @@
+module Gemini
+  class TTS
+    DEFAULT_MODEL = "gemini-2.5-flash-preview-tts".freeze
+
+    # 30 prebuilt voice names available for the prebuiltVoiceConfig
+    VOICES = %w[
+      Zephyr Puck Charon Kore Fenrir Leda Orus Aoede Callirrhoe Autonoe
+      Enceladus Iapetus Umbriel Algieba Despina Erinome Algenib Rasalgethi
+      Laomedeia Achernar Alnilam Schedar Gacrux Pulcherrima Achird
+      Zubenelgenubi Vindemiatrix Sadachbia Sadaltager Sulafat
+    ].freeze
+
+    def initialize(client:)
+      @client = client
+    end
+
+    # Generate speech audio from text.
+    #
+    # text: prompt String (use style cues / bracket tags like [excited] for control,
+    #       or "Speaker 1: ... Speaker 2: ..." for multi-speaker).
+    # voice: a single voice name (prebuiltVoiceConfig). Mutually exclusive with multi_speaker.
+    # multi_speaker: Array of { speaker:, voice: } Hashes for multi-speaker output.
+    # model: TTS preview model name. Defaults to gemini-2.5-flash-preview-tts.
+    # speech_config: raw speechConfig Hash override (skips voice/multi_speaker handling).
+    def generate(text, voice: nil, multi_speaker: nil, model: DEFAULT_MODEL,
+                 speech_config: nil, **parameters)
+      raise ArgumentError, "text is required" if text.nil? || text.to_s.empty?
+      if voice && multi_speaker
+        raise ArgumentError, "voice and multi_speaker are mutually exclusive"
+      end
+
+      resolved_speech_config = speech_config || build_speech_config(voice: voice, multi_speaker: multi_speaker)
+      raise ArgumentError, "voice, multi_speaker, or speech_config is required" unless resolved_speech_config
+
+      payload = {
+        contents: [{ parts: [{ text: text }] }],
+        generationConfig: {
+          responseModalities: ["AUDIO"],
+          speechConfig: resolved_speech_config
+        }
+      }
+
+      payload.merge!(parameters) if parameters && !parameters.empty?
+
+      response = @client.json_post(
+        path: "models/#{normalize_model(model)}:generateContent",
+        parameters: payload
+      )
+      Gemini::Response.new(response)
+    end
+
+    private
+
+    def build_speech_config(voice:, multi_speaker:)
+      if multi_speaker
+        speaker_voice_configs = multi_speaker.map do |entry|
+          speaker = entry[:speaker] || entry["speaker"]
+          v = entry[:voice] || entry["voice"]
+          raise ArgumentError, "multi_speaker entries require :speaker and :voice" unless speaker && v
+          validate_voice!(v)
+          {
+            speaker: speaker,
+            voiceConfig: { prebuiltVoiceConfig: { voiceName: v } }
+          }
+        end
+        { multiSpeakerVoiceConfig: { speakerVoiceConfigs: speaker_voice_configs } }
+      elsif voice
+        validate_voice!(voice)
+        { voiceConfig: { prebuiltVoiceConfig: { voiceName: voice } } }
+      end
+    end
+
+    def validate_voice!(voice)
+      return if VOICES.include?(voice.to_s)
+      raise ArgumentError, "Unknown voice '#{voice}'. Available voices: #{VOICES.join(', ')}"
+    end
+
+    def normalize_model(model)
+      model_str = model.to_s
+      model_str.start_with?("models/") ? model_str.delete_prefix("models/") : model_str
+    end
+  end
+end

data/lib/gemini/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gemini
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/gemini.rb

@@ -12,6 +12,8 @@ require_relative "gemini/threads"
 require_relative "gemini/messages"
 require_relative "gemini/runs"
 require_relative "gemini/embeddings"
+require_relative "gemini/tokens"
+require_relative "gemini/tts"
 require_relative "gemini/audio"
 require_relative "gemini/files"
 require_relative "gemini/images"

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-gemini-api
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - rira100000000
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -180,7 +181,9 @@ files:
 - lib/gemini/response.rb
 - lib/gemini/runs.rb
 - lib/gemini/threads.rb
+- lib/gemini/tokens.rb
 - lib/gemini/tool_definition.rb
+- lib/gemini/tts.rb
 - lib/gemini/version.rb
 - lib/gemini/video.rb
 - lib/ruby/gemini.rb
@@ -192,6 +195,7 @@ metadata:
   source_code_uri: https://github.com/rira100000000/ruby-gemini-api
   changelog_uri: https://github.com/rira100000000/ruby-gemini-api/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -206,7 +210,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.3.26
+signing_key:
 specification_version: 4
 summary: Ruby client for Google's Gemini API
 test_files: []