Crate api2convert

Expand description

Official Rust SDK for the API2Convert file-conversion API.

One call uploads (or references a URL), starts the job, polls it to completion and hands you the result:

use api2convert::{Api2Convert, ConvertOptions};

let client = Api2Convert::new("YOUR_API_KEY")?;

// Convert a local file and save the result into a directory.
let result = client.convert("photo.heic", "jpg")?;
let path = result.save("out/", None)?;
println!("saved {}", path.display());

// Convert a remote URL with target-specific options.
let result = client.convert_with(
    "https://example.com/input.png",
    "jpg",
    ConvertOptions::new().option("quality", 85),
)?;
let bytes = result.contents(None)?;

This crate is one of the official API2Convert SDKs (PHP, Python, Java, Node.js, Go, Ruby, Rust) that implement the same language-agnostic contract (docs/SDK_CONTRACT.md) and version together.

§Errors

Every fallible call returns Result, whose error is Api2ConvertError. Match it to react to specific conditions:

match client.convert("in.png", "not-a-format") {
    Ok(result) => { let _ = result; }
    Err(Api2ConvertError::Validation(e)) => eprintln!("bad request: {}", e.message),
    Err(Api2ConvertError::RateLimit { retry_after, .. }) => {
        eprintln!("rate limited; retry after {:?}s", retry_after)
    }
    Err(e) => eprintln!("failed: {e}"),
}

§Security

Account key, per-job upload token and download password ride in custom X-Api2convert-* headers. Secret-bearing requests never follow redirects (only the self-contained, no-secret download path does), uploads use the per-job token (never the account key), and no secret ever appears in an error message. See SECURITY.md.

Re-exports§

pub use cloud::CloudInput;
pub use cloud::OutputTarget;

Modules§

cloud: Cloud storage connectors: the CloudInput builder and the OutputTarget model, plus the provider vocabulary.
enums: String-valued enumerations from the API. Unknown values are preserved as-is (never rejected), so a newly-added status or input type does not break the SDK — forward compatibility is a contract requirement.

Structs§

Api2Convert: The API2Convert client. Cheap to clone (shares one transport).
ApiErrorData: Metadata shared by every HTTP error (status ≥ 400).
AsyncOptions: Controls for an asynchronous convert_async.
ClientBuilder: Builds an Api2Convert client. Obtain one via Api2Convert::builder.
ContractsResource: The account’s contract / plan details (GET /contracts). Returns free-form JSON.
Conversion: One conversion within a job.
ConversionResult: The outcome of a completed convert: the finished Job plus convenience download methods for the selected output.
ConversionsResource: The conversions catalog (GET /conversions) — which targets exist and which options each accepts.
ConvertOptions: Controls for a synchronous convert.
FileDownload: A handle to a single downloadable output. A download password given at conversion time (or to Api2Convert::download) is remembered here and sent automatically; an explicit password argument to save / contents overrides it for that call.
Headers: A case-insensitive collection of response headers.
HttpRequest: A library-agnostic HTTP request.
HttpResponse: A library-agnostic HTTP response. The body is streamed, never buffered by the sender.
InputFile: An input file of a job.
Job: A conversion job — the central resource. Create it, (upload | add a remote input), start it, poll it to a terminal status, then download its outputs.
JobMessage: An entry of a job’s errors[] / warnings[].
JobsResource: Full control over the job lifecycle. Most callers only need Api2Convert::convert, which is built on these.
OutputFile: An output file of a job. uri is a self-contained download URL (no auth, finite TTL); protect it with a download password if the job set one.
Preset: A saved conversion preset.
PresetsResource: Manage saved conversion presets (reusable named target + options).
StatsResource: Usage statistics (GET /stats/{period}/{value}/{filter}). Returns free-form JSON.
Status: A job’s status: a code (see crate::enums::job_status) and optional human-readable info.
WebhookEvent: A verified/parsed webhook delivery: the Job it describes plus the full decoded payload.
WebhookVerifier: Verifies and parses webhook deliveries.

Enums§

Api2ConvertError: Every error the SDK can produce.
Input: Something to convert: a local file path, a remote URL (http(s)://…), an in-memory buffer, or a streaming reader.

Constants§

API_KEY_ENV: The environment variable consulted when no API key is passed explicitly.
DEFAULT_BASE_URL: The default API base URL.
VERSION: The SDK version. Versioned together with the sibling API2Convert SDKs against the shared docs/SDK_CONTRACT.md.

Traits§

HttpSender: Sends an HttpRequest and returns an HttpResponse. A genuine transport failure is returned as Api2ConvertError::Network; a non-2xx status is not an error at this layer (the transport maps it).
Rng: A [0, 1) random source for backoff jitter. Tests inject a fixed value for deterministic backoff.
Sleeper: The delay function used by retry and poll backoff. The default sleeps the current thread; tests inject a no-op recorder.

Type Aliases§

Result: Shorthand for a Result whose error is Api2ConvertError.