Python

The distribution on PyPI is velo-sdk and the import package is velo. It requires Python 3.9 or newer and declares no dependencies: the transport is urllib.request from the standard library, so installing it adds one thing to your lockfile and nothing to your audit surface.

• 53 methods on VeloClient, one per project endpoint, and the same 53 on AsyncVeloClient under identical names and signatures.
• Responses are frozen dataclasses with snake_case fields that match the wire exactly, so room.empty_timeout_seconds is the empty_timeout_seconds the API returns. Timestamps stay as RFC 3339 strings rather than being parsed into datetime, so nothing is lost or guessed on the way in.
• Nested request shapes are TypedDicts: TokenPermissions, RoleInput, TemplateSettingsInput, RecordingDestinationConfig and RtmpDestinationConfig. Everything else is a keyword argument.
• The package ships py.typed, so mypy and pyright read the annotations with no stubs.

One package, no transitive dependencies to resolve.

pip install velo-sdk

The names differ on purpose, which is the usual place to trip: you install velo-sdk and you import velo.

The key is the only positional argument. Read it from the environment, never from source, so the value that grants control of your project is never in a diff.

import os

from velo import VeloClient

client = VeloClient(os.environ["VELO_API_KEY"])

• A key that is blank, not a string, or does not start with vk_ raises ValueError at construction rather than failing on the first request. Room tokens and console session tokens are rejected here on purpose: they are not project keys.
• Surrounding whitespace is trimmed before that check, so a key pasted with a trailing newline still works.
• AsyncVeloClient takes exactly the same arguments and performs exactly the same validation.

Everything else is keyword only.

client = VeloClient(
    os.environ["VELO_API_KEY"],
    base_url="https://api.usevelo.xyz",
    timeout=15.0,
    default_headers={"X-Trace": trace_id},
)

Every request carries Authorization: Bearer, Accept: application/json and a User-Agent of velo-python. A request with a body adds Content-Type: application/json, and an idempotent call adds Idempotency-Key. Path values are percent encoded with no safe characters, so a room named a/b c becomes a%2Fb%20c rather than a second path segment.

Three steps, and only the third one produces something a client may hold: create the room, mint a room token for one identity, and return the token and its url. The key stays in the process.

import os

from velo import VeloClient

client = VeloClient(os.environ["VELO_API_KEY"])

room = client.create_room(
    "consultation-42",
    max_participants=8,
    idempotency_key="consultation-42-create",
)


def velo_token():
    token = client.create_token(
        room=room.name,
        identity="patient-1187",
        name="Amina",
        ttl_seconds=3600,
        role="patient",
    )
    return {"token": token.token, "url": token.url}

create_token returns a Token carrying token, url, expires_at, and, when the room has a template, role and publish_profile. Send the first two to the browser or the phone and nothing else.

AsyncVeloClient exposes the same method names and the same signatures as VeloClient, awaitable. Swapping one for the other is an await and nothing else, and the test suite asserts that the two surfaces stay identical signature for signature.

import asyncio
import os

from velo import AsyncVeloClient


async def main() -> None:
    client = AsyncVeloClient(os.environ["VELO_API_KEY"])

    room = await client.create_room("consultation-42", max_participants=8)
    token = await client.create_token(
        room=room.name,
        identity="patient-1187",
        role="patient",
    )
    print(token.token, token.url, token.expires_at)


asyncio.run(main())

The same 53 calls the Go SDK exposes, in Python naming. This is a map, not a reference: every method maps to one endpoint, and the full request and response shapes live in the REST API reference.

• Rooms and tokens: create_room, list_rooms, get_room, delete_room, create_token.
• Participants and moderation: list_participants, get_participant, remove_participant, mute_track, send_data, change_participant_role, list_role_changes.
• Sessions: list_sessions, get_session, list_room_sessions.
• Recordings and broadcasts: start_recording, list_recordings, list_room_recordings, get_recording, stop_recording, start_broadcast, list_broadcasts, get_broadcast, stop_broadcast.
• Ingress: create_ingress, list_ingresses, get_ingress, delete_ingress.
• Templates, roles and destinations: create_template, list_templates, get_template, update_template, delete_template, get_template_settings, update_template_settings, put_role, get_role, delete_role, create_destination, list_destinations, get_destination, update_destination, delete_destination.
• Room codes: create_room_code, list_room_codes, delete_room_code. This is how a client joins without ever seeing a key.
• Webhooks: create_webhook_endpoint, list_webhook_endpoints, delete_webhook_endpoint, list_webhook_deliveries, retry_webhook_delivery.
• Billing: get_usage and get_plan. The from query parameter the API takes is spelled from_ in Python, because from is a keyword: client.get_usage(from_="2026-07-01", to="2026-07-31").

