lamina-sdk

Async-first Python SDK for Lamina video generation. Duration values are whole minutes, from 1 to 5.

Install

pip install lamina-sdk

Python 3.11 or newer is required.

Quick Start

from lamina import simi

async with simi(api_key="lamina_live_your_key") as client:
    video = await client.generate("A blue sphere moving across white background", duration=1)
    await video.save("out.mp4")

You can also set LAMINA_API_KEY and call simi() with no arguments. Requests go to https://api.laminalabs.ai unless you set base_url=....

Submit And Stream Events

from lamina import simi

async with simi(api_key="lamina_live_your_key") as client:
    job = await client.submit_async(
        "A blue sphere moving across white background",
        duration=1,
        document="brief.txt",
    )

    async for event in client.stream_events(job):
        if event.is_progress():
            print(event.payload["phase"], event.payload.get("progress"))
        else:
            print(event.type)

Events use a small public vocabulary: progress, chunk, output, job.completed, job.failed, and job.cancelled. If the stream drops, the SDK reconnects and resumes from the last sequence it delivered, so you will not see an event twice.

Callback Style

from lamina import simi

async with simi(api_key="lamina_live_your_key") as lamina:
    job = await lamina.submit_async("A narrated lesson about derivatives")
    job.onstream(lambda event: print(event.type))
    job.oncompletion(lambda video: print(f"Ready: {video.job_id}"))
    await job.wait()

Listing And Cancelling

async with simi() as client:
    jobs = await client.list_jobs(limit=10, status="complete")
    for job in jobs:
        print(job.job_id, job.status)

    await client.cancel("job_abc123")

Organizations And Billing

If your key belongs to an organization manager and carries the organizations:write scope, you can provision managed end-users, mint embed tokens for them, and schedule generation on their behalf. This is the path for mirroring your own users into Lamina.

async with simi() as client:
    created = await client.organizations.create_managed_user(
        org_id, username="ada", password="a-strong-password"
    )
    print(created.login_email)

    embed = await client.organizations.create_embed_token(org_id, "ada")
    # Hand embed.token to your frontend to render the player as that user.

    await client.organizations.create_schedule(
        org_id,
        "ada",
        prompt="Weekly product recap",
        scheduled_at="2026-09-01T15:00:00Z",
        duration=2,
        language="English",
    )

With the billing:read scope you can read credits and usage, which is what you need to meter and bill your own customers.

async with simi() as client:
    credits = await client.billing.credits()
    print(credits.available_credits, credits.credit_buckets)

    usage = await client.billing.usage(limit=100)

Creating or renaming an organization, and adding or removing human members, requires a signed-in dashboard session and cannot be done with an API key.

Retries And Errors

Reads are retried automatically on 429 and 5xx with exponential backoff, honouring retry-after. A submit is only retried when you pass an idempotency_key, so a retry can never create a second video.

from lamina import LaminaRateLimitError, simi

async with simi(max_retries=3) as client:
    try:
        job = await client.submit_async("Explain our refund policy", idempotency_key="req-1")
    except LaminaRateLimitError as error:
        print(error.status, error.retry_after, error.request_id)

Errors all derive from LaminaError: LaminaAPIError (with status, request_id, and retry_after), LaminaRateLimitError, LaminaJobError, LaminaStreamError, LaminaDownloadError, and LaminaCancelledError.

Public API

• job = lamina.submit(prompt, *, duration=1, document=None, language=None, idempotency_key=None)
• job = await lamina.submit_async(...) — same arguments
• video = await lamina.generate(...) — same arguments, waits for completion
• jobs = await lamina.list_jobs(*, limit=20, cursor=None, status=None)
• state = await lamina.cancel(job_or_id)
• playback = await lamina.get_playback(job_or_video_or_id)
• await lamina.save(job_or_video, path)
• await lamina.aclose() or async with simi()
• api_key is required in simi(...) unless LAMINA_API_KEY is set.
• duration is in minutes (1-5).

Use async with in async code. with is supported only outside a running event loop and will tell you so if you get it wrong.