Convilyn docs

SDK quickstart

From pip install to a converted file in under five minutes. By the end you'll have run the same workflow from both Python and the shell.

1. Install

pip install convilyn

A single install gives you the Python library and the convilyn binary — no separate package, no extras needed.

Requires Python 3.10 or later.

2. Get an API key

Sign up for a developer account and copy your cvl_... API key from the dashboard. Export it once so the SDK and CLI both pick it up:

export CONVILYN_API_KEY=cvl_...

The CLI also accepts an explicit --api-key flag, but the environment variable is the recommended default — it works for both Python scripts and one-off shell commands.

3. Verify your setup

Run the doctor command first to catch any environment issues before hitting the API:

$ convilyn doctor
✓ [OK] Python: 3.11.9
✓ [OK] convilyn SDK: 0.1.0
✓ [OK] httpx: 0.28.1
✓ [OK] pydantic: 2.13.4
✓ [OK] click: 8.3.1
✓ [OK] CONVILYN_API_KEY: cvl_xx…XXXX
✓ [OK] CONVILYN_BASE_URL: https://api.convilyn.com (default)
All checks passed.

Add --ping to also probe the backend's health endpoint:

convilyn doctor --ping

4. Convert a file (Python)

The five-line hello-world:

from convilyn import Convilyn

client = Convilyn()
file = client.files.upload("report.docx")
job = client.convert.create_and_wait(file=file, target_format="pdf")
client.convert.download_to(job, to="report.pdf")

What just happened:

  1. files.upload got a presigned upload URL from the API, streamed the file, and registered the upload with the backend.
  2. convert.create_and_wait started a document conversion job and polled until it finished (or failed).
  3. convert.download_to fetched the presigned download URL from the completed job and wrote the bytes to disk.

If any step fails (auth, transport, conversion error) you get a typed exception: AuthError, APIError, RetryExhaustedError, JobFailedError, JobTimeoutError. Catch the base ConvilynError to handle them all uniformly.

5. Convert a file (CLI)

The same workflow as a single command:

$ convilyn convert report.docx --to pdf
↑ Uploading report.docx (32.4 KiB)
▶ Creating conversion → pdf
… Converting… 100%
↓ Downloaded report.pdf
✓ report.pdf (28.1 KiB)

Pipe-friendly mode for shell pipelines and agents:

$ convilyn convert report.docx --to pdf --json | jq .
{
  "command": "convert",
  "file_id": "file_abc",
  "job_id": "job_xyz",
  "status": "completed",
  "output_path": "report.pdf",
  "output_size_bytes": 28798,
  "elapsed_seconds": 3.4
}

Safe preview before spending an API call:

$ convilyn convert report.docx --to pdf --dry-run
↑ [dry-run] Would upload: report.docx (32400 B, application/vnd.openxmlformats-officedocument.wordprocessingml.document)
▶ [dry-run] Would POST /api/v1/jobs
↓ [dry-run] Would download to: report.pdf
[dry-run] No API calls made.

6. Call any endpoint (escape hatch)

The CLI ships a gh-style api sub-command for endpoints the SDK has not wrapped yet. Same auth, retry, and idempotency behaviour as the high-level commands.

# Inspect a job:
convilyn api GET /api/v1/jobs/job_xyz --json | jq .

# Hit an arbitrary endpoint:
convilyn api POST /api/v1/some/new/endpoint --data '{"x": 1}'

# Pipe a body in from a file or stdin:
convilyn api POST /api/v1/echo --input body.json
echo '{"x": 1}' | convilyn api POST /api/v1/echo --input -

Pair with --include to see the status line and headers (curl -i style), or -o file to write the body to disk silently.

7. Going further

  • Async API: use AsyncConvilyn if you're inside an event loop; every method has an async counterpart with the same signature.
  • Custom retry policy: pass retry_policy= to the constructor to replace the default exponential backoff. The protocol is two methods: should_retry() and next_delay().
  • Bring-your-own transport: every resource accepts an HTTPClient via the constructor so you can inject mock transports for testing.

Common questions

Which formats are supported? Document conversion between DOCX / PDF / PPTX / TXT / HTML / Markdown / RTF / ODT today. Additional processor types (image conversion, OCR, media processing, PDF operations, compression) ship as additional SDK methods in subsequent releases.

What if a job takes more than five minutes? The default convert.create_and_wait timeout is five minutes; override with timeout=.... After timeout the job is still alive on the backend — call client.convert.retrieve(job.job_id) to fetch its current state.

How do I get HTTP traces for debugging? Set CONVILYN_DEBUG=1 to surface full repr / stacktraces from CLI errors. The SDK uses httpx underneath, so standard httpx debug hooks work via the underlying client.