ruby-gemini-api 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31487006e959d8d9a755743f6471b54e075a1bc91aa36718274203deb9fda84d
-  data.tar.gz: bc7dbbbea933ed2343b2ec1a32d3cf9b03fe41a4494801c47e5d83842bf31603
+  metadata.gz: cd1be2a2b81543d21686e9d4ade4de2e6aa42ea8b26abc4bb0929e9aa77fada0
+  data.tar.gz: 9b96121c0a8a68220e4e368057424211e29e0652f28f1812b56049842d31c5c9
 SHA512:
-  metadata.gz: cc033c4ab711800c56f2f1d8884c38a74359d7c3b66fb66ed39ea03b23b98c3748d08208dc560e3276ac3d6e25660ad3a2c5aef69ef25b523bbd6512a5b5d246
-  data.tar.gz: 998ca95babf2803241a9d0a01c00eefe7fcbd37990723ffc9378668bc30f5529a90daa92b20919e5c0e681f68f4e8a5d4206e66520eeec46da9aa18c169fc9be
+  metadata.gz: be505ec75d011d31cd3c741924b2e845024d4bccdc36b3fbdfa63e0468771a45f7dd4abbc31ec6ade82ff4e992b46bd9e3aa65a06bd874a73a799f1cdb246bed
+  data.tar.gz: edcc02ff33b17e56a004836b2c55c7a133d883bc38c9f67893f3d3a59afb239bf7329454ef8278cf618e2d393867e445dc88bf539350999258c856f02c775b69

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [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,6 +31,8 @@ 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)
 
 ### Function Calling
@@ -1263,6 +1265,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:

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

data/lib/gemini/response.rb

@@ -41,9 +41,83 @@ module Gemini
     # 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 +147,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 +306,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

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.2.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-gemini-api
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - rira100000000
@@ -180,7 +180,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