autolecture — Python SDK

Official Python SDK for AutoLecture — author explainer videos as a .tex source, render them on the server, download an mp4. The SDK wraps the v2 HTTP API end-to-end: projects, assets, tex source, compile jobs (with polling), final-video download, voice clone, billing-adjacent reads.

The SDK is the supported way to drive AutoLecture from outside the web UI — built for CLIs, Claude Code skills, and any service-to-service use case where a JWT login flow doesn't fit.

Install

pip install autolecture

Python 3.10+. The SDK depends only on httpx>=0.27.

Auth

Every call needs an API key. To mint one:

1. Sign in at https://autolecture.ai.
2. Open https://autolecture.ai/account, find the API Keys section.
3. Click Generate — copy the al_live_… string immediately, it's only shown once.

Pass it to the Client constructor (or read from AUTOLECTURE_API_KEY env var in your own code — the SDK doesn't read env vars itself, that's caller-side).

Quickstart

from pathlib import Path
from autolecture import Client

with Client(api_key="al_live_…") as al:
    # 1. Create a project.
    project = al.create_project(name="My first AutoLecture video")
    pid = project["id"]

    # 2. Upload a script + any assets you want to reference.
    al.upload_asset(pid, Path("./recording.mp3"))

    # 3. Write the VideoTeX source. See https://autolecture.ai/docs/dsl.
    al.put_tex(pid, "main.tex", r"""
        \title{Demo}
        \aspect{16:9}
        \begin{videotex}
            \begin{view}
                \say{Hello, AutoLecture!}
                \image[engine=gemini]{a duck explaining a concept on a chalkboard}
            \end{view}
        \end{videotex}
    """.strip())

    # 4. Compile. `compile()` blocks until the job terminates;
    #    `on_progress` fires after each poll for progress UI.
    job = al.compile(
        pid,
        on_progress=lambda j: print(f"  [{j['blocks_done']}/{j['blocks_total'] or '?'}] {j['status']}"),
    )
    print(f"Compile finished — {job['actual_cost_credits']} ✦ spent")

    # 5. Download the final mp4.
    al.download_preview(pid, dest="./out.mp4")
    print("Saved to ./out.mp4")

Errors

Every SDK exception inherits from AutoLectureError. The common subclasses carry the backend's structured-error fields as attributes:

from autolecture import (
    AutoLectureError, AuthenticationError, PermissionError,
    QuotaExceededError, InsufficientCreditsError, RateLimitError,
    CompileFailedError, NotFoundError, APIError,
)

try:
    al.compile(pid)
except InsufficientCreditsError as e:
    print(f"Need {e.shortfall} more ✦. Balance: {e.balance}, needed: {e.needed}")
except QuotaExceededError as e:
    print(f"Plan {e.plan} caps at {e.limit} projects (you have {e.used}).")
except CompileFailedError as e:
    print(f"Render failed:\n{e.error_log}")
except AutoLectureError as e:
    # Catch-all — every SDK error inherits from this.
    print(f"[{e.code}] {e.message}")

For a less specific error (e.g. an HTTP status we don't have a subclass for yet), you get a generic APIError with .status_code and .code.

What's in Client

Area	Methods
Projects	list_projects / create_project / create_project_from_zip / get_project / update_project / delete_project / archive_project / unarchive_project / duplicate_project
Tex source	get_tex / put_tex
Assets	upload_asset / list_assets / delete_asset
Compile	compile (high-level + polling) / start_compile / get_compile_job / cancel_compile
Preview	download_preview / download_block_preview
Voice clone	upload_voice_sample / get_voice_sample / delete_voice_sample
Account	get_balance / get_quota / get_usage
API key	mint_api_key / get_api_key_status / revoke_api_key

See the docstrings — every public method maps 1:1 to a documented HTTP endpoint at https://autolecture.ai/api/v2/....

Pointing at a different server

Most users won't need this. For local development or staging:

al = Client(api_key="al_live_…", base_url="https://dev.autolecture.ai")
# or
al = Client(api_key="al_live_…", base_url="http://localhost:8000")

Async?

v0.1 is sync-only — httpx.Client, no await. An async variant (AsyncClient) is on the roadmap for v0.2 if there's demand; the typical "script in a Claude Code skill" use case is sync-friendly, so async hasn't been a priority.

Development

git clone https://github.com/scao7/autolecture-python
cd autolecture-python
pip install -e ".[dev]"
pytest -q
ruff check src tests
mypy src

Tests use respx to mock the backend HTTP — nothing reaches the network.

License

MIT — see LICENSE.

Links

• AutoLecture web app — https://autolecture.ai
• DSL reference — https://autolecture.ai/docs/dsl
• Companion Claude Code skill — https://github.com/scao7/autolecture-claude-skill
• Backend repo — https://github.com/scao7/autolecture