SDKs
Rust SDK
Rust watermarking SDK for Etchv. Watermark images, PDFs and videos, detect watermarks, and handle assets, async jobs and webhooks from your Rust code.
Needs Rust 1.88 or later. The client is blocking: each call waits for its result. In an async application, run it on its own thread or with spawn_blocking. MIT licensed.
Install
cargo add etchv serde_jsonOr add these dependencies to Cargo.toml:
[dependencies]
etchv = "1"
serde_json = "1"Embed a file
Set ETCHV_API_KEY on your server. This example needs an API key with the watermarks:embed scope, an active plan and available credits.
use etchv::{Client, Options};
use serde_json::json;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new(std::env::var("ETCHV_API_KEY")?)?;
let key = client.get_api_key_info()?; // no credits used
println!("Connected to {} with scopes {:?}", key.organization_id, key.scopes);
let result = client.embed_image(&std::fs::read("photo.jpg")?,
&json!({"asset": "photo-123"}), Options::new().filename("photo.jpg"))?;
std::fs::write(&result.filename, &result.bytes)?;
Ok(())
}get_api_key_info checks your API key and uses no credits. Save the output bytes as they are. Do not re-encode the file.
Images, documents and video
For every media type, result.bytes holds the watermarked file in its original format. Embedding also returns watermark_id, request_id, content_type, filename, asset_id, source_asset_id and storage_delivery_id.
Detection returns the watermark it found, a confidence score, and results for each frame or page. It does not return the JSON you sent when you embedded the file. Result fields · Credits.
Client configuration
Client::with_options(key, base_url, Duration) sets the base URL and the timeout. The default timeout is 120 seconds. Use Options::new().filename(...).idempotency_key(...) on each media request. The examples below assume you already have a client.
Retries and recovery
Embedding and video detection retry and check job status for you. Image and PDF detection do not. Before you upload, save an idempotency key (a value you choose so a retry isn't run twice). With it, you can recover the request even after your program restarts.
| Situation | Action |
|---|---|
| Client timeout | The accepted job keeps running. Resume it, or resend the same inputs with the same key |
| Resume a job | get_embed_result( / get_detection_result( |
| Changed inputs | Use a new key. Reusing a key with different inputs returns 409 |
| Collect a saved result | Within 24 hours. See retention |
- Client timeout
- Action
- The accepted job keeps running. Resume it, or resend the same inputs with the same key
- Resume a job
- Action
get_embed_result(/request_id) get_detection_result(request_id)
- Changed inputs
- Action
- Use a new key. Reusing a key with different inputs returns
409
- Collect a saved result
- Action
- Within 24 hours. See retention
Error types and handling
Methods return Result<T, etchv::Error>. An error has a kind: InvalidInput, Transport, Timeout, Api or InvalidResponse. It also has status_code, message(), request_id and idempotency_key. Status 0 means the failure happened on the client side. is_gone() tells you the status was HTTP 410.
match client.embed_document(&bytes, &serde_json::json!({"doc": "42"}), Options::new()) {
Ok(result) => println!("{}", result.watermark_id),
Err(e) if e.is_timeout() => eprintln!("retry with key {:?}", e.idempotency_key),
Err(e) if e.kind == etchv::ErrorKind::Api => {
eprintln!("HTTP {}, request {:?}", e.status_code, e.request_id)
}
Err(e) => eprintln!("{e}"),
}See HTTP errors and retry behavior. When you report a failure, include the request ID.
Asset library
These calls use no credits. Downloads need the assets:read scope, and edits need assets:write. Deleting needs assets:delete and the owner or admin role.
List, edit and download assets
let page = client.list_assets(etchv::AssetListOptions::new().kind("watermarked").limit(25))?;
for item in page.items {
let asset = client.get_asset(&item.id)?;
let updated = client.update_asset(&asset.id, asset.version,
&serde_json::json!({"metadata": {"campaign": "spring"}}))?;
if updated.file_available {
let bytes = client.download_asset(&updated.id)?;
}
}
// Pass page.next_cursor to .cursor(...) with the same filters to continue listing.An edit replaces the metadata and must send the asset's current version. A 409 conflict means the asset changed since you read it, so fetch it again and redo your edit. delete_asset deletes one asset. delete_assets deletes 1–50 assets as one action: either all are deleted or none are. Asset fields, filters and retention.
Async jobs and webhooks
To start a job without waiting for the result, call submit_embed or submit_detection. You get a receipt back. Set the media type with Media::Image, Media::Document or Media::Video.
Check an embedding job with get_job and a detection job with get_detection_job.
Submit and collect an async job
Read the file into memory before you submit it.
use etchv::{JobStatus, Media, Options};
let job = client.submit_embed(Media::Document, &pdf_bytes,
&serde_json::json!({"delivery": "delivery_001"}),
Options::new().filename("document.pdf").idempotency_key("delivery_001"),
Some(&webhook_id))?;
let status = client.get_job(&job.request_id)?;
if status.status == JobStatus::Succeeded {
let result = client.get_embed_result(&job.request_id)?;
}The webhook is optional. In Java or Rust, pass null or None to skip it. Save the receipt. Job handling.
Manage endpoints and verify webhooks
Methods: create_webhook, list_webhooks, update_webhook, delete_webhook, list_webhook_deliveries, redeliver_webhook. Viewing webhooks needs webhooks:read. Managing them needs webhooks:write and the owner or admin role. The signing secret is shown only once, so save it.
// timestamp, signature and event_id are the X-Etchv-Timestamp,
// X-Etchv-Signature and X-Etchv-Event-ID header values.
if !etchv::verify_webhook_signature(&secret, timestamp, signature, raw_body) {
return Err("invalid signature".into()); // respond 400
}
let event: etchv::WebhookEvent = serde_json::from_slice(raw_body)?;
if event.id != event_id {
return Err("event ID mismatch".into());
}
// Deduplicate on event.id, enqueue work, then return 2xx.verify_webhook_signature checks the signature and timestamp. Your handler must also check that the event ID in the body matches X-Etchv-Event-ID, as shown. Pass the raw request bytes and use a 300-second timestamp tolerance. Then skip events you already handled, queue the work and return 2xx. Verification rules.
GPU processing
On Business or Enterprise plans, pass Options::new().accelerator(Accelerator::Gpu). GPU processing uses 3× the credits. If processing falls back to CPU, it uses normal credits. result.accelerator shows which one was used. See
GPU processing.
Choose where results are stored
Connect your bucket. Then pass its destination ID and, if you like, an object key (the file's path in the bucket). Leave both out to use Etchv storage.
Deliver to your bucket
let job = client.submit_embed(Media::Document, &pdf_bytes,
&serde_json::json!({"recipient": "customer-123"}),
Options::new()
.filename("report.pdf")
.idempotency_key("report-export-001")
.storage_destination_id(&destination_id)
.storage_key("reports/watermarked.pdf"),
None)?;
// After the watermark job reports succeeded:
if let Some(id) = client.get_job(&job.request_id)?.storage_delivery_id {
let delivery = client.get_storage_delivery(&id)?;
println!("{}", delivery.status);
}After the job succeeds, check the delivery with the storage:read scope. Checking before then returns 404. When the status is stored, download the file with download_storage_delivery.
retry_storage_delivery retries a failed or cancelled delivery at no cost. It needs storage:write and the owner or admin role. To add a destination, build it with NewStorageDestination::s3, gcs or azure. Then call create_storage_destination and verify_storage_destination. Use create_storage_delivery to move an existing result. See delivery recovery.