vmodal 0.1.0

Thin Python SDK for the VMX external API

vmodal Python SDK

Async-first Python SDK for the VMX external API. The SDK is distributed from GitHub under the MIT License; it is not published to PyPI.

Install

python -m pip install "git+https://github.com/v-modal/vmodal_sdk.git#subdirectory=sdk_python"

Upgrade or uninstall:

python -m pip install --upgrade "git+https://github.com/v-modal/vmodal_sdk.git#subdirectory=sdk_python"
python -m pip uninstall vmodal

For a reproducible deployment, replace the default branch with a release tag:

python -m pip install "git+https://github.com/v-modal/vmodal_sdk.git@TAG#subdirectory=sdk_python"

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)

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

Use the SDK

import asyncio
from vmodal import Client, SyncClient

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())

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

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.