Allscreenshots SDK for Rust

Official Rust SDK for the Allscreenshots API - capture website screenshots programmatically.

Installation

Add this to your Cargo.toml:

[dependencies]
allscreenshots-sdk = "0.1"
tokio = { version = "1", features = ["full"] }

Quick start

use allscreenshots_sdk::{AllscreenshotsClient, ScreenshotRequest};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client (reads API key from ALLSCREENSHOTS_API_KEY env var)
    let client = AllscreenshotsClient::from_env()?;

    // Take a screenshot
    let request = ScreenshotRequest::builder()
        .url("https://github.com")
        .device("Desktop HD")
        .build()?;

    let image_bytes = client.screenshot(&request).await?;
    std::fs::write("screenshot.png", &image_bytes)?;

    println!("Screenshot saved to screenshot.png");
    Ok(())
}

Configuration

Environment variable

The SDK automatically reads the API key from the ALLSCREENSHOTS_API_KEY environment variable:

export ALLSCREENSHOTS_API_KEY=your-api-key

Builder pattern

Configure the client with custom options:

use allscreenshots_sdk::AllscreenshotsClient;
use std::time::Duration;

let client = AllscreenshotsClient::builder()
    .api_key("your-api-key")
    .base_url("https://api.allscreenshots.com")
    .timeout(Duration::from_secs(120))
    .max_retries(5)
    .build()?;

API reference

Screenshot capture

Synchronous screenshot

use allscreenshots_sdk::{AllscreenshotsClient, ScreenshotRequest, ImageFormat};

let client = AllscreenshotsClient::from_env()?;

let request = ScreenshotRequest::builder()
    .url("https://example.com")
    .device("Desktop HD")
    .full_page(true)
    .format(ImageFormat::Png)
    .quality(90)
    .dark_mode(true)
    .build()?;

let image_bytes = client.screenshot(&request).await?;
std::fs::write("screenshot.png", &image_bytes)?;

Asynchronous screenshot

For long-running screenshots, use the async API:

use allscreenshots_sdk::{AllscreenshotsClient, ScreenshotRequest};
use std::time::Duration;

let client = AllscreenshotsClient::from_env()?;

let request = ScreenshotRequest::builder()
    .url("https://example.com")
    .full_page(true)
    .build()?;

// Start the job
let job = client.screenshot_async(&request).await?;
println!("Job created: {}", job.id);

// Poll for completion
loop {
    let status = client.get_job(&job.id).await?;

    if status.status.is_terminal() {
        if status.status.is_success() {
            let image = client.get_job_result(&job.id).await?;
            std::fs::write("screenshot.png", &image)?;
            println!("Screenshot saved!");
        } else {
            println!("Job failed: {:?}", status.error_message);
        }
        break;
    }

    tokio::time::sleep(Duration::from_secs(1)).await;
}

Bulk screenshots

Capture multiple URLs in a single request:

use allscreenshots_sdk::{AllscreenshotsClient, BulkRequest, BulkUrlRequest, BulkDefaults};

let client = AllscreenshotsClient::from_env()?;

let request = BulkRequest::new(vec![
    BulkUrlRequest::new("https://github.com"),
    BulkUrlRequest::new("https://google.com"),
    BulkUrlRequest::new("https://rust-lang.org"),
]).with_defaults(BulkDefaults {
    device: Some("Desktop HD".to_string()),
    ..Default::default()
});

let bulk_job = client.create_bulk_job(&request).await?;
println!("Bulk job created: {}", bulk_job.id);

// Check status
let status = client.get_bulk_job(&bulk_job.id).await?;
println!("Progress: {}%", status.progress);

Compose multiple screenshots

Combine multiple screenshots into a single image:

use allscreenshots_sdk::{
    AllscreenshotsClient, ComposeRequest, CaptureItem,
    ComposeOutputConfig, LayoutType
};

let client = AllscreenshotsClient::from_env()?;

