[opensourcedex]

ruby-openai is a free, open source api development & testing project written in Ruby and released under MIT. It has 3,224 GitHub stars, 383 forks and 55 open issues, and was last pushed 5 months ago. On this registry it ranks #66 of 103 tracked projects in API Development & Testing, with 5 head-to-head comparisons available. It gained 1 stars over the last 3 tracked days.

What is ruby-openai?

What it is

ruby-openai is a Ruby client library for the OpenAI API, released under the MIT license, and it is listed in the Developer Tools / API Development & Testing category. The repository has 3,222 stars, 383 forks, and a six-year age, with the last push recorded on 2026-05-01T14:37:06Z. It lives in the Ruby and Rails ecosystem, and its topics include ai, api-client, chatgpt, dall-e, gpt-4, gpt-4o, o1, openai, rails, ruby, and whisper.

The library solves the concrete problem of calling OpenAI-compatible endpoints from Ruby code without hand-writing HTTP requests, JSON payloads, streaming handling, and error parsing. The README says that users can stream GPT-5 chats with the Responses API, initiate Realtime WebRTC conversations, and use many other OpenAI features through one client.

Key capabilities

  • It supports chat, streaming chat, completions, embeddings, and Responses API workflows, including GPT-5 chat streaming, follow-up messages, tool calls, retrieval, deletion, and listing input items.
  • It can initiate Realtime WebRTC conversations and includes vision, JSON mode, image generation, image edit, image variations, DALL·E 2, DALL·E 3, Whisper transcription, translation, speech, and moderation.
  • It exposes assistants, threads, messages, runs, create-and-run flows, files, batches, vector stores, vector store files, vector store file batches, and file search chunks.
  • It supports model listing, token counting, custom timeouts, custom base URIs, extra headers per client, logging, errors, and Faraday middleware.
  • It documents usage with Azure, Deepseek, Ollama, Groq, and Gemini, in addition to the OpenAI API.

Who uses it and how

  • Ruby and Rails developers use it to add chat, streaming, vision, embeddings, and assistant workflows to applications that already have an OpenAI API key.
  • Teams building conversational products can use the Responses API sections for create, retrieve, delete, follow-up messages, tool calls, and streaming.
  • Developers can use it to upload files, create vector stores, manage threads and runs, and inspect chunks used in file search.

Getting started

Add gem "ruby-openai" to the Gemfile and run bundle install, or run gem install ruby-openai and require "openai" after obtaining an API key from https://platform.openai.com/account/api-keys.

When to use it — and when not to

It is useful when a Ruby application needs a client for OpenAI-compatible APIs, but it is not a hosted service or full application platform because it only wraps API calls and leaves persistence, UI, billing, and model hosting to the developer. A self-hoster must operate the Ruby application, secure API keys, handle provider errors, and configure timeouts, base URIs, headers, logging, or Faraday middleware. The provided facts show 55 open issues, no listed hosted option, and unknown contributor count, so teams needing a managed service or a non-Ruby client should evaluate alternatives.

project readme (upstream, from github) — read inline

Ruby OpenAI

Gem Version GitHub license CircleCI Build Status

Use the OpenAI API with Ruby! 🤖❤️

Stream GPT-5 chats with the Responses API, initiate Realtime WebRTC conversations, and much more...

Sponsors

InferToGo logo: man in suit falling, black and white

InferToGo - The inference addon for your PaaS application.

SerpApi logo: Purple rounded square with 4 connected white holes

SerpApi - Search API - Enhance your LLM's knowledge with data from search engines like Google and Bing using our simple API.

🎮 Ruby AI Builders Discord | 🐦 X | 🧠 Anthropic Gem | 🚂 Midjourney Gem | ♥️ Thanks to all sponsors!

Contents

Project Policies

Installation

Bundler

Add this line to your application's Gemfile:

gem "ruby-openai"

And then execute:

bundle install

Gem install

Or install with:

gem install ruby-openai

and require with:

