Struct Client 

pub struct Client<E>
where
    E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static,
{
    pub http_client: Client,
    pub environment: E,
    pub diagnostics: Option<Arc<DiagnosticsCollector>>,
    pub cache: Option<Arc<ApiRequestCache>>,
    pub retry_config: Option<EnhancedRetryConfig>,
    pub circuit_breaker_config: Option<EnhancedCircuitBreakerConfig>,
    pub circuit_breaker: Option<EnhancedCircuitBreaker>,
    pub rate_limiting_config: Option<EnhancedRateLimitingConfig>,
    pub rate_limiter: Option<EnhancedRateLimiter>,
}

The main client for interacting with the OpenAI API.

Provides methods for accessing different API categories like assistants, chat, embeddings, etc.

Governing Principle : “Thin Client, Rich API”

This client follows the “Thin Client, Rich API” principle - it exposes all server-side functionality transparently while maintaining zero client-side intelligence or automatic behaviors. All operations are explicit and developer-controlled, with clear separation between information retrieval and state-changing actions.

Example

use api_openai::{ Client, environment::{ OpenaiEnvironmentImpl, OpenAIRecommended }, Secret, ClientApiAccessors };

let secret = Secret::load_from_env("OPENAI_API_KEY")?;
let env = OpenaiEnvironmentImpl::build(secret, None, None, OpenAIRecommended::base_url().to_string(), OpenAIRecommended::realtime_base_url().to_string())?;
let client = Client::build(env)?;

// Use the client to access different APIs
let models = client.models().list().await?;

Fields

http_client: Client

The HTTP client used for making requests.

environment: E

The OpenAI environment configuration.

diagnostics: Option<Arc<DiagnosticsCollector>>

Optional diagnostics collector for monitoring requests.

cache: Option<Arc<ApiRequestCache>>

Optional request cache for API responses.

retry_config: Option<EnhancedRetryConfig>

Optional retry configuration for reliability.

circuit_breaker_config: Option<EnhancedCircuitBreakerConfig>

Optional circuit breaker configuration for fault tolerance.

circuit_breaker: Option<EnhancedCircuitBreaker>

Optional circuit breaker instance.

rate_limiting_config: Option<EnhancedRateLimitingConfig>

Optional rate limiting configuration.

rate_limiter: Option<EnhancedRateLimiter>

Optional rate limiter instance.

Implementations

impl<E> Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static,

pub fn build(environment: E) -> Result<Self>

Creates a new Client instance.

Arguments

• environment: The OpenAI environment configuration.

Errors

Returns OpenAIError::InvalidArgument if the API key is invalid.

pub fn with_cache(self) -> Self

Enable request caching with default configuration.

pub fn with_cache_config(self, config: CacheConfig) -> Self

Enable request caching with custom configuration.

pub fn cache_statistics(&self) -> Option<&CacheStatistics>

Get cache statistics if caching is enabled.

pub async fn clear_cache(&self)

Clear the cache if caching is enabled.

pub fn with_retry(self) -> Self

Enable enhanced retry logic with default configuration. Only available when the retry feature is enabled.

pub fn with_retry_config(self, config: EnhancedRetryConfig) -> Self

Enable enhanced retry logic with custom configuration. Only available when the retry feature is enabled.

pub fn retry_config(&self) -> Option<&EnhancedRetryConfig>

Get retry configuration if enabled.

pub fn with_circuit_breaker(self) -> Self

Enable circuit breaker logic with default configuration. Only available when the circuit_breaker feature is enabled.

pub fn with_circuit_breaker_config( self, config: EnhancedCircuitBreakerConfig, ) -> Self

Enable circuit breaker logic with custom configuration. Only available when the circuit_breaker feature is enabled.

pub fn circuit_breaker_config(&self) -> Option<&EnhancedCircuitBreakerConfig>

Get circuit breaker configuration if enabled.

pub fn with_rate_limiting(self) -> Self

Enable rate limiting logic with default configuration. Only available when the rate_limiting feature is enabled.

pub fn with_rate_limiting_config( self, config: EnhancedRateLimitingConfig, ) -> Self

Enable rate limiting logic with custom configuration. Only available when the rate_limiting feature is enabled.

pub fn rate_limiting_config(&self) -> Option<&EnhancedRateLimitingConfig>

Get rate limiting configuration if enabled.

impl<E> Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static,

pub fn get_diagnostics(&self) -> Option<Arc<DiagnosticsCollector>>

Returns the diagnostics collector for monitoring requests.

Returns

• Some(DiagnosticsCollector) if diagnostics are enabled
• None if diagnostics are disabled

pub fn list_registered_tools(&self) -> Vec<&str>

Lists all registered custom tools.

Returns

An empty vector as custom tool registration is not yet implemented.

impl<E> Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static,

pub fn admin(&self) -> Admin<'_, E>

Access the administrative API

pub async fn list_organizations(&self) -> Result<Vec<Organization>>

List organizations (convenience method)

Errors

Returns an error if the API request fails or if the response cannot be parsed.

pub async fn get_organization(&self, org_id: &str) -> Result<Organization>

Get organization details (convenience method)

Errors

