Guides
Vi Dashboard
  1. Developer Tools
  2. Vi SDK
  3. API Resources

Assets

Access assets through client.assets in the Datature Vi SDK.

Assets are the image files stored inside a dataset. You upload them before adding annotations, download them for local processing, and delete them when they are no longer needed. The asset resource handles single files, folder batches, and async upload sessions.

Before You Start

Methods

list()

List assets in a dataset.

assets = client.assets.list(dataset_id="dataset_abc123")

for asset in assets.items:
    print(f"{asset.filename}: {asset.metadata.width}x{asset.metadata.height}")
from vi.api.types import PaginationParams
from vi.api.resources.datasets.assets.types import (
    AssetSortCriterion,
    SortCriterion,
    SortOrder
)

pagination = PaginationParams(page_size=100)
sort_by = AssetSortCriterion(
    criterion=SortCriterion.FILENAME,
    order=SortOrder.ASC
)

for page in client.assets.list(
    dataset_id="dataset_abc123",
    pagination=pagination,
    sort_by=sort_by
):
    for asset in page.items:
        print(f"{asset.filename}")
assets = client.assets.list(
    dataset_id="dataset_abc123",
    contents=True
)

for asset in assets.items:
    if asset.contents and asset.contents.asset:
        print(f"{asset.filename}: {asset.contents.asset.url}")
assets = client.assets.list(
    dataset_id="dataset_abc123",
    metadata_query='custom_field == "value"'
)
Expected output
Output
image_001.jpg: 1920x1080 image_002.jpg: 3840x2160 image_003.jpg: 1280x720

Parameters

Name
Type
Description
Required
Default

Returns: PaginatedResponse[Asset]

get()

Get a specific asset.

asset = client.assets.get(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789"
)

print(f"Filename: {asset.filename}")
print(f"Size: {asset.metadata.file_size} bytes")
asset = client.assets.get(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789",
    contents=True
)

if asset.contents and asset.contents.asset:
    print(f"Download URL: {asset.contents.asset.url}")
    print(f"Expires: {asset.contents.asset.expiry}")
asset = client.assets.get(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789"
)
asset.info()  # Prints formatted asset summary
Expected output
Output
Filename: image_001.jpg Size: 245760 bytes

Parameters

Name
Type
Description
Required
Default

Returns: Asset

upload()

Upload assets to a dataset. Supports single files, multiple files, and entire directories.

result = client.assets.upload(
    dataset_id="dataset_abc123",
    paths="image.jpg",
    wait_until_done=True
)

print(f"Uploaded: {result.total_succeeded}")
result = client.assets.upload(
    dataset_id="dataset_abc123",
    paths="./images/",
    wait_until_done=True
)

print(f"Uploaded: {result.total_succeeded}")
print(f"Failed: {result.total_failed}")
print(result.summary())
result = client.assets.upload(
    dataset_id="dataset_abc123",
    paths=["image1.jpg", "image2.png", "image3.webp"],
    wait_until_done=True
)
from vi import ViUploadError, ViFileTooLargeError

try:
    result = client.assets.upload(
        dataset_id="dataset_abc123",
        paths="./images/",
        wait_until_done=True
    )

    print(f"Uploaded: {result.total_succeeded}")
    print(f"Failed: {result.total_failed}")

    if result.failed_files:
        print("Failed files:")
        for f in result.failed_files:
            print(f"  - {f}")

except ViFileTooLargeError as e:
    print(f"File too large: {e.message}")
except ViUploadError as e:
    print(f"Upload failed: {e.message}")
result = client.assets.upload(
    dataset_id="dataset_abc123",
    paths="./large_folder/",
    wait_until_done=False
)

# Save session IDs to check status later
print(f"Session IDs: {result.session_ids}")
Expected output
Output
Uploaded: 25 Failed: 0

Parameters

Name
Type
Description
Required
Default

Returns: AssetUploadResult

download()

Download assets from a dataset to a local directory.

downloaded = client.assets.download(
    dataset_id="dataset_abc123",
    save_dir="./assets"
)
downloaded = client.assets.download(
    dataset_id="dataset_abc123",
    save_dir="./assets",
    overwrite=True,
    show_progress=True
)

print(f"Downloaded to: {downloaded}")

Parameters

Name
Type
Description
Required
Default

Returns: AssetDownloadResult

delete()

Delete an asset from a dataset.

deleted = client.assets.delete(
    dataset_id="dataset_abc123",
    asset_id="asset_xyz789"
)
asset_ids = ["asset_1", "asset_2", "asset_3"]