send_data accepts bytes, bytearray, memoryview or str, and base64 encodes it for the wire, so pass your payload as it is. A response with no body, such as a 204 from a delete, comes back as None.

List calls return a Page, a frozen dataclass carrying items, limit and offset as the server applied them, and has_more. It is iterable and has a length, so you can loop the page itself and reach for page.items only when you want the list.

page = client.list_sessions(room="consultation-42", active=True, limit=100)

while True:
    for session in page:
        print(session.participant_identity, session.duration_seconds)
    if not page.has_more:
        break
    page = client.list_sessions(
        room="consultation-42",
        active=True,
        limit=page.limit,
        offset=page.offset + page.limit,
    )

• A filter left as None is dropped from the query string entirely, so an unset limit takes the server default rather than sending a literal zero.
• Booleans are serialised as true and false, so active=True reaches the API as active=true.
• list_destinations is the one exception to the shape: the endpoint returns a plain array, so it returns list[Destination].

Calls that create or trigger something accept idempotency_key=, sent as the Idempotency-Key header. Replaying the same key with the same body replays the original response instead of acting twice; replaying it with a different body is rejected with idempotency_key_reuse. Leaving it as None means the header is not sent at all.

room = client.create_room(
    "consultation-42",
    idempotency_key="consultation-42-create",
)

recording = client.stop_recording(egress_id, idempotency_key=f"stop-{egress_id}")

• It is available on create_room, create_token, mute_track, send_data, change_participant_role, start_recording, stop_recording, start_broadcast, stop_broadcast, create_template, create_destination, create_room_code, create_webhook_endpoint and retry_webhook_delivery.
• Nothing else takes one. create_ingress, the update calls and put_role have no idempotency parameter, because they are already defined by the state they set.
• The async client takes the same keyword in the same position, because its signatures are the sync ones.

Every API failure arrives in one envelope, and the package raises a class you can catch rather than returning a response to inspect. Everything it raises descends from VeloError.

{
  "error": {
    "code": "quota_exceeded",
    "message": "monthly participant minutes exhausted"
  }
}

from velo import (
    VeloAPIError,
    VeloConnectionError,
    VeloPermissionDeniedError,
    VeloQuotaExceededError,
    VeloRateLimitedError,
)

try:
    recording = client.start_recording("consultation-42", type="room_composite")
except VeloQuotaExceededError as exc:
    show_upgrade_prompt(exc.code, exc.message)
except VeloRateLimitedError:
    retry_after_backoff()
except VeloPermissionDeniedError as exc:
    disable_control(exc.permission)
except VeloAPIError as exc:
    report(exc.status, exc.code, exc.field, exc.message)
except VeloConnectionError as exc:
    log.warning("velo never answered: %s", exc.cause)

VeloError

The base class for everything this package raises. Catch it to catch all of them.

VeloAPIError

Any non-2xx response. It carries status, code, message, field and the parsed body.

VeloQuotaExceededError

Any 402, such as quota_exceeded, room_limit_reached, insufficient_balance or feature_not_in_plan. A plan limit is an expected state, not a bug, so it gets its own class.

VeloPermissionDeniedError

Any 403. Its permission property aliases field, which names the grant that was missing, so a UI can disable that one control.

VeloNotFoundError

Any 404.

VeloRateLimitedError

Any 429. Back off and retry rather than surfacing it.

VeloConnectionError

The request never produced an HTTP response, or the response body was not valid JSON. It carries message and the original exception as cause.

• The four status classes all extend VeloAPIError, so order your except clauses narrowest first, as the example above does.
• Status is what selects the class, not the code, so a new 402 code still arrives as VeloQuotaExceededError.
• When a response is not a Velo envelope, code becomes http_{status} and message holds the first 512 characters of the body.

A quota failure is an expected state: the project is live and out of minutes. Branch on it first, tell the person what happened, and leave the retry loop for VeloRateLimitedError. Not every 402 is about minutes: recording and live streaming are not on the free plan, so on a free project start_recording, start_broadcast, create_ingress and create_destination raise VeloQuotaExceededError with the code feature_not_in_plan and the refused feature in field. The list, get, stop and delete calls are never refused for that reason. Full status meanings are in Authentication.

• The REST API is the full surface every method here maps onto, request body by request body.
• Webhooks is how your Python service hears about a room ending or a recording completing without polling list_sessions.
• The Web SDK is what receives the token this package mints. The Android, iOS, Flutter and React Native packages take the same token.
• The Go SDK is the same surface for a Go backend, method for method.