Struct Embedding 

pub struct Embedding { /* private fields */ }

Main struct for building and sending embedding requests to the OpenAI API.

This struct provides a builder pattern interface for constructing embedding requests with various parameters. Use Embedding::new() to create a new instance, then chain methods to configure the request before calling [embed()].

Providers

The client supports two providers:

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

Example

use openai_tools::embedding::request::Embedding;
use openai_tools::common::models::EmbeddingModel;

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

    let response = embedding
        .model(EmbeddingModel::TextEmbedding3Small)
        .input_text("Sample text")
        .embed()
        .await?;

    Ok(())
}

Implementations

impl Embedding

pub fn new() -> Result<Self>

Creates a new Embedding instance for OpenAI API.

Initializes the embedding client by loading the OpenAI API key from the environment variable OPENAI_API_KEY. Supports .env file loading via dotenvy.

Returns

• Ok(Embedding) - A new embedding instance ready for configuration
• Err(OpenAIToolError) - If the API key is not found in the environment

Example

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

let embedding = Embedding::new().expect("API key should be set");

pub fn with_auth(auth: AuthProvider) -> Self

Creates a new Embedding instance with a custom authentication provider

Use this to explicitly configure OpenAI or Azure authentication.

Arguments

• auth - The authentication provider

Returns

A new Embedding instance with the specified auth provider

pub fn azure() -> Result<Self>

Creates a new Embedding instance for Azure OpenAI API

Loads configuration from Azure-specific environment variables.

Returns

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

pub fn detect_provider() -> Result<Self>

Creates a new Embedding instance by auto-detecting the provider

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

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

Creates a new Embedding 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

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

Creates a new Embedding instance from URL using environment variables

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

pub fn auth(&self) -> &AuthProvider

Returns the authentication provider

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.

Arguments

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

Returns

A mutable reference to self for method chaining

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

Sets the model to use for embedding generation.

Arguments

• model - The embedding model to use

Returns

A mutable reference to self for method chaining

Example

use openai_tools::embedding::request::Embedding;
use openai_tools::common::models::EmbeddingModel;

let mut embedding = Embedding::new().unwrap();
embedding.model(EmbeddingModel::TextEmbedding3Small);

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

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

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

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

Arguments

• model_id - The model identifier string (e.g., “text-embedding-3-small”)

Returns

A mutable reference to self for method chaining

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::embedding::request::Embedding;
use openai_tools::common::models::EmbeddingModel;

let mut embedding = Embedding::new().unwrap();
embedding.model(EmbeddingModel::TextEmbedding3Small)
    .timeout(Duration::from_secs(30));

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

Sets a single text input for embedding.

Use this method when you want to embed a single piece of text. For multiple texts, use [input_text_array] instead.

Arguments

• input_text - The text to convert into an embedding vector

Returns

A mutable reference to self for method chaining

Example

embedding.input_text("Hello, world!");

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

Sets multiple text inputs for batch embedding.

Use this method when you want to embed multiple texts in a single API call. This is more efficient than making separate requests for each text.

Arguments

• input_text_array - Vector of texts to convert into embedding vectors

Returns

A mutable reference to self for method chaining

Example

let texts = vec!["First text", "Second text", "Third text"];
embedding.input_text_array(texts);

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

Sets the encoding format for the output embeddings.

Arguments

• encoding_format - Either “float” (default) or “base64”
  • "float": Returns embeddings as arrays of floating point numbers
  • "base64": Returns embeddings as base64-encoded strings (more compact)

Returns

A mutable reference to self for method chaining

Panics

Panics if encoding_format is not “float” or “base64”

Example

embedding.encoding_format("float");

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

Sends the embedding request to the OpenAI API.

This method validates the request parameters, constructs the HTTP request, sends it to the OpenAI Embeddings API endpoint, and parses the response.

Returns

• Ok(Response) - The embedding response containing vectors and metadata
• Err(OpenAIToolError) - If validation fails, the request fails, or parsing fails

Errors

Returns an error if:

• API key is not set
• Model ID is not set
• Input text is not set
• Network request fails
• Response parsing fails

Example

let mut embedding = Embedding::new()?;
let response = embedding
    .model(EmbeddingModel::TextEmbedding3Small)
    .input_text("Hello, world!")
    .embed()
    .await?;