imgbb-rs

A comprehensive and flexible ImgBB API client for Rust

Features

• Upload images using file path, bytes, or base64 encoded strings
• Customize uploads with name, title, expiration time, and album ID
• Delete images
• Robust error handling with specialized error types
• Builder pattern for flexible configuration
• Custom timeout settings
• Custom user agent support
• TLS features options: rustls-tls or native-tls
• Use your own reqwest client with custom configuration

Getting Started

1. Register/Log in to ImgBB
2. Obtain the API Key
3. Add imgbb to your project dependencies:

[dependencies]
imgbb = "1.3.0"

Usage Examples

Simple Upload

use imgbb::ImgBB;
use tokio;

#[tokio::main]
async fn main() -> Result<(), imgbb::Error> {
    // Initialize with your API key
    let imgbb = ImgBB::new("YOUR_API_KEY");

    // Upload an image file
    let response = imgbb.upload_file("path/to/image.jpg").await?;
    
    // Print the image URL
    println!("Uploaded image URL: {}", response.data.unwrap().url.unwrap());
    
    Ok(())
}

Advanced Upload with Builder Pattern

use imgbb::ImgBB;
use std::time::Duration;
use tokio;

#[tokio::main]
async fn main() -> Result<(), imgbb::Error> {
    // Initialize with custom configuration
    let imgbb = ImgBB::builder("YOUR_API_KEY")
        .timeout(Duration::from_secs(30))
        .user_agent("MyApp/1.0")
        .build()?;
        
    // Create an upload with additional options
    let response = imgbb.upload_builder()
        .file("path/to/image.jpg")?
        .name("my_custom_name")
        .title("My Image Title")
        .expiration(86400) // 24 hours
        .album("album_id")
        .upload()
        .await?;
        
    // Print image details
    let data = response.data.unwrap();
    println!("Image ID: {}", data.id.unwrap());
    println!("Image URL: {}", data.url.unwrap());
    println!("Delete URL: {}", data.delete_url.unwrap());
    
    Ok(())
}

Error Handling

use imgbb::{ImgBB, Error};
use tokio;

#[tokio::main]
async fn main() {
    let imgbb = ImgBB::new("YOUR_API_KEY");
    
    match imgbb.upload_file("path/to/image.jpg").await {
        Ok(response) => {
            println!("Upload successful!");
            println!("URL: {}", response.data.unwrap().url.unwrap());
        },
        Err(Error::InvalidApiKey) => {
            eprintln!("Your API key is invalid");
        },
        Err(Error::ImageTooLarge) => {
            eprintln!("Image exceeds the maximum size limit");
        },
        Err(Error::RateLimitExceeded) => {
            eprintln!("Rate limit exceeded, please wait and try again");
        },
        Err(e) => {
            eprintln!("Upload failed: {}", e);
        }
    }
}

Deleting Images

use imgbb::ImgBB;
use tokio;

#[tokio::main]
async fn main() -> Result<(), imgbb::Error> {
    let imgbb = ImgBB::new("YOUR_API_KEY");
    
    // First upload an image
    let response = imgbb.upload_file("path/to/image.jpg").await?;
    
    // Get the delete URL
    let delete_url = response.data.unwrap().delete_url.unwrap();
    println!("Delete URL: {}", delete_url);
    
    // Delete the image
    imgbb.delete(delete_url).await?;
    println!("Image deleted successfully");
    
    Ok(())
}

Advanced Configuration

TLS Options

By default, this crate uses the native TLS implementation. You can switch to rustls by using a feature flag:

[dependencies]
imgbb = { version = "1.3.0", features = ["rustls-tls"], default-features = false }

Custom reqwest Client

You can provide your own preconfigured reqwest client for more control over network settings:

use imgbb::ImgBB;
use reqwest::Client;
use std::time::Duration;

// Create a custom reqwest client
let client = Client::builder()
    .timeout(Duration::from_secs(30))
    .user_agent("MyApp/1.0")
    .https_only(true)
    .pool_max_idle_per_host(10)
    .build()
    .unwrap();

// Use with direct constructor
let imgbb = ImgBB::new_with_client("YOUR_API_KEY", client.clone());

// Or use with builder pattern
let imgbb = ImgBB::builder("YOUR_API_KEY")
    .client(client)
    .build()
    .unwrap();

Timeout Configuration

use imgbb::ImgBB;
use std::time::Duration;

// Create a client with a 10-second timeout
let imgbb = ImgBB::builder("YOUR_API_KEY")
    .timeout(Duration::from_secs(10))
    .build()
    .unwrap();

API Reference

For complete API documentation, see docs.rs/imgbb

License

imgbb-rs is licensed under the GNU GPL v3.0