From install to first conversion in five minutes.

1. Install

uv add --prerelease=allow convilyn   # or: pip install --pre convilyn

2. Convert a file right now — no key needed

Before any of the account setup: the Python package converts files on your own machine, with no upload and no network call.

uv add "convilyn[documents]"
convilyn local convert report.docx --to md

from convilyn import local
 
result = local.convert("report.docx", to="md")
print(result.output)  # report.md

Headings, lists and tables survive; embedded images land in an assets/ folder beside the Markdown. Nothing here reads CONVILYN_API_KEY or consumes quota — see offline conversion for the full picture, including how to ask what this machine can convert before you try.

3. Get an API key

Everything from here talks to the platform, and that needs a key.

Sign up, then create an API key on your Settings → API page (login required — it also manages billing and quota). The key starts with ck_ and is shown only once. Export it so the SDK and CLI both pick it up:

export CONVILYN_API_KEY=ck_...

4. Verify your setup

The convilyn package ships a doctor command that checks your environment before you spend an API call:

$ convilyn doctor --ping
[OK] convilyn SDK: 1.6.0b1
[OK] CONVILYN_API_KEY: ck_xx…XXXX
[OK] Backend health: 200 OK
[OK] Account tier: tier=free
All checks passed.

5. Convert a file in the cloud

The five-line hello-world: upload, convert, download.

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")

A failed job raises a typed JobFailed error; an elapsed deadline raises a JobTimeout error. Catch the base error type to handle them uniformly — see each SDK's error reference.

Or, the same conversion from the convilyn CLI:

convilyn convert report.docx --to pdf -o report.pdf
convilyn convert report.docx --to pdf --json | jq .   # machine-readable
convilyn convert report.docx --to pdf --dry-run        # preview, no API call

6. Run an agentic workflow

Goal workflows are agentic — the backend assembles a multi-step plan, calls MCP tools, and may pause to ask for input. run starts a job and waits until it finishes or pauses for human input.

job = client.goals.run(workflow_id="doc_analyzer", files=["file_abc"])
if job.needs_input:
    slot = job.pending_slots[0]
    job = client.goals.fill_slot(job.job_spec_id, slot_id=slot.slot_id, value="March 2026")
    job = client.goals.confirm(job.job_spec_id)
    job = client.goals.wait(job.job_spec_id)
print(job.status)

7. Pre-flight plan + quota

Some actions (fork a public workflow, publish your own tool server, run an expensive goal workflow job) need a paid plan. Check before you call:

estimate = client.account.get_quota(max_iterations=25)
print(estimate.estimated_usd, estimate.quota_check.state)  # "ok" | "soft_limit" | "quota_exceeded"

When the verdict isn't ok, the SDK raises a typed PlanRequiredError / QuotaExceededError carrying the upgrade / top-up URL.

Where to go next