Skip to content

Vermillio SDK

The Vermillio SDK is a Python library designed to allow for developers to programmatically interact with the Vermillio platform.

Installation

Vermillio SDK is published as a Python package and can be installed ideally within a virtual environment. Vermillio SDK requires Python 3.9+.

pip install vermillio-sdk

uv add vermillio-sdk

Core SDK

The vermillio-sdk-core library has the following dependencies: 

"asyncio>=3,<4",
"pydantic>=2,<3",
"requests>=2,<3",

Configuration

All of the classes are driven by a vermillio.sdk.core.VermillioConfig object which holds all of the required configuration parameters in order to interact with the Vermillio Endpoints. It can be initialized a couple of different ways:

from vermillio.sdk.core import VermillioConfig
# Load configuration from env variables, expecting the following:
# VERMILLIO_SDK_CLIENT_ID     : your client id
# VERMILLIO_SDK_CLIENT_SECRET : your client secret
# Environment prefix can 'VERMILLIO_SDK' can also be customized
config = VermillioConfig.from_env() 
# Create directly in python, assuming you get `client_id` and `client_secret` from other methods
client_id, client_secret = get_client_credentials_from_secret()
config = VermillioConfig.credentials(client_id, client_secret)

This VermillioConfig should be used in all of the subsequent classes to interact with API Endpoints.

Authentication

All of the classes provided should transparently handle authenticating requests. Any requests made to endpoints will automatically acquire an access_token if necessary before executing the API requests. The access_token is cached in the client until it is near expiration, and a new access_token is fetched, so it is preferred to use the same instance of the client when possible to avoid having to fetch access_token with every request.

Asset Management

from vermillio.sdk.core import VermillioAssets
assets = VermillioAssets(config)

# list the assets that are licensed
for asset in assets.list():
  print(f"Asset {asset.title} available for download.")

# fetch a specific asset
parent_asset = assets.get('source ip asset id')
print(f"Asset {parent_asset.title} is being used to derive content.")

# download a source asset
manifest = assets.download(parent_asset.id, '/path/to/directory')

# upload a new asset
assets.upload('/path/to/file.png', 'Image', 'Derived content', parent_asset.id)

The VermillioAssets class also provides some convenience methods for common operations:

Bulk Asset Download

There are two different helper functions for bulk downloading of assets for a particular license: one zipped and one unzipped, both to a local directory path. Zip will also provide a manifest of the files downloaded and what asset, media and license they come from along with a brief title and description for each asset. In each case, files will be downloaded to a standard hierarchy on your local destination, so it is often helpful to use the same directory path for each bulk download if you have multiple licenses.

Downloading zipped: 

assets.bulk_download_license_zip('license_id', '/path/to/directory')

Downloading unzipped (many individual files): 

assets.bulk_download_license('license_id', '/path/to/directory')

Bulk Asset Upload

In cases when a user has many assets they want to upload, perhaps an entire directory, there is a separate asset-uploader tool which utilizes and depends on the core Vermillio SDK. The authorization and config utilize the same credentials and environment variables as the rest of the SDK. This tool has two primary functions:

  1. scanning local or cloud storage for assets to be registered and
  2. uploading media files to match those registered assets.

This tool also provides mechanisms for resuming disrupted scans or uploads. Below is an example of the most simple case of scanning and uploading everything in a path:

from vermillio.asset_uploader.uploader import AssetUploader

uploader = AssetUploader()
upload = uploader.upload_folder('path/to/local/or/cloud/directory')

for local, entry in upload['path_mapping'].items():
   print(f"local path: {local} -> {entry['remote_path']}:{entry['status']}")

### to resume a discontinued upload

uploader.upload_folder('path/to/local/or/cloud/directory', upload['id'])

Usage Management

from vermillio.sdk.core import VermillioTracking
tracking = VermillioTracking(config)

# report asset usage
tracking.usage('trained model', [parent1.id, parent2.id], data={"model_version": "v1.0"})

# report bulk asset usage
tracking.usage('generated audio', [parent1.id, parent2.id], num_audio_generated, {"model_version": "v2.1"})

# report publishing assets to 
tracking.action('Publish', [asset.id], published_url)

# report revenue
tracking.revenue([asset.id], 5.0, 'USD', transaction_id)