api2convert 10.2.0 → 10.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3d6b5c540037362377c06e4096518c623017c17882b39233f932f73f0b70d14
-  data.tar.gz: 37b28638fbef0fd35e3eff63abb8557fd27c4400a4c4e63bab170dbf86d0fd8e
+  metadata.gz: ab0c201184fae5e154e8eb8dda08b1dd523f6721b8c0ea63882f36b0d08d69a8
+  data.tar.gz: 51d41801caf9b731b48b2f988b2f76605638b455b90a337c4ce6ce2acbfda4d6
 SHA512:
-  metadata.gz: 83f600ae36bd429c61df404004a744b2cb51dad8aedab4c739c79ed83b8c95d77542c5162d0c356a84cb7515d369457f6264c92c1d03c898a84c74768148444c
-  data.tar.gz: 63031c428a7bb3ea8e976ac2861c38dc27b83585ab41c0927ad24660a3c1d9a2aee10724b6b9b743ea947019e026f941ab84272fefb472b88a0fbd5710c3a4e0
+  metadata.gz: e1a07542793b7fe4f016907ba28b6e25bc6d887bf0549714b3233350994f561534604a79f1488df8c69efc7cd40f76340a73486938fa5c82fb9424a8f63417d6
+  data.tar.gz: bd3a8cdc13f9d5092a54f91d7e6ef3caa5e7627b2bee607e8203afda5a7991d5356749ce35da48afcd0ae8420e3e43cf6b52f359b37bdfc6feba030111fefb24

data/AGENTS.md

@@ -63,7 +63,7 @@ junior-friendly surface — one-call `convert` — and use AI to keep it current
   key/token in errors. Secret-scan before any release.
 - **The contract is law.** Public method names, signatures and semantics match `docs/SDK_CONTRACT.md`
   across every SDK language. Adapt only to Ruby idiom (see divergences below).
-- **Upload uses the per-job `X-Oc-Token`, never the account key.** There is a spec for this.
+- **Upload uses the per-job `X-Api2convert-Token`, never the account key.** There is a spec for this.
 - **Secret-bearing requests never follow redirects.** The key/token/download-password ride in custom
   `X-Oc-*` headers. `Net::HTTP` does not follow redirects by default — the SDK relies on that and
   only opts the no-secret download path into following redirects. `spec/security` proves the

data/README.md

@@ -1,5 +1,10 @@
 # API2Convert Ruby SDK
 
