Complete reference for all classes, methods, and properties in the Sinkove Python SDK.

​
Installation

pip install sinkove-sdk

​
Core Classes

​
Client

Main entry point for the Sinkove API. 
from sinkove import Client

# Initialize client
client = Client(
    organization_id=uuid.UUID("your-organization-id"),
    api_key="your-api-key"  # Optional if SINKOVE_API_KEY env var is set
)

​
Properties

PropertyTypeDescription
iduuid.UUIDOrganization ID
organization_namestrOrganization name
datasetsDatasetClientDataset operations interface

​
Dataset

Represents a dataset with metadata and operations.

​
Properties

PropertyTypeDescription
iduuid.UUIDUnique dataset identifier
model_iduuid.UUIDID of the model used
organization_iduuid.UUIDOrganization that owns this dataset
num_samplesintNumber of samples to generate
argsdictModel-specific arguments
created_atstrISO timestamp of creation
statestrCurrent processing state
finishedboolWhether processing is complete
readyboolWhether dataset is ready for download
metadataMetadata | NoneDataset metadata (if available)

​
Methods

download
dataset.download(
    output_file: str,
    strategy: "fail" | "skip" | "replace" = "fail",
    wait: bool = False,
    timeout: int = None
) -> None
Download the dataset to a local file. Parameters:
  • output_file: Path where dataset will be saved
  • strategy: How to handle existing files ("fail", "skip", "replace")
  • wait: Whether to wait for dataset to be ready
  • timeout: Maximum seconds to wait
Example: 
dataset.download("output.zip", strategy="replace", wait=True, timeout=300)
wait
dataset.wait(timeout: int = None) -> None
Block until dataset processing completes. Example: 
dataset.wait(timeout=600)  # Wait max 10 minutes

​
DatasetClient

Manages dataset operations for an organization.

​
Methods

create
client.datasets.create(
    model_id: uuid.UUID,
    num_samples: int,
    args: dict
) -> Dataset
Create a new dataset generation request. Example: 
dataset = client.datasets.create(
    model_id=uuid.UUID("38ac9115-0305-4446-a93e-427ab066a764"),
    num_samples=100,
    args={"prompt": "chest x-ray showing cardiomegaly"}
)
list
client.datasets.list() -> List[Dataset]
Retrieve all datasets for the organization. Example: 
datasets = client.datasets.list()
for dataset in datasets:
    print(f"{dataset.id}: {dataset.state}")
get
client.datasets.get(dataset_id: uuid.UUID) -> Dataset
Retrieve a specific dataset by ID. Example: 
dataset = client.datasets.get(uuid.UUID("2e8f80f2-7f0e-4020-9464-6732a2386b6c"))

​
Data Types

​
Metadata

@dataclass
class Metadata:
    id: uuid.UUID
    progress: int          # Completion percentage (0-100)
    size: int             # Dataset size in bytes  
    started_at: datetime  # When processing began
    finished_at: datetime # When processing completed

​
Dataset States

StateDescription
"PENDING"Queued for processing
"STARTED"Currently generating
"READY"Successfully completed
"FAILED"Generation failed

​
Advanced Classes

​
OrganizationClient

For managing multiple organizations. 
from sinkove.connector import Connector
from sinkove.organizations.client import OrganizationClient

connector = Connector(api_key="your-api-key")
org_client = OrganizationClient(connector)

# List all organizations
organizations = org_client.list()
for org in organizations:
    print(f"{org.organization_name}: {len(org.datasets.list())} datasets")

​
Environment Variables

VariableDescriptionDefault
SINKOVE_API_KEYAPI key for authenticationRequired
SINKOVE_API_URLAPI endpoint URLhttps://api.sinkove.com

​
Exception Handling

ExceptionCause
ValueErrorMissing required configuration
TimeoutErrorOperation timeout exceeded
ExceptionAPI errors, network issues, etc.
try:
    dataset = client.datasets.create(model_id, 10, args)
    dataset.wait(timeout=300)
    dataset.download("output.zip")
except ValueError as e:
    print(f"Config error: {e}")
except TimeoutError:
    print("Operation timed out")
except Exception as e:
    print(f"Error: {e}")

​
Complete Example

import uuid
from sinkove import Client

client = Client(uuid.UUID("your-organization-id"))

dataset = client.datasets.create(
    model_id=uuid.UUID("your-model-id"),
    num_samples=50,
    args={"prompt": "chest x-ray showing pneumonia"}
)

dataset.wait(timeout=1800)
dataset.download("dataset.zip", strategy="replace")
print("Complete!")

​
Next Steps

Python SDK Guide

Complete SDK documentation

Quick Start

Create your first dataset

Examples

Advanced patterns and use cases

Installation

Setup and configuration