openai/openai-ruby

openai/openai-ruby

Description: Official Ruby SDK for the OpenAI API

Language: Ruby

License: Apache-2.0

Stars: 436

Forks: 49

Open issues: 19

Created: 2025-03-05T18:31:42Z

Pushed: 2026-06-10T16:12:29Z

Default branch: main

Fork: no

Archived: no

README:

OpenAI Ruby API library

The OpenAI Ruby library provides convenient access to the OpenAI REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – see below for usage with Sorbet. The standard library's net/http is used as the HTTP transport, with connection pooling via the connection_pool gem.

Documentation

Documentation for releases of this gem can be found on RubyDoc.

The REST API documentation can be found on platform.openai.com.

Installation

To use this gem, install via Bundler by adding the following to your application's Gemfile:

gem "openai", "~> 0.66.1"

Usage

require "bundler/setup"
require "openai"

openai = OpenAI::Client.new(
api_key: ENV["OPENAI_API_KEY"] # This is the default and can be omitted
)

chat_completion = openai.chat.completions.create(messages: [{role: "user", content: "Say this is a test"}], model: "gpt-5.2")

puts(chat_completion)

Streaming

We provide support for streaming responses using Server-Sent Events (SSE).

stream = openai.responses.stream(
input: "Write a haiku about OpenAI.",
model: "gpt-5.2"
)

stream.each do |event|
puts(event.type)
end

Pagination

List methods in the OpenAI API are paginated.

This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:

page = openai.fine_tuning.jobs.list(limit: 20)

# Fetch single item from page.
job = page.data[0]
puts(job.id)

# Automatically fetches more pages as needed.
page.auto_paging_each do |job|
puts(job.id)
end

Alternatively, you can use the #next_page? and #next_page methods for more granular control working with pages.

if page.next_page?
new_page = page.next_page
puts(new_page.data[0].id)
end

File uploads

Request parameters that correspond to file uploads can be passed as raw contents, a `Pathname` instance, `StringIO`, or more.

require "pathname"

# Use `Pathname` to send the filename and/or avoid paging a large file into memory:
file_object = openai.files.create(file: Pathname("input.jsonl"), purpose: "fine-tune")

# Alternatively, pass file contents or a `StringIO` directly:
file_object = openai.files.create(file: File.read("input.jsonl"), purpose: "fine-tune")

puts(file_object.id)

# Or, to control the filename and/or content type:
image = OpenAI::FilePart.new(Pathname('dog.jpg'), content_type: 'image/jpeg')
edited = openai.images.edit(
prompt: "make this image look like a painting",
model: "gpt-image-1",
size: '1024x1024',
image: image
)

puts(edited.data.first)

Note that you can also pass a raw IO descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).

Workload Identity Authentication

For secure, automated environments like cloud-managed Kubernetes, Azure, and GCP, you can use workload identity authentication with short-lived tokens from cloud identity providers instead of long-lived API keys.

client_id remains available as an optional parameter for token exchange setups that require an explicit OAuth client ID.

Kubernetes Service Account

require "openai"

# Configure Kubernetes service account provider
provider = OpenAI::Auth::SubjectTokenProviders::K8sServiceAccountTokenProvider.new

workload_identity = OpenAI::Auth::WorkloadIdentity.new(
identity_provider_id: ENV["IDENTITY_PROVIDER_ID"], # This is the default and can be omitted
service_account_id: ENV["SERVICE_ACCOUNT_ID"], # This is the default and can be omitted
provider: provider
)

client = OpenAI::Client.new(
workload_identity: workload_identity,
)

response = client.chat.completions.create(
messages: [{role: "user", content: "Hello!"}],
model: "gpt-5.2"
)

Azure Managed Identity

provider = OpenAI::Auth::SubjectTokenProviders::AzureManagedIdentityTokenProvider.new

workload_identity = OpenAI::Auth::WorkloadIdentity.new(
identity_provider_id: ENV["IDENTITY_PROVIDER_ID"], # This is the default and can be omitted
service_account_id: ENV["SERVICE_ACCOUNT_ID"], # This is the default and can be omitted
provider: provider
)

client = OpenAI::Client.new(
workload_identity: workload_identity,
)

GCP Metadata Server

provider = OpenAI::Auth::SubjectTokenProviders::GCPIDTokenProvider.new

workload_identity = OpenAI::Auth::WorkloadIdentity.new(
identity_provider_id: ENV["IDENTITY_PROVIDER_ID"], # This is the default and can be omitted
service_account_id: ENV["SERVICE_ACCOUNT_ID"], # This is the default and can be omitted
provider: provider
)

client = OpenAI::Client.new(
workload_identity: workload_identity,
)

Custom Token Providers

You can implement custom token providers by including the OpenAI::Auth::SubjectTokenProvider module:

class CustomProvider
include OpenAI::Auth::SubjectTokenProvider

def token_type
OpenAI::Auth::TokenType::JWT
end

def get_token
"custom-token"
end
end

provider = CustomProvider.new

workload_identity = OpenAI::Auth::WorkloadIdentity.new(
identity_provider_id: ENV["IDENTITY_PROVIDER_ID"], # This is the default and can be omitted
service_account_id: ENV["SERVICE_ACCOUNT_ID"], # This is the default and can be omitted
provider: provider
)

client = OpenAI::Client.new(
workload_identity: workload_identity,
organization: ENV["OPENAI_ORG_ID"],
project: ENV["OPENAI_PROJECT_ID"]
)

Webhook Verification

Verifying webhook signatures is _optional but encouraged_.

For more information about webhooks, see the API docs.

Parsing webhook payloads

For most use cases, you will likely want to verify the webhook and parse the payload at the same time. To achieve this, we provide the method client.webhooks.unwrap, which parses a webhook request and verifies that it was sent by OpenAI. This method will raise an error if the signature is invalid.

Note that the body parameter must be the raw JSON string sent from the…