vmodal Python SDK

Async-first Python SDK for the VMX external API. The SDK is published on PyPI under the MIT License.

Install

pip install vmodal

Upgrade or uninstall:

pip install --upgrade vmodal
pip uninstall vmodal

Configure authentication

Obtain an API key through your v-modal account administrator. API keys are Bearer credentials: keep them out of source control, rotate them in the account administration surface, and replace VMODAL_API_KEY after a rotation.

export VMODAL_API_KEY=ak_xxx

Client.from_env() and SyncClient.from_env() select the hosted public service and resolve the account identity associated with the key.

An invalid or expired token raises AuthError with status 401. A valid token without the required permission raises ApiError with status 403. Rotate a token by replacing the environment value. Cached identity information is encrypted and stored in the operating system's user-cache directory.

Verify authentication

from vmodal import SyncClient

client = SyncClient.from_env()
print(client.auth())

Successful output:

VMODAL_API_KEY is valid, authenticated correctly (user_id=user_abc)

Simple usage examples

Check authentication and API health:

from vmodal import SyncClient

client = SyncClient.from_env()
print(client.auth())
print(client.health())

Search videos:

from vmodal import SyncClient

client = SyncClient.from_env()
result = client.searches.search_video(
    query_text="alien",
    mode="vid_file",
    group_name="newsalien2",
    stream_name="astream",
    search_sources=["image"],
    search_combine_mode="union",
    limit=10,
    image_emb_score_min=1.5,
    tracking_id="readme_search",
)
print(result)

Upload a video:

from vmodal import SyncClient

client = SyncClient.from_env()
result = client.collections.video_upload(
    filepath_local="/path/to/video.mp4",
    collection_name="newsalien2",
    sub_collection_name="astream",
    mode="vid_file",
    modality="vid_raw",
)
print(result)

Files of 100 MiB or more automatically use resumable multipart upload (64 MiB parts, four concurrent part uploads). To force it for a smaller file or tune the part size:

result = client.collections.video_upload(
    "/path/to/video.mp4",
    "newsalien2",
    "astream",
    multipart=True,
    part_size_bytes=64 * 1024 * 1024,
)

More examples

• Authentication check
• Full SDK usage
• Video upload, indexation, and color search
• Search examples

Async usage

import asyncio
from vmodal import Client

async def main():
    async with Client.from_env() as client:
        return await client.searches.search_video(
            query_text="example",
            mode="vid_file",
            group_name="agroup",
        )

asyncio.run(main())

CLI

vmodal health
vmodal search_video --query_text=example --group_name=agroup --mode=vid_file
python -m vmodal.cli video_upload --filepath_local=/path/to/video.mp4 --collection_name=agroup --sub_collection_name=astream

See the endpoint map, configuration reference, and support policy.