Struct TripoClient 

pub struct TripoClient {
    pub s3_endpoint_override: Option<String>,
    /* private fields */
}

The main client for interacting with the Tripo3D API.

It holds the shared reqwest::Client and the base URL for all API requests. It is designed to be cloneable and safe to share across threads.

Fields

s3_endpoint_override: Option<String>

(For testing) Overrides the S3 endpoint to allow mocking S3 uploads.

Implementations

impl TripoClient

pub fn new(api_key: Option<String>) -> Result<Self, TripoError>

Creates a new TripoClient.

This method initializes the client with an API key. It first checks for the api_key parameter. If it’s None, it falls back to the TRIPO_API_KEY environment variable.

Arguments

• api_key - An Option<String> containing the API key.

Errors

Returns TripoError::MissingApiKey if the API key is not provided either via the parameter or the environment variable.

Example

// Create a client using a provided API key
let client_from_key = TripoClient::new(Some("your_api_key_here".to_string()));

// Or create a client using the TRIPO_API_KEY environment variable
// (ensure it's set in your environment)
let client_from_env = TripoClient::new(None);

pub fn new_with_url(api_key: String, base_url: &str) -> Result<Self, TripoError>

Creates a new TripoClient with a custom base URL.

This is useful for testing or for connecting to a different API endpoint.

Arguments

• api_key - The API key for authentication.
• base_url - The base URL for the API (e.g., for a mock server).

Errors

This function can return an error if the internal HTTP client fails to build or if the provided base_url is invalid.

pub async fn text_to_model( &self, prompt: &str, ) -> Result<TaskResponse, TripoError>

Submits a new text-to-model generation task.

Arguments

• prompt - A text description of the 3D model to generate.

Returns

On success, a TaskResponse containing the ID of the newly created task.

Errors

Returns a TripoError if the API request fails.

pub async fn upload_file_s3<P: AsRef<Path>>( &self, image_path: P, ) -> Result<FileContent, TripoError>

Uploads a file to a temporary S3 location using STS credentials.

This method replicates a secondary upload mechanism from the official Python SDK. It first requests temporary STS credentials from the Tripo API, then uses those credentials to upload the specified file directly to an S3 bucket.

Note: This is generally not the primary method for file uploads. upload_file is preferred for most use cases.

Arguments

• image_path - The path to the local image file to upload.

Returns

On success, a FileContent struct containing the S3 object details.

Errors

Returns a TripoError if fetching STS tokens, reading the file, or uploading to S3 fails.

pub async fn upload_file<P: AsRef<Path>>( &self, image_path: P, ) -> Result<String, TripoError>

Uploads a file using the standard multipart method to get a file token.

This is the primary and recommended method for uploading files. It sends the file directly to the Tripo API as a multipart/form-data request and receives a file_token in return, which can then be used in other API calls.

Arguments

• image_path - The path to the local image file to upload.

Returns

On success, a file_token as a String.

Errors

Returns a TripoError if the file cannot be read or if the API request fails.

pub async fn image_to_model( &self, image: &str, ) -> Result<TaskResponse, TripoError>

Submits a new image-to-model generation task.

The image parameter is flexible and accepts one of three input types:

1. A public URL string starting with http:// or https://.
2. A file token (as a UUID string) obtained from a previous upload.
3. A path to a local file, which will be uploaded automatically.

Arguments

• image - A string representing the image input (URL, file token, or local path).

Returns

On success, a TaskResponse containing the ID of the newly created task.

Errors

Returns a TripoError if the input string is a file path that doesn’t exist, if the file upload fails, or if the final API request fails.

pub async fn get_task(&self, task_id: &str) -> Result<TaskStatus, TripoError>

Retrieves the status of a specific task.

This is the primary method for polling the status of a long-running generation task.

Arguments

• task_id - The unique identifier of the task to query.

Returns

On success, a TaskStatus struct with the latest status of the task.

Errors

Returns a TripoError if the API request fails.

pub async fn get_balance(&self) -> Result<Balance, TripoError>

Queries the user’s current account balance.

Returns

On success, a Balance struct containing the user’s balance information.

Errors

Returns a TripoError if the API request fails.

pub async fn wait_for_task( &self, task_id: &str, verbose: bool, ) -> Result<TaskStatus, TripoError>

Waits for a task to complete by polling its status.

This method repeatedly calls get_task until the task status is either Success or Failed.

Arguments

• task_id - The ID of the task to wait for.
• verbose - If true, prints the task progress to the console.

Returns

On success, the final TaskStatus of the completed or failed task.

Errors

Returns a TripoError if polling fails at any point.

Example

let final_status = client.wait_for_task(task_id, true).await?;
println!("Task finished with status: {:?}", final_status.status);

pub async fn download_model<P: AsRef<Path>>( &self, model_file: &ResultFile, dest_dir: P, ) -> Result<PathBuf, TripoError>

Downloads a single model file to a specified directory.

This function handles the HTTP request to the model’s URL and saves the content to a local file. The filename is inferred from the URL.

Arguments

• model_file - A reference to a ResultFile struct containing the download URL.
• dest_dir - The local directory path where the file will be saved.

Returns

A Result containing the PathBuf of the newly created file.

Errors

Returns a TripoError if the download fails, the destination directory or file cannot be created, or there’s an issue writing the file to disk.

pub async fn download_all_models<P: AsRef<Path>>( &self, task_status: &TaskStatus, dest_dir: P, ) -> Result<Vec<PathBuf>, TripoError>

Downloads all models from a completed task to a specified directory.

This is a convenience method that iterates over the results in a TaskStatus and downloads each available model file.

Arguments

• task_status - The completed TaskStatus containing the models to download.
• dest_dir - The directory where the models will be saved.

Returns

A Vec containing the PathBuf of each downloaded file.

Errors

Returns a TripoError if any of the model downloads fail.

Trait Implementations

impl Clone for TripoClient

fn clone(&self) -> TripoClient

Returns a duplicate of the value.

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

Performs copy-assignment from source.