Skip to main content

​
Overview

The OpenAI Ruby client can be configured through environment variables or by passing parameters directly to the OpenAI::Client constructor. Environment variables provide a convenient way to manage configuration across different environments.

​
Environment Variables

The following environment variables are supported:
​
OPENAI_API_KEY
String
required
Your OpenAI API key. This is required to authenticate with the OpenAI API.
export OPENAI_API_KEY="sk-..."
If this environment variable is not set and no api_key parameter is provided, an ArgumentError will be raised.
​
OPENAI_ORG_ID
String
Your OpenAI organization ID for scoping API requests.
export OPENAI_ORG_ID="org-..."
​
OPENAI_PROJECT_ID
String
Your OpenAI project ID for scoping API requests.
export OPENAI_PROJECT_ID="proj-..."
​
OPENAI_WEBHOOK_SECRET
String
Your webhook secret for verifying webhook signatures.
export OPENAI_WEBHOOK_SECRET="whsec_..."
​
OPENAI_BASE_URL
String
Override the default base URL for the OpenAI API.Default: "https://api.openai.com/v1"
export OPENAI_BASE_URL="https://api.example.com/v1"
Useful for using a proxy, testing with a mock server, or connecting to alternative OpenAI-compatible endpoints.

​
Configuration Priority

When both environment variables and constructor parameters are provided, constructor parameters take precedence: 
# Environment variable is set
ENV["OPENAI_API_KEY"] = "sk-env-key"

# But parameter overrides it
client = OpenAI::Client.new(
  api_key: "sk-param-key"  # This value is used
)

​
Default Configuration Values

The following default values are used when parameters are not explicitly provided:
ParameterEnvironment VariableDefault ValueDescription
api_keyOPENAI_API_KEY(required)Your OpenAI API key
organizationOPENAI_ORG_IDnilOrganization ID
projectOPENAI_PROJECT_IDnilProject ID
webhook_secretOPENAI_WEBHOOK_SECRETnilWebhook secret
base_urlOPENAI_BASE_URL"https://api.openai.com/v1"API base URL
max_retries(none)2Maximum retry attempts
timeout(none)600.0Request timeout in seconds
initial_retry_delay(none)0.5Initial retry delay in seconds
max_retry_delay(none)8.0Maximum retry delay in seconds

​
Retry Configuration

The client implements automatic retries with exponential backoff and jitter for failed retryable requests: 
client = OpenAI::Client.new
# max_retries: 2
# initial_retry_delay: 0.5 seconds
# max_retry_delay: 8.0 seconds
# Exponential backoff with jitter
The retry delay grows exponentially with each retry attempt and includes random jitter to prevent thundering herd problems. The delay is capped at max_retry_delay.

​
Timeout Configuration

Control how long the client waits for API responses: 
client = OpenAI::Client.new
# timeout: 600.0 seconds (10 minutes)
The default timeout of 600 seconds is suitable for most API operations, including streaming responses. Adjust this value based on your specific use case.

​
Complete Configuration Example

# .env
OPENAI_API_KEY=sk-proj-...
OPENAI_ORG_ID=org-...
OPENAI_PROJECT_ID=proj-...
OPENAI_WEBHOOK_SECRET=whsec_...
OPENAI_BASE_URL=https://api.openai.com/v1

​
Best Practices

Security: Never hardcode API keys in your source code. Use environment variables or a secure credential management system.
Development vs Production: Use different API keys and organization IDs for development, staging, and production environments.
# config/initializers/openai.rb
RAILS_OPENAI_CLIENT = OpenAI::Client.new(
  api_key: Rails.application.credentials.dig(:openai, :api_key),
  organization: Rails.application.credentials.dig(:openai, :org_id),
  max_retries: Rails.env.production? ? 3 : 1,
  timeout: Rails.env.production? ? 600.0 : 30.0
)

Build docs developers (and LLMs) love

Get started for freeTalk to us