require "openai"

How to use

Quickstart

For a quick test you can pass your token directly to a new client:

client = OpenAI::Client.new(
  access_token: "access_token_goes_here",
  log_errors: true # Highly recommended in development, so you can see what errors OpenAI is returning. Not recommended in production because it could leak private data to your logs.
)

With Config

For a more robust setup, you can configure the gem with your API keys, for example in an openai.rb initializer file. Never hardcode secrets into your codebase - instead use something like dotenv to pass the keys safely into your environments.

OpenAI.configure do |config|
  config.access_token = ENV.fetch("OPENAI_ACCESS_TOKEN")
  config.admin_token = ENV.fetch("OPENAI_ADMIN_TOKEN") # Optional, used for admin endpoints, created here: https://platform.openai.com/settings/organization/admin-keys
  config.organization_id = ENV.fetch("OPENAI_ORGANIZATION_ID") # Optional
  config.log_errors = true # Highly recommended in development, so you can see what errors OpenAI is returning. Not recommended in production because it could leak private data to your logs.
end

Then you can create a client like this:

client = OpenAI::Client.new

You can still override the config defaults when making new clients; any options not included will fall back to any global config set with OpenAI.configure. e.g. in this example the organization_id, request_timeout, etc. will fallback to any set globally using OpenAI.configure, with only the access_token and admin_token overridden:

client = OpenAI::Client.new(access_token: "access_token_goes_here", admin_token: "admin_token_goes_here")
Custom timeout or base URI
  • The default timeout for any request using this library is 120 seconds. You can change that by passing a number of seconds to the request_timeout when initializing the client.
  • You can also change the base URI used for all requests, eg. to use observability tools like Helicone or Velvet
  • You can also add arbitrary other headers e.g. for openai-caching-proxy-worker, eg.:
client = OpenAI::Client.new(
  access_token: "access_token_goes_here",
  uri_base: "https://oai.hconeai.com/",
  request_timeout: 240,
  extra_headers: {
    "X-Proxy-TTL" => "43200", # For https://github.com/6/openai-caching-proxy-worker#specifying-a-cache-ttl
    "X-Proxy-Refresh": "true", # For https://github.com/6/openai-caching-proxy-worker#refreshing-the-cache
    "Helicone-Auth": "Bearer HELICONE_API_KEY", # For https://docs.helicone.ai/getting-started/integration-method/openai-proxy
    "helicone-stream-force-format" => "true", # Use this with Helicone otherwise streaming drops chunks # https://github.com/alexrudall/ruby-openai/issues/251
  }
)

or when configuring the gem:

OpenAI.configure do |config|
  config.access_token = ENV.fetch("OPENAI_ACCESS_TOKEN")
  config.admin_token = ENV.fetch("OPENAI_ADMIN_TOKEN") # Optional, used for admin endpoints, created here: https://platform.openai.com/settings/organization/admin-keys
  config.organization_id = ENV.fetch("OPENAI_ORGANIZATION_ID") # Optional
  config.log_errors = true # Optional
  config.uri_base = "https://oai.hconeai.com/" # Optional
  config.request_timeout = 240 # Optional
  config.extra_headers = {
    "X-Proxy-TTL" => "43200", # For https://github.com/6/openai-caching-proxy-worker#specifying-a-cache-ttl
    "X-Proxy-Refresh": "true", # For https://github.com/6/openai-caching-proxy-worker#refreshing-the-cache
    "Helicone-Auth": "Bearer HELICONE_API_KEY" # For https://docs.helicone.a

readme truncated — read the full docs on github

Frequently asked questions

Is ruby-openai free to use?

ruby-openai is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does ruby-openai do?

OpenAI API + Ruby! 🤖❤️ GPT-5 & Realtime WebRTC compatible!

What is ruby-openai written in?

ruby-openai is primarily written in Ruby. Its source is publicly available at https://github.com/alexrudall/ruby-openai, and it has 3,224 GitHub stars.