OpenAI Tools

API Wrapper for OpenAI API.

Installation

To start using the openai-tools, add it to your projects's dependencies in the `Cargo.toml' file:

cargo add openai-tools

Quick Example

use openai_tools::chat::request::ChatCompletion;
use openai_tools::common::{message::Message, role::Role, models::ChatModel};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let response = ChatCompletion::new()
        .model(ChatModel::Gpt4oMini)
        .messages(vec![Message::from_string(Role::User, "Hello!")])
        .chat()
        .await?;

    println!("{:?}", response.choices[0].message.content);
    Ok(())
}

Environment Setup

OpenAI API

Set the API key in the .env file:

OPENAI_API_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxx"

Azure OpenAI API

Set Azure-specific environment variables:

AZURE_OPENAI_API_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
AZURE_OPENAI_BASE_URL = "https://my-resource.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview"

Note: Each API (Chat, Embedding, etc.) requires its own complete endpoint URL including the API path.

Provider Detection

All API clients support multiple ways to configure authentication:

use openai_tools::chat::request::ChatCompletion;
use openai_tools::common::auth::{AuthProvider, AzureAuth};

// OpenAI (default)
let chat = ChatCompletion::new();

// Azure (from environment variables)
let chat = ChatCompletion::azure()?;

// Auto-detect provider from environment variables
let chat = ChatCompletion::detect_provider()?;

// URL-based detection (auto-detects provider from URL pattern)
// *.openai.azure.com → Azure, all other URLs → OpenAI-compatible
let chat = ChatCompletion::with_url(
    "https://my-resource.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview",
    "azure-key",
);

// OpenAI-compatible APIs (Ollama, vLLM, LocalAI, etc.)
let chat = ChatCompletion::with_url(
    "http://localhost:11434/v1",
    "ollama",
);

// Explicit Azure auth configuration
let auth = AuthProvider::Azure(
    AzureAuth::new(
        "api-key",
        "https://my-resource.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview"
    )
);
let chat = ChatCompletion::with_auth(auth);

Modules

Import the necessary modules in your code:

use openai_tools::chat::ChatCompletion;
use openai_tools::responses::Responses;
use openai_tools::embedding::Embedding;
use openai_tools::realtime::RealtimeClient;
use openai_tools::conversations::Conversations;
use openai_tools::models::Models;
use openai_tools::files::Files;
use openai_tools::moderations::Moderations;
use openai_tools::images::Images;
use openai_tools::audio::Audio;
use openai_tools::batch::Batches;
use openai_tools::fine_tuning::FineTuning;

Supported APIs

Chat Completions API

use openai_tools::chat::request::ChatCompletion;
use openai_tools::common::message::Message;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let messages = vec![Message::from_string("user", "Hello!")];

    let mut chat = ChatCompletion::new();
    let response = chat
        .model_id("gpt-4o-mini")
        .messages(messages)
        .temperature(0.7)
        .chat()
        .await?;

    println!("{}", response.choices[0].message.content);
    Ok(())
}

Responses API

use openai_tools::responses::request::Responses;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = Responses::new();
    let response = client
        .model_id("gpt-4o")
        .str_message("What is the capital of France?")
        .complete()
        .await?;

    println!("{}", response.output_text());
    Ok(())
}

Responses API CRUD Operations

use openai_tools::responses::request::{Responses, ToolChoice, ToolChoiceMode};
use openai_tools::common::models::ChatModel;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = Responses::new();

    // Create a response with tool_choice and prompt caching
    client.model(ChatModel::Gpt4oMini)
        .str_message("Hello!")
        .tool_choice(ToolChoice::Simple(ToolChoiceMode::Auto))
        .prompt_cache_key("my-cache-key")
        .store(true);

    let response = client.complete().await?;
    let response_id = response.id.as_ref().unwrap();

    // Retrieve a stored response
    let retrieved = client.retrieve(response_id).await?;

    // List input items with pagination
    let items = client.list_input_items(response_id, Some(10), None, None).await?;

    // Count input tokens before sending a request
    let tokens = client.get_input_tokens("gpt-4o-mini", serde_json::json!("Hello!")).await?;
    println!("Input tokens: {}", tokens.input_tokens);

    // Delete a response when done
    client.delete(response_id).await?;

    Ok(())
}

Conversations API

Manage long-running conversations with the Responses API:

use openai_tools::conversations::request::Conversations;
use openai_tools::conversations::response::InputItem;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conversations = Conversations::new()?;

    // Create a conversation with metadata
    let mut metadata = HashMap::new();
    metadata.insert("user_id".to_string(), "user123".to_string());

    let conv = conversations.create(Some(metadata), None).await?;
    println!("Created conversation: {}", conv.id);

    // Add items to the conversation
    let items = vec![InputItem::user_message("Hello!")];
    conversations.create_items(&conv.id, items).await?;

    // List conversation items
    let items = conversations.list_items(&conv.id, Some(10), None, None, None).await?;
    for item in &items.data {
        println!("Item: {} ({})", item.id, item.item_type);
    }

    // Delete conversation when done
    conversations.delete(&conv.id).await?;

    Ok(())
}

Realtime API

Real-time audio and text communication with GPT-4o models through WebSocket:

use openai_tools::realtime::{RealtimeClient, Modality, Voice};
use openai_tools::realtime::events::server::ServerEvent;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = RealtimeClient::new();
    client
        .model("gpt-4o-realtime-preview")
        .modalities(vec![Modality::Text, Modality::Audio])
        .voice(Voice::Alloy)
        .instructions("You are a helpful assistant.");

    let mut session = client.connect().await?;

    // Send a text message
    session.send_text("Hello!").await?;
    session.create_response(None).await?;

    // Process events
    while let Some(event) = session.recv().await? {
        match event {
            ServerEvent::ResponseTextDelta(e) => print!("{}", e.delta),
            ServerEvent::ResponseDone(_) => break,
            _ => {}
        }
    }

    session.close().await?;
    Ok(())
}

Models API

List and retrieve available models:

use openai_tools::models::request::Models;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let models = Models::new()?;

    // List all models
    let response = models.list().await?;
    for model in &response.data {
        println!("{}: owned by {}", model.id, model.owned_by);
    }

    // Retrieve a specific model
    let model = models.retrieve("gpt-4o-mini").await?;
    println!("Model: {}", model.id);

    Ok(())
}

Files API

Upload, manage, and retrieve files:

use openai_tools::files::request::Files;
use openai_tools::files::response::FilePurpose;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let files = Files::new()?;

    // Upload a file for fine-tuning
    let file = files.upload_path("training.jsonl", FilePurpose::FineTune).await?;
    println!("Uploaded: {}", file.id);

    // List files
    let response = files.list(None).await?;
    for file in &response.data {
        println!("{}: {} bytes", file.filename, file.bytes);
    }

    // Delete file
    files.delete(&file.id).await?;

    Ok(())
}

Moderations API

Check content for policy violations:

use openai_tools::moderations::request::Moderations;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let moderations = Moderations::new()?;

    // Check a single text
    let response = moderations.moderate_text("Hello, world!", None).await?;
    if response.results[0].flagged {
        println!("Content was flagged!");
    } else {
        println!("Content is safe.");
    }

    // Check multiple texts at once
    let texts = vec!["Text 1".to_string(), "Text 2".to_string()];
    let response = moderations.moderate_texts(texts, None).await?;

    Ok(())
}

Images API (DALL-E)

Generate images with DALL-E:

use openai_tools::images::request::{Images, GenerateOptions, ImageModel, ImageSize, ImageQuality};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let images = Images::new()?;

    // Generate an image
    let options = GenerateOptions {
        model: Some(ImageModel::DallE3),
        size: Some(ImageSize::Size1024x1024),
        quality: Some(ImageQuality::Hd),
        ..Default::default()
    };
    let response = images.generate("A sunset over mountains", options).await?;
    println!("Image URL: {:?}", response.data[0].url);

    Ok(())
}

Audio API

Text-to-speech and transcription:

use openai_tools::audio::request::{Audio, TtsOptions, TranscribeOptions};
use openai_tools::audio::response::{TtsModel, Voice};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let audio = Audio::new()?;

    // Text-to-speech
    let options = TtsOptions {
        model: TtsModel::Tts1Hd,
        voice: Voice::Nova,
        ..Default::default()
    };
    let bytes = audio.text_to_speech("Hello!", options).await?;
    std::fs::write("hello.mp3", bytes)?;

    // Transcribe audio
    let options = TranscribeOptions {
        language: Some("en".to_string()),
        ..Default::default()
    };
    let response = audio.transcribe("audio.mp3", options).await?;
    println!("Transcript: {}", response.text);

    Ok(())
}