+[![CI](https://github.com/QaamGo/api2convert-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/QaamGo/api2convert-ruby/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/api2convert)](https://rubygems.org/gems/api2convert)
+![Ruby](https://img.shields.io/badge/ruby-%E2%89%A5%203.1-red)
+![License](https://img.shields.io/badge/license-MIT-green)
+
 Official Ruby SDK for the [API2Convert](https://www.api2convert.com) file-conversion API.
 Convert, compress and transform images, documents, audio, video, ebooks, archives and CAD —
 and run operations like OCR, merge, thumbnail and website capture — in one line of code.
@@ -150,6 +155,44 @@ Live conformance tests hit the real API and are skipped unless a key is present:
 $ API2CONVERT_API_KEY=<your key> bundle exec rake spec:live
 ```
 
+Each guide has a runnable, self-contained example under [`examples/`](examples/),
+and the [live conformance suite](spec/live/conformance_spec.rb) mirrors every one
+of them (same operation, plus assertions) so a published version is always
+verified end to end. It runs automatically against the real API on every release
+tag (see `.github/workflows/live-conformance.yml`).
+
+| # | Example | What it shows |
+|---|---------|---------------|
+| 1 | [`quickstart.rb`](examples/quickstart.rb) | Convert a remote URL, fetch the job, download the output |
+| 2 | [`convert_files.rb`](examples/convert_files.rb) | Browse the conversions catalog, then convert |
+| 3 | [`uploading_files.rb`](examples/uploading_files.rb) | One-call upload + convert of a local file |
+| 4 | [`job_lifecycle.rb`](examples/job_lifecycle.rb) | Drive create → add input → start → wait → outputs by hand |
+| 5 | [`add_watermark.rb`](examples/add_watermark.rb) | Stamp a PDF with an image (two remote inputs) |
+| 6 | [`create_thumbnails.rb`](examples/create_thumbnails.rb) | Render a thumbnail of the first PDF page |
+| 7 | [`compress_files.rb`](examples/compress_files.rb) | Compress an image with the compress operation |
+| 8 | [`create_archives.rb`](examples/create_archives.rb) | Bundle remote files into a ZIP |
+| 9 | [`create_hashes.rb`](examples/create_hashes.rb) | Compute a file's SHA-256 checksum |
+| 10 | [`extract_assets.rb`](examples/extract_assets.rb) | Extract embedded assets from a document |
+| 11 | [`file_analysis.rb`](examples/file_analysis.rb) | Extract file metadata as JSON |
+| 12 | [`compare_files.rb`](examples/compare_files.rb) | Diff two images with compare-image |
+| 13 | [`capture_website.rb`](examples/capture_website.rb) | Screenshot a page with the screenshot engine |
+| 14 | [`audio_operations.rb`](examples/audio_operations.rb) | Re-encode audio to AAC |
+| 15 | [`image_operations.rb`](examples/image_operations.rb) | Resize an image |
+| 16 | [`webhooks.rb`](examples/webhooks.rb) | Start an async job with a callback URL |
+| 17 | [`presets.rb`](examples/presets.rb) | List saved conversion presets |
+| 18 | [`statistics.rb`](examples/statistics.rb) | Read monthly API usage |
+| 19 | [`rate-limits.rb`](examples/rate-limits.rb) | Inspect the account's contracts |
+| 20 | [`authentication.rb`](examples/authentication.rb) | Verify the API key by listing jobs |
+
+A companion [`webhook.rb`](examples/webhook.rb) is a tiny Rack receiver that
+verifies the callback signature — the other side of example 16.
+
+Run any example with your key in the environment:
+
+```console
+$ API2CONVERT_API_KEY=<your key> ruby -Ilib examples/quickstart.rb
+```
+
 If your machine's Ruby is older than the gem targets, run the guardrail on a
 supported Ruby with the bundled `Dockerfile`:
 

data/docs/CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to the API2Convert Ruby SDK are documented here. The five
 official SDKs (PHP, Python, Java, Node.js, Ruby) version together against the
 shared [`SDK_CONTRACT.md`](SDK_CONTRACT.md).
 
-## [Unreleased]
+## [10.2.1] - 2026-07-08
 
-- Initial development; not yet publicly released.
+- Lock-step version bump to keep all API2Convert SDKs on 10.2.1. No library changes since 10.2.0
+  (the redirect / download-password hardening already shipped); added a runnable example per
+  documented guide and expanded the live-conformance suite to seven canonical scenarios.

data/docs/SDK_CONTRACT.md

@@ -10,27 +10,40 @@ Two layers make up an SDK:
   (`openapi/api2convert.openapi.json`); an AI update may freely change it to match the spec.
 - **Hand-authored layer** — the ergonomics below (`convert`, upload, polling, download, webhook
   verification). These flows are **not** in the spec. Their **public signatures and semantics are
-  fixed**: change them only when this document changes, and bump the major version when you do.
+  fixed**: change them only when this document changes. Adding a new **optional** parameter or
+  options-bag field that preserves every existing call site and behavior is an additive **minor**;
+  changing or removing an existing parameter, return type, or documented semantic is a **major**.
 
 > When the two disagree, this contract wins for the hand-authored layer; the spec wins for the
 > derived layer.
 
 ## Protocol facts (the API the SDK speaks)
 
-- Base URL `https://api.api2convert.com/v2`. Auth header `X-Oc-Api-Key: <key>` on account requests.
+- Base URL `https://api.api2convert.com/v2`. Auth header `X-Api2convert-Api-Key: <key>` on account requests (canonical `X-Api2convert-*` names; the legacy `X-Oc-*` headers remain accepted by the API as permanent aliases).
 - **Create job** `POST /jobs` `{ conversion:[{category?,target,options?}], input?:[…], process:bool,
   callback?, notify_status?, download_passwords?:[…] }` → response includes `id`, per-job `token`,
   per-job upload `server`, and `status.code`. `download_passwords` protects every output of the job;
   any password in the list then unlocks its downloads. The API never returns the plaintext back.
 - **Upload** (not in the spec): `POST {server}/upload-file/{job_id}`, `multipart/form-data` field
-  `file`, authenticated with the per-job **`X-Oc-Token`** header — never the account key.
+  `file`, authenticated with the per-job **`X-Api2convert-Token`** header — never the account key.
 - **Add remote input**: `POST /jobs/{id}/input` `{ type:'remote', source:'https://…' }`.
+- **Cloud input** (import from customer storage): `POST /jobs/{id}/input` (or inline in `create`)
+  `{ type:'cloud', source:<provider>, parameters:{…}, credentials:{…} }`, `<provider> ∈ {amazons3,
+  azure, ftp, googlecloud}`; plus `{ type:'gdrive_picker', source:<drive-file-id>,
+  credentials:{token}, content_type? }` for Google Drive. The API validates a cloud descriptor
+  **asynchronously** — it accepts any descriptor on create (`201`) and later fails a bad one on the
+  input (`status:failed`, generic `code 99`); it never echoes a credential value.
+- **Cloud output** (deliver to customer storage): a `conversion[]` may carry
+  `output_target:[{ type:<provider>, parameters:{…}, credentials:{…} }]`, `<provider> ∈ {amazons3,
+  googlecloud, azure, ftp, youtube, gdrive}`. `status` (`waiting|uploading|completed|failed`) is
+  server-set and read-only — never sent on create. The job reaches `completed` only after the upload
+  succeeds (a failed upload → `failed`); an output-target conversion produces **no** local output.
 - **Start**: `PATCH /jobs/{id}` `{ process:true }`.
 - **Poll**: `GET /jobs/{id}` → terminal when `status.code ∈ {completed, failed, canceled}`
   (`failed`/`canceled` are unsuccessful terminals; non-terminal: `created`, `incomplete`,
   `downloading`, `queued`, `processing`, and any unknown code). Poll with backoff; clamp the
   interval to a floor (never busy-loop) and the total wait to a ceiling (never poll unbounded).
-- **Download**: `GET output.uri` — self-contained, no auth; `X-Oc-Download-Password` header if set.
+- **Download**: `GET output.uri` — self-contained, no auth; `X-Api2convert-Download-Password` header if set.
 - **Discover options**: `GET /conversions?category=&target=`.
 - **Errors**: HTTP body `{ "message": "…" }`; job-level `errors[]` / `warnings[]` of
   `{ source, id_source, code, message, details }`.
@@ -64,7 +77,7 @@ Two layers make up an SDK:
 - `contents(downloadPassword?) → binary`, `url() → string`, `output()`, `outputs()`.
 - **Download-password transparency**: a password supplied at conversion time (`convert(...,
   downloadPassword)`) or to `download(output, downloadPassword)` is remembered and sent as the
-  `X-Oc-Download-Password` header on every download from that result/handle — callers do not
+  `X-Api2convert-Download-Password` header on every download from that result/handle — callers do not
   re-supply it. An explicit `downloadPassword` argument to `save()` / `contents()` overrides the
   remembered one for that call.
 
@@ -82,8 +95,39 @@ Two layers make up an SDK:
   missing/wrong signature. Empty secret skips verification.
 - `parse(rawBody) → WebhookEvent` — deserialize without verifying (pre-signed-webhooks).
 
+## Cloud storage connectors
+
+The API imports inputs from and delivers outputs to customer-owned cloud storage. The SDK models the
+wire descriptors above; per-provider keys are **not** validated synchronously server-side, so the
+typed surface is the client's only pre-flight structure.
+
+- **Provider vocabulary** — one shared `CloudProvider` concept (per-language spelling): `amazons3,
+  azure, ftp, gdrive, googlecloud, youtube`. It is **build-side vocabulary only** — read models keep
+  `source`/`type`/`status` as raw strings, and an unknown provider from the server round-trips
+  untyped (never throws).
+- **Cloud input** — a `CloudInput` builder emits `{ type:cloud, source, parameters, credentials }`
+  and hands off to `addInput` / the create path. It ships per-provider named constructors whose
+  signatures carry each provider's required keys **verbatim** (flat/lowercase, as the API expects):
+  `amazonS3(bucket, file, accesskeyid, secretaccesskey)`,
+  `azure(container, file, accountname, accountkey)`, `ftp(host, file, username, password)`,
+  `googleCloud(projectid, bucket, file, keyfile)`. The required keys are **constructor arguments**,
+  not a runtime gate — the builder never rejects a descriptor the permissive server would accept, and
+  a generic `parameters`/`credentials` map stays reachable for optional/forward-compat keys. Google
+  Drive input uses `type:gdrive_picker` (`source` = the Drive file id, token in `credentials.token`),
+  carried by the generic `addInput` raw-map path this wave (no typed builder yet). `gdrive` and
+  `youtube` are **output-only** — they validate as an input `source` but have no downloader.
+- **Cloud output** — an `OutputTarget` model (`type` = a `CloudProvider` + free-form
+  `parameters`/`credentials`) attaches to a conversion, both via `convert`/`convertAsync` (a new
+  optional `outputTargets` control, never merged into the options map) and the raw `jobs().create`
+  conversion map. It serializes `{ type, parameters, credentials }` and **omits `status`** on create.
+  Per-provider output factories are **not** in this wave (their keys live in a separate service and
+  diverge per provider). When any output target is set, `convert` returns the completed `Job` and
+  does **not** download — the conversion has no local output.
+- **Read semantics** — `parameters` and the per-target `status` round-trip on read; `credentials`
+  are **never** surfaced (the API returns them empty; the SDK does not hydrate them).
+
 ## Cross-cutting semantics
-- **Auth**: account key as `X-Oc-Api-Key`; uploads use the per-job token.
+- **Auth**: account key as `X-Api2convert-Api-Key`; uploads use the per-job token.
 - **Retries**: automatically retry with capped, jittered exponential backoff, honoring `Retry-After`
   (delay-seconds or HTTP-date form, clamped to a ceiling). `429` is retried for every method; `5xx`
   and network errors are retried only for idempotent methods (`GET`/`HEAD`/`PUT`/`DELETE`/`OPTIONS`/
@@ -97,3 +141,10 @@ Two layers make up an SDK:
   conversion-failed (carrying the job and its `errors`).
 - **Naming**: method names and option keys are identical across languages, adapted only to each
   language's idiom (camelCase / snake_case).
+- **Credential redaction**: cloud `credentials` travel in the request body — never derive error text
+  from the request body, and mask the **whole `credentials` object** to `[REDACTED]` wherever a value
+  object could surface it: object inspection (`toString`/`repr`/`Debug`/`inspect`), any SDK-emitted
+  request log, and the decoded error body (belt-and-suspenders — the API does not echo credential
+  values). Also mask any `parameters` leaf whose key contains a sensitive token (`token, password,
+  passwd, secret, key, keyfile, credential, passphrase, sas, sig, signature`, case-insensitive).
+  Credentials ride in the plaintext body — user-attached request logging must redact its own.

data/examples/add_watermark.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Add a Watermark — stamp a PDF with an image using two remote inputs.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/add_watermark.rb
+
+require "api2convert"
+
+PDF = "https://example-files.online-convert.com/document/pdf/example.pdf"
+PNG = "https://example-files.online-convert.com/raster%20image/png/example.png"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# Create a job with two inputs (the document and the stamp image) and start it.
+job = client.jobs.create(
+  {
+    "process" => true,
+    "input" => [
+      { "type" => "remote", "source" => PDF },
+      { "type" => "remote", "source" => PNG }
+    ],
+    "conversion" => [
+      {
+        "category" => "document",
+        "target" => "pdf",
+        "options" => { "stamp" => true, "alignment" => "center" }
+      }
+    ]
+  }
+)
+
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+outputs = client.jobs.outputs(job.id)
+outputs.each { |output| puts output.uri }

data/examples/audio_operations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Audio Operations — re-encode a WAV to AAC with explicit codec settings.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/audio_operations.rb
+
+require "api2convert"
+
+WAV = "https://example-files.online-convert.com/audio/wav/example.wav"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(
+  WAV,
+  "aac",
+  { "audio_codec" => "aac", "audio_bitrate" => 192, "channels" => "stereo", "frequency" => 44_100 },
+  category: "audio"
+)
+
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/authentication.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Authentication — verify your API key by listing your jobs.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/authentication.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# A successful, authenticated call returns your jobs (empty on a fresh account).
+jobs = client.jobs.list
+puts "authenticated: #{jobs.length} job(s) visible"

data/examples/capture_website.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Capture a Website — screenshot a page with the screenshot engine.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/capture_website.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+job = client.jobs.create(
+  {
+    "process" => true,
+    "input" => [
+      {
+        "type" => "remote",
+        "source" => "https://www.online-convert.com",
+        "engine" => "screenshot",
+        "options" => { "screen_width" => 1280, "screen_height" => 1024, "device_scale_factor" => 1 }
+      }
+    ],
+    "conversion" => [{ "category" => "image", "target" => "png" }]
+  }
+)
+
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+client.jobs.outputs(job.id).each { |output| puts output.uri }

data/examples/compare_files.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Compare Files — diff two images with the compare-image operation.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/compare_files.rb
+
+require "api2convert"
+
+JPG_SMALL = "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+job = client.jobs.create(
+  {
+    "process" => true,
+    "input" => [
+      { "type" => "remote", "source" => JPG_SMALL },
+      { "type" => "remote", "source" => JPG }
+    ],
+    "conversion" => [
+      {
+        "category" => "operation",
+        "target" => "compare-image",
+        "options" => { "method" => "ssim", "threshold" => 5, "diff_color" => "red" }
+      }
+    ]
+  }
+)
+
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+client.jobs.outputs(job.id).each { |output| puts output.uri }

data/examples/compress_files.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Compress Files — shrink an image with the compress operation.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/compress_files.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(
+  JPG, "compress", { "compression_level" => "high" }, category: "operation"
+)
+
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/convert_files.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Convert Files — browse the conversions catalog, then convert.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/convert_files.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# The whole catalog: every supported target and its options.
+all = client.conversions.list
+puts "#{all.length} conversions available"
+
+# Narrow it down: which conversions produce a PNG image?
+png = client.conversions.list("image", "png")
+puts "#{png.length} way(s) to produce png"
+
+# Now convert a JPG to PNG.
+result = client.convert(JPG, "png", category: "image")
+path = result.save("convert-files-output.png")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/create_archives.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Create Archives — bundle several remote files into a single ZIP.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/create_archives.rb
+
+require "api2convert"
+
+PDF = "https://example-files.online-convert.com/document/pdf/example.pdf"
+PNG = "https://example-files.online-convert.com/raster%20image/png/example.png"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+job = client.jobs.create(
+  {
+    "process" => true,
+    "input" => [
+      { "type" => "remote", "source" => PDF },
+      { "type" => "remote", "source" => PNG }
+    ],
+    "conversion" => [{ "category" => "archive", "target" => "zip" }]
+  }
+)
+
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+outputs = client.jobs.outputs(job.id)
+outputs.each { |output| puts output.uri }

data/examples/create_hashes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Create Hashes — compute the SHA-256 checksum of a remote file.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/create_hashes.rb
+
+require "api2convert"
+
+ZIP = "https://example-files.online-convert.com/archive/zip/example.zip"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(ZIP, "sha256", category: "hash")
+
+# The hash is returned as the output file's contents.
+puts "sha256: #{result.contents}"
+
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/create_thumbnails.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Create Thumbnails — render a thumbnail of the first PDF page.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/create_thumbnails.rb
+
+require "api2convert"
+
+PDF = "https://example-files.online-convert.com/document/pdf/example.pdf"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(
+  PDF,
+  "thumbnail",
+  { "thumbnail_target" => "png", "width" => 300, "pages" => "first", "dpi" => 150 },
+  category: "operation"
+)
+
+# Save into a directory so the API-provided filename is kept.
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/extract_assets.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Extract Assets — pull the embedded assets out of a document.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/extract_assets.rb
+
+require "api2convert"
+
+DOCX = "https://example-files.online-convert.com/document/docx/example.docx"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(DOCX, "extract-assets", category: "operation")
+puts "job #{result.job.id} is #{result.job.status.code}"
+
+result.outputs.each { |output| puts output.uri }

data/examples/file_analysis.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# File Analysis — extract a file's metadata as JSON.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/file_analysis.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(JPG, "json", category: "metadata")
+puts "job #{result.job.id} is #{result.job.status.code}"
+
+# The analysis result is the output file's JSON body.
+puts result.contents

data/examples/image_operations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Image Operations — resize an image with the resize-image operation.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/image_operations.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(
+  JPG,
+  "resize-image",
+  { "width" => 800, "height" => 600, "resize_by" => "px", "resize_handling" => "keep_aspect_ratio_crop" },
+  category: "operation"
+)
+
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/job_lifecycle.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Job Lifecycle — drive create -> add input -> start -> wait -> outputs by hand.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/job_lifecycle.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# Stage a job (process: false) so we can attach inputs before starting.
+job = client.jobs.create(
+  { "process" => false, "conversion" => [{ "category" => "image", "target" => "png" }] }
+)
+puts "created job #{job.id}"
+
+# Attach a remote input, then start processing.
+client.jobs.add_input(job.id, { "type" => "remote", "source" => JPG })
+client.jobs.start(job.id)
+
+# Poll to a terminal status (raises on a failed job by default).
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+# List the produced outputs.
+outputs = client.jobs.outputs(job.id)
+outputs.each { |output| puts output.uri }

data/examples/presets.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Presets — list your saved conversion presets.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/presets.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+presets = client.presets.list(category: "video", target: "mp4")
+puts "#{presets.length} preset(s)"
+
+presets.each { |preset| puts "#{preset.id}: #{preset.name} -> #{preset.target}" }

data/examples/quickstart.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Quickstart — convert a remote file, inspect the job, download the result.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/quickstart.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# One-call convert of a remote URL (create -> poll -> ready to download).
+result = client.convert(JPG, "png", category: "image")
+
+# Fetch the finished job by id and print its status.
+job = client.jobs.get(result.job.id)
+puts "job #{job.id} is #{job.status.code}"
+
+# Download the produced output.
+path = result.save("quickstart-output.png")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/rate_limits.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Rate Limits — inspect your account's contracts (quotas and limits).
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/rate_limits.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+contracts = client.contracts.get
+puts contracts.inspect

data/examples/statistics.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Statistics — read your API usage for a given month.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/statistics.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+stats = client.stats.month("2026-06")
+puts stats.inspect

data/examples/uploading_files.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Uploading Files — convert a local file in one call (convert() uploads it).
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/uploading_files.rb
+
+require "api2convert"
+require "base64"
+require "tmpdir"
+
+# A minimal valid 1x1 PNG so the example needs no binary fixture on disk.
+ONE_PX_PNG = Base64.decode64(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
+)
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+Dir.mktmpdir("a2c-upload") do |dir|
+  source = File.join(dir, "pixel.png")
+  File.binwrite(source, ONE_PX_PNG)
+
+  # Hand convert() a local path — it stages the job, uploads the file to the
+  # per-job upload server, starts it and polls to completion.
+  result = client.convert(source, "png", category: "image")
+  path = result.save("uploading-files-output.png")
+  puts "saved #{path} (#{File.size(path)} bytes)"
+end