vmodal 0.1.1

Thin Python SDK for the VMX external API

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

This is the complete public configuration. Client.from_env() and SyncClient.from_env() select the production gateway and call /api/v1/auth/me to derive and cache user_id, tenant_id, and email from 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; the encrypted identity cache is token-scoped and stored in the operating system's user-cache directory.

The old VMODAL_API_TOKEN and TEST_CLIENT_* names remain private test-only compatibility aliases. They are not public configuration inputs.

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

These examples are taken from examples/auth_check.py and examples/app_full_usage.py.

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)

More examples

• Authentication check
• Full SDK usage
• Video upload, indexation, and color search
• Search examples
• Sample end-to-end flow
• SDK application example
• Video search application

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.