let request = ComposeRequest::with_captures(vec![
    CaptureItem::new("https://github.com").with_device("Desktop HD"),
    CaptureItem::new("https://github.com").with_device("iPhone 14"),
    CaptureItem::new("https://github.com").with_device("iPad"),
]).with_output(ComposeOutputConfig {
    layout: Some(LayoutType::Horizontal),
    spacing: Some(20),
    background: Some("#ffffff".to_string()),
    ..Default::default()
});

let result = client.compose(&request).await?;
println!("Composed image URL: {:?}", result.url);

Scheduled screenshots

Set up recurring screenshot captures:

use allscreenshots_sdk::{AllscreenshotsClient, CreateScheduleRequest, ScheduleScreenshotOptions};

let client = AllscreenshotsClient::from_env()?;

let request = CreateScheduleRequest::new(
    "Daily GitHub capture",
    "https://github.com",
    "0 9 * * *", // Every day at 9 AM
)
.with_timezone("America/New_York")
.with_retention_days(30)
.with_options(ScheduleScreenshotOptions {
    device: Some("Desktop HD".to_string()),
    full_page: Some(true),
    ..Default::default()
});

let schedule = client.create_schedule(&request).await?;
println!("Schedule created: {}", schedule.id);

// List all schedules
let schedules = client.list_schedules().await?;
for s in schedules.schedules {
    println!("  {} - {}", s.name, s.status);
}

// Pause a schedule
client.pause_schedule(&schedule.id).await?;

// Resume a schedule
client.resume_schedule(&schedule.id).await?;

// Get execution history
let history = client.get_schedule_history(&schedule.id, Some(10)).await?;
for execution in history.executions {
    println!("  {} - {}", execution.executed_at, execution.status);
}

Usage and quota

Check your API usage:

use allscreenshots_sdk::AllscreenshotsClient;

let client = AllscreenshotsClient::from_env()?;

// Get usage statistics
let usage = client.get_usage().await?;
println!("Tier: {}", usage.tier);
println!("Screenshots this period: {}", usage.current_period.screenshots_count);
println!("Bandwidth used: {}", usage.current_period.bandwidth_formatted);

// Get quota status
let quota = client.get_quota().await?;
println!("Screenshots remaining: {}", quota.screenshots.remaining);
println!("Quota used: {}%", quota.screenshots.percent_used);

Screenshot options

Device presets

Common device presets:

Error handling

The SDK provides typed errors for robust error handling:

use allscreenshots_sdk::{AllscreenshotsClient, ScreenshotRequest, AllscreenshotsError, ErrorCode};

let client = AllscreenshotsClient::from_env()?;
let request = ScreenshotRequest::builder()
    .url("https://example.com")
    .build()?;

match client.screenshot(&request).await {
    Ok(image) => {
        std::fs::write("screenshot.png", &image)?;
    }
    Err(AllscreenshotsError::ApiError { code, message, status }) => {
        match code {
            ErrorCode::RateLimitExceeded => {
                println!("Rate limit exceeded, please wait and retry");
            }
            ErrorCode::Unauthorized => {
                println!("Invalid API key");
            }
            ErrorCode::ValidationError => {
                println!("Invalid request: {}", message);
            }
            _ => {
                println!("API error ({}): {}", status, message);
            }
        }
    }
    Err(AllscreenshotsError::ValidationError(msg)) => {
        println!("Request validation failed: {}", msg);
    }
    Err(AllscreenshotsError::Timeout) => {
        println!("Request timed out");
    }
    Err(e) => {
        println!("Error: {}", e);
    }
}

Retryable errors

The SDK automatically retries transient errors with exponential backoff:

• Rate limit exceeded (429)
• Internal server errors (5xx)
• Network timeouts
• Connection errors

Configure retry behavior:

let client = AllscreenshotsClient::builder()
    .api_key("your-api-key")
    .max_retries(5)
    .build()?;

License

Apache License 2.0

Links

• Allscreenshots website
• API documentation
• GitHub repository