openai/openai-ruby

openai/openai‑ruby – Official Ruby client for the OpenAI API

What it is

• A Ruby gem that wraps the OpenAI REST API, letting Ruby 3.3+ applications call models such as GPT‑4, Whisper, DALL‑E, and the newer Realtime and Agents endpoints.
• Provides typed request/response objects, Yard documentation, RBS/RBI files for Sorbet, and built‑in pagination, streaming, and file‑upload helpers.

Key capabilities

• Chat & completion – simple client.chat.completions.create calls.
• Streaming – Server‑Sent Events (SSE) for incremental token output.
• Agents (beta) – create long‑running agent sessions, retrieve final structured results, and download generated artifacts.
• Realtime WebSockets – block‑scoped text, transcription, voice, and WebRTC call control.
• Responses WebSocket – persistent multiplexed response creation.
• File handling – upload, poll for processing, stage files for hosted environments, and download artifacts.
• Custom HTTP transport – plug in your own client (e.g., for connection pooling, mTLS, or special proxy logic).
• Provider integrations – Azure OpenAI, Amazon Bedrock, and workload‑identity authentication are supported out of the box.

Typical use‑cases

• Building chat‑bots, assistants, or any LLM‑driven feature in a Ruby web or background service.
• Generating images, audio, or transcriptions directly from Ruby code.
• Running long‑running “agent” workflows that need stateful interaction and file I/O.
• Real‑time voice or text applications using the Realtime WebSocket API.
• Integrating with Azure OpenAI or AWS Bedrock without changing your code.

Installation

# In your Gemfile
gem "openai", "~> 0.103.0"

Run bundle install. The gem works with Ruby 3.3 or newer.

Quick start

require "bundler/setup"
require "openai"

client = OpenAI::Client.new(api_key: ENV["OPENAI_API_KEY"]) # key optional if env var set

# Simple chat completion
resp = client.chat.completions.create(
  model: "gpt-4o-mini",
  messages: [{role: "user", content: "Say this is a test"}]
)
puts resp

Streaming example

stream = client.responses.stream(input: "Write a haiku about OpenAI.", model: "gpt-4o-mini")
stream.each { |event| puts event.type }

Agent (beta) example

stream = client.beta.agents.sessions.create_streaming(
  agent: {model: "gpt-4o-mini", instructions: "Summarize the policy clearly."},
  environment: {type: :none},
  input: "Explain this policy: ..."
)
result = stream.get_final_result
puts result.output_text

Advanced features

• Use OpenAI::BaseModel subclasses to declare structured output types and get automatic parsing.
• Upload local files with client.files.create or stage them for an agent environment via client.beta.agents.environments.files.prepare.
• Enable mutual TLS by constructing a custom OpenAI::NetHTTPClient with a client cert and passing it to OpenAI::Client.
• Switch providers:

  client = OpenAI::Client.new(provider: OpenAI::Providers.azure(endpoint: ENV["AZURE_OPENAI_ENDPOINT"], api_key: ENV["AZURE_OPENAI_API_KEY"]))
  

Maturity & support

• Actively maintained by OpenAI (official repository).
• Comprehensive documentation on RubyDoc and the OpenAI platform docs.
• Supports the latest OpenAI features (Agents, Realtime, vector stores, etc.) with beta flags.

License

• Distributed under the MIT License (see the repository’s LICENSE file).

---

This summary is based solely on the README content of the openai/openai‑ruby repository.