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
- Vi SDK installed with authentication configured
- A secret key for API authentication
- A dataset to upload assets into
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"'
)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 summaryReturns: 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}")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}")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}")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")Returns: AssetIngestionSession
Supported file formats
Response types
Asset
from vi.api.resources.datasets.assets.responses import AssetMethods: info() → prints a formatted asset summary.
AssetMetadata
from vi.api.resources.datasets.assets.responses import AssetMetadataAssetGenerations
from vi.api.resources.datasets.assets.responses import AssetGenerationsAssetAnnotations
from vi.api.resources.datasets.assets.responses import AssetAnnotationsAssetDimensions
from vi.api.resources.datasets.assets.responses import AssetDimensionsAssetPixelRatio
from vi.api.resources.datasets.assets.responses import AssetPixelRatioAssetHash
from vi.api.resources.datasets.assets.responses import AssetHashAssetContents
from vi.api.resources.datasets.assets.responses import AssetContentsContents
from vi.api.resources.datasets.assets.responses import ContentsAssetUploadResult
Aggregates results from batched upload operations.
Methods: summary() → returns a summary string.
AssetIngestionSession
from vi.api.resources.datasets.assets.responses import AssetIngestionSessionAssetIngestionSessionSpec
from vi.api.resources.datasets.assets.responses import AssetIngestionSessionSpecAssetIngestionSessionStatus
from vi.api.resources.datasets.assets.responses import AssetIngestionSessionStatusAssetIngestionProgressCount
from vi.api.resources.datasets.assets.responses import AssetIngestionProgressCountUploadedAssetMetadata
from vi.api.resources.datasets.assets.responses import UploadedAssetMetadataAssetForUpload
from vi.api.resources.datasets.assets.responses import AssetForUploadRequest types
AssetSortCriterion
from vi.api.resources.datasets.assets.types import AssetSortCriterionAssetCustomMetadata
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 SortCriterionSortOrder
from vi.api.resources.datasets.assets.types import SortOrderFailureMode
from vi.api.resources.datasets.assets.responses import FailureModeResourceRetentionMode
from vi.api.resources.datasets.assets.responses import ResourceRetentionModeAssetIngestionError
from vi.api.resources.datasets.assets.responses import AssetIngestionErrorRelated resources
Updated about 1 month ago