Consumer SDK Reference

The convilyn Python package — for API callers (apps, agents, scripts that use Convilyn). Everything imported from convilyn at the top level is part of the supported API.

For workflow authors building tool servers and workflow specs, see the Author SDK Reference instead — that's the convilyn-sdk package.

What's in the SDK

Page	Contents
Clients	`Convilyn` (sync) and `AsyncConvilyn` (async) — the SDK entry points
Exceptions	The full `ConvilynError` hierarchy — every exception the SDK can raise
Types	Pydantic data models returned by the SDK (`File`, `ConvertJob`, `GoalJob`, ...)

Quick map

from convilyn import (
    # Clients
    Convilyn,
    AsyncConvilyn,

    # Exceptions — base + transport
    ConvilynError,            # base
    AuthError,
    APIError,
    RateLimitError,
    RetryExhaustedError,
    S3UploadError,
    WebSocketError,

    # Exceptions — billing (subclass APIError; new in v1.0.0)
    PlanRequiredError,
    QuotaExceededError,

    # Exceptions — jobs
    JobFailedError,
    JobTimeoutError,
    GoalJobFailedError,
    GoalJobTimeoutError,

    # Data models — files / convert
    File,
    ResultFile,
    ConvertJob,
    JobError,

    # Data models — goal lane
    GoalJob,
    GoalEvent,
    PendingSlot,

    # Data models — workflows marketplace
    Workflow,
    WorkflowSummary,
    WorkflowSearchPage,
    WorkflowStats,
    LikeResponse,

    # Data models — billing
    Plan,
    PlanTier,
    QuotaCheck,
    QuotaState,
    CostEstimate,
    ToolCostEstimate,

    # Retry policy primitives
    RetryPolicy,
    ExponentialBackoffRetry,
    NoRetry,
)

Versioning

The SDK follows semantic versioning. Anything in convilyn.__all__ is part of the supported public surface; anything starting with _ (e.g. convilyn._internal) is private and may change between releases.

Need something not listed here?

The CLI ships an api sub-command that calls any endpoint with the same auth, retry, and idempotency behaviour as the high-level methods. See the Quickstart §6 for examples.