Batch API

Process large volumes of requests asynchronously with 50% cost savings:

use openai_tools::batch::request::{Batches, CreateBatchRequest, BatchEndpoint};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let batches = Batches::new()?;

    // List all batches
    let response = batches.list(Some(20), None).await?;
    for batch in &response.data {
        println!("Batch: {} - {:?}", batch.id, batch.status);
    }

    // Create a batch job (input file must be uploaded via Files API with purpose "batch")
    let request = CreateBatchRequest::new("file-abc123", BatchEndpoint::ChatCompletions);
    let batch = batches.create(request).await?;
    println!("Created batch: {}", batch.id);

    Ok(())
}

Fine-tuning API

Customize models with your training data:

use openai_tools::fine_tuning::request::{FineTuning, CreateFineTuningJobRequest};
use openai_tools::fine_tuning::response::Hyperparameters;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let fine_tuning = FineTuning::new()?;

    // List fine-tuning jobs
    let response = fine_tuning.list(Some(10), None).await?;
    for job in &response.data {
        println!("Job: {} - {:?}", job.id, job.status);
    }

    // Create a fine-tuning job
    let hyperparams = Hyperparameters {
        n_epochs: Some(3),
        ..Default::default()
    };
    let request = CreateFineTuningJobRequest::new("gpt-4o-mini-2024-07-18", "file-abc123")
        .with_suffix("my-model")
        .with_supervised_method(Some(hyperparams));

    let job = fine_tuning.create(request).await?;
    println!("Created job: {}", job.id);

    Ok(())
}

Embedding API

use openai_tools::embedding::request::Embedding;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut embedding = Embedding::new();
    let response = embedding
        .model("text-embedding-3-small")
        .input_text("Hello, world!")
        .embed()
        .await?;

    println!("Embedding dimensions: {}", response.data[0].embedding.as_1d().unwrap().len());
    Ok(())
}

Update History

• Added 88 comprehensive model-specific parameter validation tests
  • Chat API: 30 tests for parameter restrictions across model generations (GPT-5, o-series, standard models)
  • Responses API: 32 tests for temperature, top_p, top_logprobs validation
  • Models: 26 tests for reasoning model detection and ParameterSupport/ParameterRestriction types
• Fixed Responses API integration test assertions (max_output_tokens minimum, JSON formatting)
• Updated documentation to recommend cargo nextest run for test execution

• Breaking Change: Simplified AzureAuth to accept complete endpoint URL
  • AzureAuth::new(api_key, base_url) - simple 2-argument constructor
  • base_url must be the complete endpoint URL including API path (e.g., /chat/completions)
  • endpoint() method now returns base_url as-is (path parameter is ignored)
  • Removed resource_name, deployment_name, api_version fields
  • Removed use_entra_id, with_entra_id(), is_entra_id() (Entra ID support removed)
• Breaking Change: Updated with_url() method signature
  • Changed from with_url(url, api_key, deployment_name) to with_url(url, api_key)
• Environment variable changes:
  • Use AZURE_OPENAI_BASE_URL (complete endpoint URL) instead of separate resource/deployment vars
  • Removed AZURE_OPENAI_TOKEN (Entra ID token support removed)

• Added URL-based provider detection for all API clients
  • with_url(url, api_key, deployment_name) - auto-detect provider from URL pattern
  • from_url(url) - auto-detect with env var credentials
  • *.openai.azure.com → Azure, all other URLs → OpenAI-compatible
• Support for OpenAI-compatible APIs (Ollama, vLLM, LocalAI, etc.)
• Added Azure OpenAI support with azure() and environment variable configuration
• Added AuthProvider abstraction for unified authentication handling

• Added automatic handling for reasoning model (o1, o3 series) parameter restrictions
  • Chat API: temperature, frequency_penalty, presence_penalty, logprobs, top_logprobs, logit_bias, n
  • Responses API: temperature, top_p, top_logprobs
• Unsupported parameters are automatically ignored with tracing::warn! warnings
• Added "Model-Specific Parameter Restrictions" documentation section

• Initial release with all OpenAI APIs:
  • Chat Completions API
  • Responses API
  • Conversations API
  • Embedding API
  • Realtime API (WebSocket)
  • Models API
  • Files API
  • Moderations API
  • Images API (DALL-E)
  • Audio API (TTS, STT)
  • Batch API
  • Fine-tuning API

License

MIT License