Skip to main content

​
Overview

The OpenAI::Client class is the primary entry point for interacting with the OpenAI API. It handles authentication, request configuration, and provides access to all API resources.

​
Basic Usage

client = OpenAI::Client.new(
  api_key: "your-api-key"
)

​
Parameters

​
api_key
String
required
Your OpenAI API key. This parameter is required.Default: ENV["OPENAI_API_KEY"]
If not provided and the environment variable is not set, an ArgumentError will be raised.
​
organization
String
Your OpenAI organization ID. Used for scoping API requests to a specific organization.Default: ENV["OPENAI_ORG_ID"]This value is sent in the openai-organization header with each request.
​
project
String
Your OpenAI project ID. Used for scoping API requests to a specific project.Default: ENV["OPENAI_PROJECT_ID"]This value is sent in the openai-project header with each request.
​
webhook_secret
String
Your webhook secret for verifying webhook signatures.Default: ENV["OPENAI_WEBHOOK_SECRET"]
​
base_url
String
Override the default base URL for the API. Useful for testing or using alternative endpoints.Default: ENV["OPENAI_BASE_URL"] or "https://api.openai.com/v1"
Example: "https://api.example.com/v2/"
​
max_retries
Integer
Maximum number of retries to attempt after a failed retryable request.Default: 2 (OpenAI::Client::DEFAULT_MAX_RETRIES)
​
timeout
Float
Per-request timeout in seconds.Default: 600.0 (OpenAI::Client::DEFAULT_TIMEOUT_IN_SECONDS)
​
initial_retry_delay
Float
Initial retry delay in seconds. Overall delay is calculated using exponential backoff plus jitter.Default: 0.5 (OpenAI::Client::DEFAULT_INITIAL_RETRY_DELAY)
​
max_retry_delay
Float
Maximum retry delay in seconds.Default: 8.0 (OpenAI::Client::DEFAULT_MAX_RETRY_DELAY)

​
Constants

The OpenAI::Client class defines the following constants for default configuration values: 
OpenAI::Client::DEFAULT_MAX_RETRIES # => 2
OpenAI::Client::DEFAULT_TIMEOUT_IN_SECONDS # => 600.0
OpenAI::Client::DEFAULT_INITIAL_RETRY_DELAY # => 0.5
OpenAI::Client::DEFAULT_MAX_RETRY_DELAY # => 8.0
ConstantValueDescription
DEFAULT_MAX_RETRIES2Default max number of retries to attempt after a failed retryable request
DEFAULT_TIMEOUT_IN_SECONDS600.0Default per-request timeout
DEFAULT_INITIAL_RETRY_DELAY0.5Default initial retry delay in seconds (used with exponential backoff + jitter)
DEFAULT_MAX_RETRY_DELAY8.0Default max retry delay in seconds

​
Available Resources

Once initialized, the client provides access to the following resource namespaces: 
client.completions      # Text completions
client.chat             # Chat completions
client.embeddings       # Embeddings
client.files            # File management
client.images           # Image generation
client.audio            # Audio transcription and generation
client.moderations      # Content moderation
client.models           # Model information
client.fine_tuning      # Fine-tuning jobs
client.graders          # Graders
client.vector_stores    # Vector stores
client.webhooks         # Webhook management
client.beta             # Beta features (assistants, threads)
client.batches          # Batch API
client.uploads          # File uploads
client.responses        # Responses
client.realtime         # Realtime API
client.conversations    # Conversations
client.evals            # Evaluations
client.containers       # Containers
client.skills           # Skills
client.videos           # Video generation

​
Error Handling

If the api_key is not provided (either as a parameter or via the OPENAI_API_KEY environment variable), an ArgumentError will be raised:
ArgumentError: api_key is required, and can be set via environ: "OPENAI_API_KEY"

​
Examples

# Set environment variables
ENV["OPENAI_API_KEY"] = "sk-..."
ENV["OPENAI_ORG_ID"] = "org-..."

# Client will use environment variables automatically
client = OpenAI::Client.new

Build docs developers (and LLMs) love

Get started for freeTalk to us