Struct Responses

Source

pub struct Responses {
    pub request_body: Body,
    /* private fields */
}

Expand description

Client for making requests to the OpenAI Responses API

This struct provides a convenient interface for building and executing requests to the OpenAI Responses API and Azure OpenAI API. It handles authentication, request formatting, and response parsing automatically.

§Providers

The client supports two providers:

OpenAI: Standard OpenAI API (default)
Azure: Azure OpenAI Service

§Examples

§OpenAI (existing behavior - unchanged)

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

let mut client = Responses::new();
let response = client
    .model_id("gpt-4")
    .instructions("You are a helpful assistant.")
    .str_message("Hello, how are you?")
    .complete()
    .await?;

§Azure OpenAI

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

let mut client = Responses::azure()?;
let response = client
    .str_message("Hello!")
    .complete()
    .await?;

Fields§

§request_body: Body

The request body containing all parameters for the API call

Implementations§

Source §

impl Responses

Source

pub fn new() -> Self

Creates a new instance of the Responses client for OpenAI API

This method initializes a new client by loading the OpenAI API key from the OPENAI_API_KEY environment variable. Make sure to set this environment variable before calling this method.

§Panics

Panics if the OPENAI_API_KEY environment variable is not set.

Source

pub fn from_endpoint<T: AsRef<str>>(endpoint: T) -> Self

👎Deprecated since 0.3.0: Use with_auth() with custom OpenAIAuth for custom endpoints

Creates a new instance of the Responses client with a custom endpoint

Source

pub fn with_model(model: ChatModel) -> Self

Creates a new Responses client with a specified model.

This is the recommended constructor as it enables parameter validation at setter time. When you set parameters like temperature() or top_p(), the model’s parameter support is checked and warnings are logged for unsupported values.

§Arguments

model - The model to use for response generation

§Panics

Panics if the OPENAI_API_KEY environment variable is not set.

§Returns

A new Responses instance with the specified model

§Example

use openai_tools::responses::request::Responses;
use openai_tools::common::models::ChatModel;

// Recommended: specify model at creation time
let mut responses = Responses::with_model(ChatModel::Gpt4oMini);

// For reasoning models, unsupported parameters are validated at setter time
let mut reasoning_responses = Responses::with_model(ChatModel::O3Mini);
reasoning_responses.temperature(0.5); // Warning logged, value ignored

Source

pub fn with_auth(auth: AuthProvider) -> Self

Creates a new Responses client with a custom authentication provider

Use this to explicitly configure OpenAI or Azure authentication.

§Arguments

auth - The authentication provider

§Returns

A new Responses instance with the specified auth provider

§Example

use openai_tools::responses::request::Responses;
use openai_tools::common::auth::{AuthProvider, AzureAuth};

// Explicit Azure configuration with complete base URL
let auth = AuthProvider::Azure(
    AzureAuth::new(
        "api-key",
        "https://my-resource.openai.azure.com/openai/deployments/gpt-4o?api-version=2024-08-01-preview"
    )
);
let mut responses = Responses::with_auth(auth);

Source

pub fn azure() -> Result<Self>

Creates a new Responses client for Azure OpenAI API

Loads configuration from Azure-specific environment variables.

§Returns

Result<Responses> - Configured for Azure or error if env vars missing

§Environment Variables

Variable	Required	Description
`AZURE_OPENAI_API_KEY`	Yes	Azure API key
`AZURE_OPENAI_BASE_URL`	Yes	Complete endpoint URL including deployment, API path, and api-version

§Example

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

// With environment variables:
// AZURE_OPENAI_API_KEY=xxx
// AZURE_OPENAI_BASE_URL=https://my-resource.openai.azure.com/openai/deployments/gpt-4o/responses?api-version=2024-08-01-preview
let mut responses = Responses::azure()?;

Source

pub fn detect_provider() -> Result<Self>

Creates a new Responses client by auto-detecting the provider

Tries Azure first (if AZURE_OPENAI_API_KEY is set), then falls back to OpenAI.

§Returns

Result<Responses> - Auto-configured client or error

§Example

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

// Uses Azure if AZURE_OPENAI_API_KEY is set, otherwise OpenAI
let mut responses = Responses::detect_provider()?;