for asset_id in asset_ids:
    client.assets.delete(
        dataset_id="dataset_abc123",
        asset_id=asset_id
    )
    print(f"Deleted: {asset_id}")

Parameters

Name
Type
Description
Required
Default

Returns: DeletedAsset

wait_until_done()

Wait for an upload session to complete. Use this after an async upload (wait_until_done=False) to block until ingestion finishes.

status = client.assets.wait_until_done(
    dataset_id="dataset_abc123",
    asset_ingestion_session_id="session_id"
)

print(f"Succeeded: {status.status.progressCount.succeeded}")
print(f"Failed: {status.status.progressCount.errored}")
result = client.assets.upload(
    dataset_id="dataset_abc123",
    paths="./images/",
    wait_until_done=False
)

# Do other work...

# Then wait for each session to finish
for session_id in result.session_ids:
    status = client.assets.wait_until_done(
        dataset_id="dataset_abc123",
        asset_ingestion_session_id=session_id
    )
    print(f"Session {session_id}: {status.status.progressCount.succeeded} succeeded")

Parameters

Name
Type
Description
Required
Default

Returns: AssetIngestionSession

Supported file formats

Supported file formats

Name
Type
Description
Required
Default

Response types

Asset

from vi.api.resources.datasets.assets.responses import Asset

Properties

Name
Type
Description
Required
Default

Methods: info() → prints a formatted asset summary.

AssetMetadata

from vi.api.resources.datasets.assets.responses import AssetMetadata

Properties

Name
Type
Description
Required
Default

AssetGenerations

from vi.api.resources.datasets.assets.responses import AssetGenerations

Properties

Name
Type
Description
Required
Default

AssetAnnotations

from vi.api.resources.datasets.assets.responses import AssetAnnotations

Properties

Name
Type
Description
Required
Default

AssetDimensions

from vi.api.resources.datasets.assets.responses import AssetDimensions

Properties

Name
Type
Description
Required
Default

AssetPixelRatio

from vi.api.resources.datasets.assets.responses import AssetPixelRatio

Properties

Name
Type
Description
Required
Default

AssetHash

from vi.api.resources.datasets.assets.responses import AssetHash

Properties

Name
Type
Description
Required
Default

AssetContents

from vi.api.resources.datasets.assets.responses import AssetContents

Properties

Name
Type
Description
Required
Default

Contents

from vi.api.resources.datasets.assets.responses import Contents

Properties

Name
Type
Description
Required
Default

AssetUploadResult

Aggregates results from batched upload operations.

Properties

Name
Type
Description
Required
Default

Methods: summary() → returns a summary string.

AssetIngestionSession

from vi.api.resources.datasets.assets.responses import AssetIngestionSession

Properties

Name
Type
Description
Required
Default

AssetIngestionSessionSpec

from vi.api.resources.datasets.assets.responses import AssetIngestionSessionSpec

Properties

Name
Type
Description
Required
Default

AssetIngestionSessionStatus

from vi.api.resources.datasets.assets.responses import AssetIngestionSessionStatus

Properties

Name
Type
Description
Required
Default

AssetIngestionProgressCount

from vi.api.resources.datasets.assets.responses import AssetIngestionProgressCount

Properties

Name
Type
Description
Required
Default

UploadedAssetMetadata

from vi.api.resources.datasets.assets.responses import UploadedAssetMetadata

Properties

Name
Type
Description
Required
Default

AssetForUpload

from vi.api.resources.datasets.assets.responses import AssetForUpload

Properties

Name
Type
Description
Required
Default

Request types

AssetSortCriterion

from vi.api.resources.datasets.assets.types import AssetSortCriterion

Properties

Name
Type
Description
Required
Default

AssetCustomMetadata

from vi.api.resources.datasets.assets.types import AssetCustomMetadata

# Type alias
AssetCustomMetadata = dict[str, str | int | float | bool]

Custom metadata dictionary with string keys and primitive values.

Enums

SortCriterion

from vi.api.resources.datasets.assets.types import SortCriterion

Values

Name
Type
Description
Required
Default

SortOrder

from vi.api.resources.datasets.assets.types import SortOrder

Values

Name
Type
Description
Required
Default

FailureMode

from vi.api.resources.datasets.assets.responses import FailureMode

Values

Name
Type
Description
Required
Default

ResourceRetentionMode

from vi.api.resources.datasets.assets.responses import ResourceRetentionMode

Values

Name
Type
Description
Required
Default

AssetIngestionError

from vi.api.resources.datasets.assets.responses import AssetIngestionError

Values

Name
Type
Description
Required
Default

Related resources

Updated 4 months ago

Did this page help you?