Returns an error if the API request fails, the organization is not found, or if the response cannot be parsed.

pub async fn list_users(&self, org_id: &str) -> Result<Vec<User>>

List users in organization (convenience method)

Errors

Returns an error if the API request fails, the organization is not found, insufficient permissions, or if the response cannot be parsed.

pub async fn list_projects(&self, org_id: Option<&str>) -> Result<Vec<Project>>

List projects (convenience method)

Errors

Returns an error if the API request fails, the organization is not found (when specified), insufficient permissions, or if the response cannot be parsed.

pub async fn create_project(&self, name: String) -> Result<Project>

Create project (convenience method)

Errors

Returns an error if the API request fails, invalid project name, insufficient permissions, or if the response cannot be parsed.

impl<E> Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static,

pub fn uploads(&self) -> Uploads<'_, E>

Access the uploads API

pub async fn upload_file<P: AsRef<Path>>( &self, file_path: P, purpose: &str, ) -> Result<FileObject>

Upload a file with default configuration

Errors

Returns OpenAIError if the file upload fails.

pub async fn list_files(&self, purpose: Option<&str>) -> Result<Vec<FileObject>>

List uploaded files

Errors

Returns OpenAIError if the request fails.

pub async fn get_file(&self, file_id: &str) -> Result<FileObject>

Get file information

Errors

Returns OpenAIError if the request fails.

pub async fn delete_file(&self, file_id: &str) -> Result<DeleteFileResponse>

Delete a file

Errors

Returns OpenAIError if the request fails.

pub async fn download_file(&self, file_id: &str) -> Result<Vec<u8>>

Download file content

Errors

Returns OpenAIError if the request fails.

impl<E> Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static,

pub fn enterprise(&self) -> EnterpriseClient<'_, E>

Access enterprise features

impl<E> Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static,

Extension trait for Client to add comparator method

pub fn comparator(&self) -> ModelComparator<'_, E>

Create a model comparator for A/B testing

Trait Implementations

impl<E> ClientApiAccessors<E> for Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static,

fn assistants(&self) -> Assistants<'_, E>

Returns an Assistants API client.

fn audio(&self) -> Audio<'_, E>

Returns an Audio API client.

fn chat(&self) -> Chat<'_, E>

Returns a Chat API client.

fn embeddings(&self) -> Embeddings<'_, E>

Returns an Embeddings API client.

fn files(&self) -> Files<'_, E>

Returns a Files API client.

fn fine_tuning(&self) -> FineTuning<'_, E>

Returns a FineTuning API client.

fn images(&self) -> Images<'_, E>

Returns an Images API client.

fn models(&self) -> Models<'_, E>

Returns a Models API client.

fn moderations(&self) -> Moderations<'_, E>

Returns a Moderations API client.

fn realtime(&self) -> Realtime<'_, E>

Returns a Realtime API client.

fn responses(&self) -> Responses<'_, E>

Returns a Responses API client.

fn vector_stores(&self) -> VectorStores<'_, E>

Returns a VectorStores API client.

impl<E> Clone for Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static + Clone,

fn clone(&self) -> Client<E>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<E> Debug for Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E> PlatformSpecificClient<E> for Client<E>

where E: OpenaiEnvironment + EnvironmentInterface + Send + Sync + 'static,

fn create_chat_completion_with_search<'life0, 'async_trait>( &'life0 self, _request: ChatCompletionRequest, _search_config: SearchGroundingConfig, ) -> Pin<Box<dyn Future<Output = Result<CreateChatCompletionResponse>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Creates a chat completion with search grounding integration.

fn search_and_ground<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _query: &'life1 str, _context: Option<&'life2 str>, _config: SearchGroundingConfig, ) -> Pin<Box<dyn Future<Output = Result<GroundedResponse>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Performs search grounding for a query with optional context.

fn execute_code<'life0, 'life1, 'async_trait>( &'life0 self, _code: &'life1 str, _config: CodeExecutionConfig, ) -> Pin<Box<dyn Future<Output = Result<CodeExecutionResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Executes code in a secure environment.

fn create_chat_completion_with_code_execution<'life0, 'async_trait>( &'life0 self, _request: ChatCompletionRequest, _execution_config: CodeExecutionConfig, ) -> Pin<Box<dyn Future<Output = Result<CreateChatCompletionResponse>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Creates a chat completion with code execution capabilities.

fn browse_url<'life0, 'life1, 'async_trait>( &'life0 self, _url: &'life1 str, _config: WebBrowsingConfig, ) -> Pin<Box<dyn Future<Output = Result<BrowsingResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Browses a URL and extracts content.

fn create_chat_completion_with_browsing<'life0, 'async_trait>( &'life0 self, _request: ChatCompletionRequest, _browsing_config: WebBrowsingConfig, ) -> Pin<Box<dyn Future<Output = Result<CreateChatCompletionResponse>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Creates a chat completion with web browsing capabilities.

fn generate_image<'life0, 'life1, 'async_trait>( &'life0 self, _prompt: &'life1 str, _config: ImageGenerationConfig, ) -> Pin<Box<dyn Future<Output = Result<ImageResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Generates an image from a prompt.