Source

pub fn with_url<S: Into<String>>(base_url: S, api_key: S) -> Self

Creates a new Responses instance with URL-based provider detection

Analyzes the URL pattern to determine the provider:

URLs containing .openai.azure.com → Azure
All other URLs → OpenAI-compatible

§Arguments

base_url - The complete base URL for API requests
api_key - The API key or token

Source

pub fn from_url<S: Into<String>>(url: S) -> Result<Self>

Creates a new Responses instance from URL using environment variables

Analyzes the URL pattern to determine the provider, then loads credentials from the appropriate environment variables.

Source

pub fn auth(&self) -> &AuthProvider

Returns the authentication provider

§Returns

Reference to the authentication provider

Source

pub fn base_url<T: AsRef<str>>(&mut self, url: T) -> &mut Self

Sets a custom API endpoint URL (OpenAI only)

Use this to point to alternative OpenAI-compatible APIs (e.g., proxy servers). For Azure, use azure() or with_auth() instead.

§Arguments

url - The base URL (e.g., “https://my-proxy.example.com/v1”)

§Returns

A mutable reference to self for method chaining

§Note

This method only works with OpenAI authentication. For Azure, the endpoint is constructed from resource name and deployment name.

§Example

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

let mut responses = Responses::new();
responses.base_url("https://my-proxy.example.com/v1");

Source

pub fn model(&mut self, model: ChatModel) -> &mut Self

Sets the model for the request.

§Arguments

model - The model to use (e.g., ChatModel::Gpt4oMini, ChatModel::Gpt4o)

§Returns

A mutable reference to self for method chaining

§Example

use openai_tools::responses::request::Responses;
use openai_tools::common::models::ChatModel;

let mut responses = Responses::new();
responses.model(ChatModel::Gpt4oMini);

Source

pub fn model_id<T: AsRef<str>>(&mut self, model_id: T) -> &mut Self

👎Deprecated since 0.2.0: Use model(ChatModel) instead for type safety

Sets the model using a string ID (for backward compatibility).

Prefer using [model] with ChatModel enum for type safety.

§Arguments

model_id - The ID of the model to use (e.g., “gpt-4o-mini”)

§Returns

A mutable reference to self for method chaining

Source

pub fn timeout(&mut self, timeout: Duration) -> &mut Self

Sets the request timeout duration

§Arguments

timeout - The maximum time to wait for a response

§Returns

A mutable reference to self for method chaining

§Example

use std::time::Duration;
use openai_tools::responses::request::Responses;

let mut responses = Responses::new();
responses.model_id("gpt-4o")
    .timeout(Duration::from_secs(30));

Source

pub fn user_agent<T: AsRef<str>>(&mut self, user_agent: T) -> &mut Self

Sets the User-Agent string for the request

§Arguments

user_agent - The User-Agent string to include in the request headers

§Returns

A mutable reference to self for method chaining

Source

pub fn instructions<T: AsRef<str>>(&mut self, instructions: T) -> &mut Self

Sets instructions to guide the model’s behavior

§Arguments

instructions - Instructions that define how the model should behave

§Returns

A mutable reference to self for method chaining

Source

pub fn str_message<T: AsRef<str>>(&mut self, input: T) -> &mut Self

Sets plain text input for simple text-based requests

This method is mutually exclusive with messages(). Use this for simple text-based interactions where you don’t need conversation history.

§Arguments

input - The plain text input to send to the model

§Returns

A mutable reference to self for method chaining

Source

pub fn messages(&mut self, messages: Vec<Message>) -> &mut Self

Sets structured message input for conversation-style interactions

This method is mutually exclusive with plain_text_input(). Use this for complex conversations with message history and different roles.

§Arguments

messages - A vector of messages representing the conversation history

§Returns

A mutable reference to self for method chaining

Source

pub fn tools(&mut self, tools: Vec<Tool>) -> &mut Self

Sets tools that the model can use during response generation

§Arguments

tools - A vector of tools available to the model

§Returns

A mutable reference to self for method chaining

Source

pub fn tool_choice(&mut self, tool_choice: ToolChoice) -> &mut Self

Sets the tool choice configuration

Controls how the model selects which tool to use when tools are available. Can be set to auto (let model decide), none (no tools), required (must use tools), or a specific function name to force calling that function.

§Arguments

tool_choice - The tool choice configuration

§Returns

A mutable reference to self for method chaining

§Examples

use openai_tools::responses::request::{Responses, ToolChoice, ToolChoiceMode, NamedFunctionChoice};

let mut client = Responses::new();

// Let the model decide
client.tool_choice(ToolChoice::Simple(ToolChoiceMode::Auto));

// Force a specific function
client.tool_choice(ToolChoice::Function(NamedFunctionChoice::new("get_weather")));

Source

pub fn prompt(&mut self, prompt: Prompt) -> &mut Self

Sets a prompt template reference

Allows you to use pre-defined prompt templates stored in the OpenAI platform, optionally with variable substitution.

§Arguments

prompt - The prompt template reference

§Returns

A mutable reference to self for method chaining

§Examples

use openai_tools::responses::request::{Responses, Prompt};
use std::collections::HashMap;

let mut client = Responses::new();

// Simple prompt reference
client.prompt(Prompt::new("prompt-abc123"));

// Prompt with variables
let mut vars = HashMap::new();
vars.insert("name".to_string(), "Alice".to_string());
client.prompt(Prompt::with_variables("prompt-abc123", vars));

Source

pub fn prompt_cache_key<T: AsRef<str>>(&mut self, key: T) -> &mut Self

Sets the prompt cache key for caching

A unique key to use for prompt caching. When provided, the same prompt will be cached and reused for subsequent requests with the same cache key.

§Arguments

key - The cache key to use

§Returns

A mutable reference to self for method chaining

§Examples

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

let mut client = Responses::new();
client.prompt_cache_key("my-cache-key");

Source

pub fn prompt_cache_retention<T: AsRef<str>>( &mut self, retention: T, ) -> &mut Self

Sets the prompt cache retention duration

Controls how long cached prompts should be retained.

§Arguments

retention - The retention duration string (e.g., “1h”, “24h”, “7d”)

§Returns

A mutable reference to self for method chaining

§Examples

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

let mut client = Responses::new();
client.prompt_cache_retention("24h");

Source

pub fn structured_output(&mut self, text_format: Schema) -> &mut Self

Sets structured output format specification

This allows you to specify the exact format and structure of the model’s response output.

§Arguments

text_format - The schema defining the expected output structure

§Returns

A mutable reference to self for method chaining

Source

pub fn temperature(&mut self, temperature: f64) -> &mut Self

Sets the sampling temperature for controlling response randomness

Controls the randomness and creativity of the model’s responses. Higher values make the output more random and creative, while lower values make it more focused and deterministic.

§Arguments

temperature - The temperature value (0.0 to 2.0)
- 0.0: Most deterministic and focused responses
- 1.0: Default balanced behavior
- 2.0: Most random and creative responses

Note: Reasoning models (GPT-5, o-series) only support temperature=1.0. For these models, other values will be ignored with a warning.

§Panics

This method will panic if the temperature value is outside the valid range of 0.0 to 2.0, as this would result in an API error.

§Returns

A mutable reference to self for method chaining

§Examples

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

// Deterministic responses for factual queries
let mut client = Responses::new();
client.temperature(0.2);

// Creative responses for brainstorming
let mut client = Responses::new();
client.temperature(1.1);

Source

pub fn max_output_tokens(&mut self, max_tokens: usize) -> &mut Self

Sets the maximum number of tokens to generate in the response

Controls the maximum length of the generated response. The actual response may be shorter if the model naturally concludes or hits other stopping conditions.

§Arguments

max_tokens - Maximum number of tokens to generate (minimum: 1)

§Returns

A mutable reference to self for method chaining

§Examples

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

let mut client = Responses::new();
client.max_output_tokens(100);  // Limit response to 100 tokens

Source

pub fn max_tool_calls(&mut self, max_tokens: usize) -> &mut Self

Sets the maximum number of tool calls allowed during response generation

Limits how many tools the model can invoke during response generation. This helps control cost and response time when using multiple tools.

§Arguments

max_tokens - Maximum number of tool calls allowed (0 = no tool calls)

§Returns

A mutable reference to self for method chaining

§Examples

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

let mut client = Responses::new();
client.max_tool_calls(3);  // Allow up to 3 tool calls
client.max_tool_calls(0);  // Disable tool usage

Source

pub fn metadata(&mut self, key: String, value: Value) -> &mut Self

Adds or updates a metadata key-value pair for the request

Metadata provides arbitrary key-value pairs that can be attached to the request for tracking, logging, or passing additional context that doesn’t affect the model’s behavior.

§Arguments

key - The metadata key (string identifier)
value - The metadata value (can be string, number, boolean, etc.)

§Behavior

If the key already exists, the old value is replaced with the new one
If metadata doesn’t exist yet, a new metadata map is created
Values are stored as serde_json::Value for flexibility

§Returns

A mutable reference to self for method chaining

§Examples

use openai_tools::responses::request::Responses;
use serde_json::Value;

let mut client = Responses::new();
client.metadata("user_id".to_string(), Value::String("user123".to_string()));
client.metadata("priority".to_string(), Value::Number(serde_json::Number::from(1)));
client.metadata("debug".to_string(), Value::Bool(true));

Source

pub fn parallel_tool_calls(&mut self, enable: bool) -> &mut Self

Enables or disables parallel tool calls

When enabled, the model can make multiple tool calls simultaneously rather than sequentially. This can significantly improve response time when multiple independent tools need to be used.

§Arguments

enable - Whether to enable parallel tool calls
- true: Tools can be called in parallel (faster for independent tools)
- false: Tools are called sequentially (better for dependent operations)

§Returns

A mutable reference to self for method chaining

§When to Use

Enable (true): When tools are independent (e.g., weather + stock prices)
Disable (false): When tools have dependencies (e.g., read file → analyze content)

§Examples

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

let mut client = Responses::new();
client.parallel_tool_calls(true);   // Enable parallel execution
client.parallel_tool_calls(false);  // Force sequential execution

Source

pub fn include(&mut self, includes: Vec<Include>) -> &mut Self

Specifies additional data to include in the response output

Defines various types of additional information that can be included in the API response output, such as web search results, code interpreter outputs, image URLs, log probabilities, and reasoning traces.

§Arguments

includes - A vector of Include enum values specifying what to include

§Available Inclusions

Include::WebSearchCall - Web search results and sources
Include::CodeInterpreterCall - Code execution outputs
Include::FileSearchCall - File search operation results
Include::LogprobsInOutput - Token log probabilities
Include::ReasoningEncryptedContent - Reasoning process traces
Include::ImageUrlInInputMessages - Image URLs from input
Include::ImageUrlInComputerCallOutput - Computer interaction screenshots

§Returns

A mutable reference to self for method chaining

§Examples

use openai_tools::responses::request::{Responses, Include};

let mut client = Responses::new();
client.include(vec![
    Include::WebSearchCall,
    Include::LogprobsInOutput,
    Include::ReasoningEncryptedContent,
]);

Source

pub fn background(&mut self, enable: bool) -> &mut Self

Enables or disables background processing for the request

When enabled, allows the request to be processed in the background, potentially improving throughput for non-urgent requests at the cost of potentially higher latency.

§Arguments

enable - Whether to enable background processing
- true: Process in background (lower priority, potentially longer latency)
- false: Process with standard priority (default behavior)

§Trade-offs

Background processing: Better for batch operations, non-interactive requests
Standard processing: Better for real-time, interactive applications

§Returns

A mutable reference to self for method chaining

§Examples

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

let mut client = Responses::new();
client.background(true);   // Enable background processing
client.background(false);  // Use standard processing

Source

pub fn conversation<T: AsRef<str>>(&mut self, conversation_id: T) -> &mut Self

Sets the conversation ID for grouping related requests

Identifier for grouping related requests as part of the same conversation or session. This helps with context management, analytics, and conversation tracking across multiple API calls.

§Arguments

conversation_id - The conversation identifier
- Must start with “conv-” prefix according to API requirements
- Should be a unique identifier (UUID recommended)

§Returns

A mutable reference to self for method chaining

§Format Requirements

The conversation ID must follow the format: conv-{identifier}

§Examples

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

let mut client = Responses::new();
client.conversation("conv-123e4567-e89b-12d3-a456-426614174000");
client.conversation("conv-user123-session456");

Source

pub fn previous_response_id<T: AsRef<str>>( &mut self, response_id: T, ) -> &mut Self

Sets the ID of the previous response for context continuation

References a previous response in the same conversation to maintain context and enable features like response chaining, follow-up handling, or response refinement.

§Arguments

response_id - The ID of the previous response to reference

§Use Cases

Multi-turn conversations: Maintaining context across multiple exchanges
Follow-up questions: Building on previous responses
Response refinement: Iterating on or clarifying previous answers
Context chaining: Creating connected sequences of responses

§Returns

A mutable reference to self for method chaining

§Examples

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

let mut client = Responses::new();
client.previous_response_id("resp_abc123def456");
client.previous_response_id("response-uuid-here");

Source

pub fn reasoning( &mut self, effort: ReasoningEffort, summary: ReasoningSummary, ) -> &mut Self

Configures reasoning behavior for complex problem-solving

Controls how the model approaches complex reasoning tasks, including the computational effort level and format of reasoning explanations. This is particularly useful for mathematical, logical, or analytical tasks.

§Arguments

effort - The level of reasoning effort to apply:
- ReasoningEffort::Minimal - Fastest, for simple queries
- ReasoningEffort::Low - Balanced, for moderate complexity
- ReasoningEffort::Medium - Thorough, for complex queries
- ReasoningEffort::High - Maximum analysis, for very complex problems
summary - The format for reasoning explanations:
- ReasoningSummary::Auto - Let the model choose the format
- ReasoningSummary::Concise - Brief, focused explanations
- ReasoningSummary::Detailed - Comprehensive, step-by-step explanations

§Returns

A mutable reference to self for method chaining

§Use Cases

Mathematical problem-solving with step-by-step explanations
Complex logical reasoning tasks
Analysis requiring deep consideration
Tasks where understanding the reasoning process is important

§Examples

use openai_tools::responses::request::{Responses, ReasoningEffort, ReasoningSummary};

let mut client = Responses::new();

// High effort with detailed explanations for complex problems
client.reasoning(ReasoningEffort::High, ReasoningSummary::Detailed);

// Medium effort with concise explanations for balanced approach
client.reasoning(ReasoningEffort::Medium, ReasoningSummary::Concise);

Source

pub fn text_verbosity(&mut self, verbosity: TextVerbosity) -> &mut Self

Sets the text output verbosity level

Controls how detailed and lengthy the model’s text responses should be. This is particularly useful for controlling response length and detail level based on your use case requirements.

§Arguments

verbosity - The verbosity level for text output:
- TextVerbosity::Low - Concise, brief responses
- TextVerbosity::Medium - Balanced responses (default)
- TextVerbosity::High - Comprehensive, detailed responses

§Model Support

This parameter is available on GPT-5.2 and newer models.

§Use Cases

Low verbosity: Quick answers, summaries, yes/no questions
Medium verbosity: Standard explanations, general queries
High verbosity: Detailed tutorials, comprehensive analysis

§Examples

use openai_tools::responses::request::{Responses, TextVerbosity};

let mut client = Responses::new();

// Concise responses for simple queries
client.text_verbosity(TextVerbosity::Low);

// Detailed responses for complex explanations
client.text_verbosity(TextVerbosity::High);

Source

pub fn safety_identifier<T: AsRef<str>>(&mut self, safety_id: T) -> &mut Self

Sets the safety identifier for content filtering configuration

Specifies which safety and content filtering policies should be applied to the request. Different safety levels provide varying degrees of content restriction and filtering.

§Arguments

safety_id - The safety configuration identifier

§Common Safety Levels

"strict" - Apply strict content filtering (highest safety)
"moderate" - Apply moderate content filtering (balanced approach)
"permissive" - Apply permissive content filtering (minimal restrictions)
"default" - Use system default safety settings

§Returns

A mutable reference to self for method chaining

§Use Cases

Educational content requiring strict filtering
Business applications with moderate restrictions
Research applications needing broader content access

§Examples

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

let mut client = Responses::new();
client.safety_identifier("strict");     // High safety for education
client.safety_identifier("moderate");   // Balanced for general use
client.safety_identifier("permissive"); // Minimal restrictions

Source

pub fn service_tier<T: AsRef<str>>(&mut self, tier: T) -> &mut Self

Sets the service tier for request processing priority and features

Specifies the service tier for the request, which affects processing priority, rate limits, pricing, and available features. Different tiers provide different levels of service quality and capabilities.

§Arguments

tier - The service tier identifier

§Common Service Tiers

"default" - Standard service tier with regular priority
"scale" - High-throughput tier optimized for bulk processing
"premium" - Premium service tier with enhanced features and priority
"enterprise" - Enterprise tier with dedicated resources

§Returns

A mutable reference to self for method chaining

§Considerations

Higher tiers may have different pricing structures
Some features may only be available in certain tiers
Rate limits and quotas may vary by tier

§Examples

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

let mut client = Responses::new();
client.service_tier("default");   // Standard service
client.service_tier("scale");     // High-throughput processing
client.service_tier("premium");   // Premium features and priority

Source

pub fn store(&mut self, enable: bool) -> &mut Self

Enables or disables conversation storage

Controls whether the conversation may be stored for future reference, training, or analytics purposes. This setting affects data retention and privacy policies.

§Arguments

enable - Whether to allow conversation storage
- true: Allow storage for training, analytics, etc.
- false: Explicitly opt-out of storage

§Privacy Considerations

Enabled storage: Conversation may be retained according to service policies
Disabled storage: Request explicit deletion after processing
Default behavior: Varies by service configuration

§Returns

A mutable reference to self for method chaining

§Use Cases

Enable: Contributing to model improvement, analytics
Disable: Sensitive data, privacy-critical applications

§Examples

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

let mut client = Responses::new();
client.store(false);  // Opt-out of storage for privacy
client.store(true);   // Allow storage for improvement

Source

pub fn stream(&mut self, enable: bool) -> &mut Self

Enables or disables streaming responses

When enabled, the response will be streamed back in chunks as it’s generated, allowing for real-time display of partial results instead of waiting for the complete response.

§Arguments

enable - Whether to enable streaming
- true: Stream response in real-time chunks
- false: Wait for complete response before returning

§Returns

A mutable reference to self for method chaining

§Use Cases

Enable streaming: Real-time chat interfaces, live text generation
Disable streaming: Batch processing, when complete response is needed

§Implementation Notes

Streaming responses require different handling in client code
May affect some response features or formatting options
Typically used with stream_options() for additional configuration

§Examples

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

let mut client = Responses::new();
client.stream(true);   // Enable real-time streaming
client.stream(false);  // Wait for complete response

Source

pub fn stream_options(&mut self, include_obfuscation: bool) -> &mut Self

Configures streaming response options

Additional options for controlling streaming response behavior, such as whether to include obfuscated placeholder content during the streaming process.

§Arguments

include_obfuscation - Whether to include obfuscated content
- true: Include placeholder/obfuscated content in streams
- false: Only include final, non-obfuscated content

§Returns

A mutable reference to self for method chaining

§Relevance

This setting is only meaningful when stream(true) is also set. It has no effect on non-streaming responses.

§Use Cases

Include obfuscation: Better user experience with placeholder content
Exclude obfuscation: Cleaner streams with only final content

§Examples

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

let mut client = Responses::new();
client.stream(true);                    // Enable streaming
client.stream_options(true);            // Include placeholder content
client.stream_options(false);           // Only final content

Source

pub fn top_logprobs(&mut self, n: usize) -> &mut Self

Sets the number of top log probabilities to include in the response

Specifies how many of the most likely alternative tokens to include with their log probabilities for each generated token. This provides insight into the model’s confidence and alternative choices.

§Arguments

n - Number of top alternatives to include (typically 1-20)
- 0: No log probabilities included
- 1-5: Common range for most use cases
- >5: Detailed analysis scenarios

§Returns

A mutable reference to self for method chaining

§Use Cases

Model analysis: Understanding model decision-making
Confidence estimation: Measuring response certainty
Alternative exploration: Seeing what else the model considered
Debugging: Analyzing unexpected model behavior

§Performance Note

Higher values increase response size and may affect latency.

Note: Reasoning models (GPT-5, o-series) do not support top_logprobs. For these models, this parameter will be ignored with a warning.

§Examples

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

let mut client = Responses::new();
client.top_logprobs(1);   // Include top alternative for each token
client.top_logprobs(5);   // Include top 5 alternatives (detailed analysis)
client.top_logprobs(0);   // No log probabilities

Source

pub fn top_p(&mut self, p: f64) -> &mut Self

Sets the nucleus sampling parameter for controlling response diversity

Controls the randomness of the model’s responses by limiting the cumulative probability of considered tokens. This is an alternative to temperature-based sampling that can provide more stable results.

§Arguments

p - The nucleus sampling parameter (0.0 to 1.0)
- 0.1: Very focused, deterministic responses
- 0.7: Balanced creativity and focus (good default)
- 0.9: More diverse and creative responses
- 1.0: Consider all possible tokens (no truncation)

§Returns

A mutable reference to self for method chaining

§How It Works

The model considers only the tokens whose cumulative probability reaches the specified threshold, filtering out unlikely options.

§Interaction with Temperature

Can be used together with temperature() for fine-tuned control:

Low top_p + Low temperature = Very focused responses
High top_p + High temperature = Very creative responses

Note: Reasoning models (GPT-5, o-series) only support top_p=1.0. For these models, other values will be ignored with a warning.

§Examples

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

let mut client = Responses::new();
client.top_p(0.1);   // Very focused responses
client.top_p(0.7);   // Balanced (recommended default)
client.top_p(0.95);  // High diversity

Source

pub fn truncation(&mut self, truncation: Truncation) -> &mut Self

Sets the truncation behavior for handling long inputs

Controls how the system handles inputs that exceed the maximum context length supported by the model. This helps manage cases where input content is too large to process entirely.

§Arguments

truncation - The truncation mode to use:
- Truncation::Auto: Automatically truncate long inputs to fit
- Truncation::Disabled: Return error if input exceeds context length

§Returns

A mutable reference to self for method chaining

§Use Cases

Auto truncation: When you want to handle long documents gracefully
Disabled truncation: When you need to ensure complete input processing

§Considerations

Auto truncation may remove important context from long inputs
Disabled truncation ensures complete processing but may cause errors
Consider breaking long inputs into smaller chunks when possible

§Examples

use openai_tools::responses::request::{Responses, Truncation};

let mut client = Responses::new();
client.truncation(Truncation::Auto);      // Handle long inputs gracefully
client.truncation(Truncation::Disabled);  // Ensure complete processing

Source

pub async fn complete(&self) -> Result<Response>

Executes the request and returns the response

This method sends the configured request to the OpenAI Responses API and returns the parsed response. It performs validation of required fields before sending the request.

§Returns

A Result containing the Response on success, or an OpenAIToolError on failure

§Errors

Returns an error if:

The API key is not set or is empty
The model ID is not set or is empty
Neither messages nor plain text input is provided
Both messages and plain text input are provided (mutually exclusive)
The HTTP request fails
The response cannot be parsed

§Parameter Validation

For reasoning models (GPT-5, o-series), certain parameters have restrictions:

temperature: only 1.0 supported
top_p: only 1.0 supported
top_logprobs: not supported

Validation occurs at two points:

At setter time (when using with_model() constructor) - immediate warning
At API call time (fallback) - for cases where model is changed after setting params

Unsupported parameter values are ignored with a warning and the request proceeds.

§Examples

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

let mut client = Responses::new();
let response = client
    .model_id("gpt-4")
    .str_message("Hello!")
    .complete()
    .await?;

Source

pub async fn retrieve(&self, response_id: &str) -> Result<Response>

Retrieves a response by its ID

Fetches the details of a specific response, including its output, status, and metadata.

§Arguments

response_id - The ID of the response to retrieve

§Returns

A Result containing the Response on success

§API Reference

https://platform.openai.com/docs/api-reference/responses/get

§Examples

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

let client = Responses::new();
let response = client.retrieve("resp_abc123").await?;
println!("Status: {:?}", response.status);

Source

pub async fn delete(&self, response_id: &str) -> Result<DeleteResponseResult>

Deletes a response by its ID

Permanently removes a response from the OpenAI platform.

§Arguments

response_id - The ID of the response to delete

§Returns

A Result containing DeleteResponseResult on success

§API Reference

https://platform.openai.com/docs/api-reference/responses/delete

§Examples

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

let client = Responses::new();
let result = client.delete("resp_abc123").await?;
assert!(result.deleted);

Source

pub async fn cancel(&self, response_id: &str) -> Result<Response>

Cancels an in-progress response

Cancels a response that is currently being generated. This is useful for background responses that are taking too long.

§Arguments

response_id - The ID of the response to cancel

§Returns

A Result containing the cancelled Response on success

§API Reference

https://platform.openai.com/docs/api-reference/responses/cancel

§Examples

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

let client = Responses::new();
let response = client.cancel("resp_abc123").await?;
println!("Response cancelled: {:?}", response.status);

Source

pub async fn list_input_items( &self, response_id: &str, limit: Option<u32>, after: Option<&str>, before: Option<&str>, ) -> Result<InputItemsListResponse>

Lists input items for a response

Retrieves a paginated list of input items that were part of the request that generated the response.

§Arguments

response_id - The ID of the response to get input items for
limit - Maximum number of items to return (default: 20)
after - Cursor for pagination (return items after this ID)
before - Cursor for pagination (return items before this ID)

§Returns

A Result containing InputItemsListResponse on success

§API Reference

https://platform.openai.com/docs/api-reference/responses/list-input-items

§Examples

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

let client = Responses::new();
let items = client.list_input_items("resp_abc123", Some(10), None, None).await?;
for item in items.data {
    println!("Item: {} (type: {})", item.id, item.item_type);
}

Source

pub async fn compact( &self, previous_response_id: &str, model: Option<&str>, ) -> Result<CompactedResponse>

Compacts a response to reduce its size

Creates a compacted version of a response, which can be useful for long-running conversations to reduce token usage.

§Arguments

previous_response_id - The ID of the response to compact
model - Optional model to use for compaction (defaults to original model)

§Returns

A Result containing CompactedResponse on success

§API Reference

https://platform.openai.com/docs/api-reference/responses/compact

§Examples

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

let client = Responses::new();
let compacted = client.compact("resp_abc123", None).await?;
println!("Compacted response ID: {}", compacted.id);

Source

pub async fn get_input_tokens( &self, model: &str, input: Value, ) -> Result<InputTokensResponse>

Counts the number of input tokens for a potential request

Useful for estimating token usage before sending a request.

§Arguments

model - The model to use for token counting
input - The input to count tokens for (can be a string or messages array)

§Returns

A Result containing InputTokensResponse on success

§API Reference

https://platform.openai.com/docs/api-reference/responses/input-tokens

§Examples

use openai_tools::responses::request::Responses;
use serde_json::json;

let client = Responses::new();
let tokens = client.get_input_tokens("gpt-4o-mini", json!("Hello, world!")).await?;
println!("Input tokens: {}", tokens.input_tokens);

Trait Implementations§

Source §

impl Clone for Responses

Source §

fn clone(&self) -> Responses

Returns a duplicate of the value. Read more

1.0.0 · Source§

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

Performs copy-assignment from source. Read more

Source §

impl Debug for Responses

Source §

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

Formats the value using the given formatter. Read more

Source §

impl Default for Responses

Source §

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl UnwindSafe for Responses

Blanket Implementations§

Source §

impl<T> Any for T
where T: 'static + ?Sized,

Source §

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

Source §

impl<T> Borrow<T> for T
where T: ?Sized,

Source §

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

Source §

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source §

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

Source §

impl<T> CloneToUninit for T
where T: Clone,

Source §

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)

Performs copy-assignment from self to dest. Read more

Source §

impl<T> From<T> for T

Source §

fn from(t: T) -> T

Returns the argument unchanged.

Source §

impl<T> Instrument for T

Source §

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Source §

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Source §

impl<T, U> Into for T
where U: From<T>,

Source §

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source §

impl<T> IntoEither for T

Source §

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more

Source §

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more

Source §