MyoSapiens
Reference

SDK Reference

Complete Python SDK reference documentation.

Complete reference for the MyoSapiens Python SDK (myosdk).

Getting Started: If you haven't installed the SDK yet, see the Installation Guide for setup instructions.

Client

Client

Main client class for interacting with the MyoSapiens API.

from myosdk import Client

client = Client(
    api_key="your_api_key_here",
    base_url="https://api.myolab.ai",  # optional
    timeout=30.0  # optional
)

Parameters

  • api_key (str, required) - Your API key from dev.myolab.ai
  • base_url (str, optional) - Base URL of the API (default: https://api.myolab.ai)
  • timeout (float, optional) - Request timeout in seconds (default: 30.0)

Properties

  • assets - Access the assets resource
  • jobs - Access the jobs resource

Methods

  • close() - Close the HTTP client and release resources

Context Manager

The client can be used as a context manager to automatically close connections:

with Client(api_key="your_api_key") as client:
    # Use client here
    assets = client.assets.list()
# Client is automatically closed

Assets

Manage file uploads and downloads.

upload_file()

Upload a file in one step (convenience method).

asset = client.assets.upload_file(
    file_path="path/to/file.c3d",
    purpose="retarget",  # optional, auto-detected if not provided
    metadata={"description": "My motion capture file"}  # optional
)

Parameters

  • file_path (str | Path, required) - Path to the file to upload
  • purpose (str, optional) - Asset purpose. Auto-detected from file extension if not provided. See File Formats for supported purposes and file types.
  • metadata (dict, optional) - Optional metadata dictionary

Returns

Dict with completed asset details:

{
    "asset_id": "uuid",
    "verified": True,
    "size_bytes": 1024000,
    "checksum_sha256": "..."
}

Example

# Upload a C3D file
c3d_asset = client.assets.upload_file("motion.c3d")
print(f"Uploaded asset ID: {c3d_asset['asset_id']}")

# Upload with explicit purpose (usually auto-detected)
c3d_asset = client.assets.upload_file(
    "motion.c3d",
    purpose="retarget",
    metadata={"source": "mocap_session"}
)

get()

Get asset details.

asset = client.assets.get(asset_id)

Parameters

  • asset_id (str, required) - Asset identifier

Returns

Dict with asset details including download_url:

{
    "asset_id": "uuid",
    "purpose": "retarget",
    "filename": "motion.c3d",
    "size_bytes": 1024000,
    "status": "completed",
    "download_url": "https://...",
    "created_at": "2024-01-01T00:00:00Z"
}

download()

Download an asset to a local file.

client.assets.download(asset_id, "output.npz")
# or
client.assets.download(asset_dict, "output.npz")

Parameters

  • asset (str | dict, required) - Asset identifier (string) or asset dict from get()
  • destination (str | Path, required) - Destination file path

Example

# Download by asset ID
client.assets.download(asset_id, "output.npz")

# Download from asset dict
asset = client.assets.get(asset_id)
client.assets.download(asset, "output.npz")

list()

List assets with optional filtering.

result = client.assets.list(
    purpose="retarget",  # optional
    reference_count=0,  # optional
    limit=50,  # optional, default: 50
    offset=0  # optional, default: 0
)

Parameters

  • purpose (str, optional) - Filter by purpose. See File Formats for supported purposes.
  • reference_count (int, optional) - Filter by reference count (e.g., 0 for unused assets)
  • limit (int, optional) - Items per page (default: 50)
  • offset (int, optional) - Items to skip (default: 0)

Returns

Dict with assets list and pagination info:

{
    "assets": [...],
    "total": 100,
    "limit": 50,
    "offset": 0
}

delete()

Delete an asset.

client.assets.delete(asset_id)

Parameters

  • asset_id (str, required) - Asset identifier

Raises

  • ValidationError - If asset has active references or cannot be deleted

Jobs

Manage retargeting jobs.

start_retarget()

Start a retarget job.

job = client.jobs.start_retarget(
    c3d_asset_id="uuid",  # or c3d_s3="s3://..."
    markerset_asset_id="uuid",  # or markerset_s3="s3://..."
    character_id="uuid",  # optional, default provided
    character_version="v1.0.0",  # optional, default: "v1.0.0"
    enable_scaling=True,  # optional, default: True
    subject_gender="male",  # optional, default: "male"
    subject_height=1.75,  # optional
    subject_weight=70.0,  # optional
    metadata={"description": "..."}  # optional
)

Parameters

  • c3d_asset_id (str, optional) - Asset ID of the C3D motion capture file (either this or c3d_s3 required)
  • c3d_s3 (str, optional) - Direct S3 key of the C3D file (either this or c3d_asset_id required)
  • markerset_asset_id (str, optional) - Asset ID of the markerset XML file (either this or markerset_s3 required)
  • markerset_s3 (str, optional) - Direct S3 key of the markerset XML file (either this or markerset_asset_id required)
  • character_id (str, optional) - Character identifier (default: "0199e278-06e6-7726-a6ba-9929f79005e8")
  • character_version (str, optional) - Character version (default: "v1.0.0")
  • enable_scaling (bool, optional) - Whether to enable body scaling during retargeting (default: True)
  • subject_gender (str, optional) - Subject gender for anthropometric scaling: "male" or "female" (default: "male")
  • subject_height (float, optional) - Subject height in meters for anthropometric scaling
  • subject_weight (float, optional) - Subject weight in kilograms for anthropometric scaling
  • metadata (dict, optional) - Optional metadata dictionary

Returns

Dict with job information:

{
    "job_id": "uuid",
    "type": "retarget",
    "status": "QUEUED",
    "message": "Retarget job created successfully",
    "estimated_wait_time_seconds": 10
}

Example

# Start retarget job with asset IDs
job = client.jobs.start_retarget(
    c3d_asset_id=c3d_asset["asset_id"],
    markerset_asset_id=markerset_asset["asset_id"],
    character_id="0199e278-06e6-7726-a6ba-9929f79005e8",
    character_version="v1.0.0",
    enable_scaling=True,
    subject_gender="male",
    subject_height=1.75,
    subject_weight=70.0
)

get()

Get job status.

job = client.jobs.get(job_id)

Parameters

  • job_id (str, required) - Job identifier

Returns

Dict with job status and results:

{
    "job_id": "uuid",
    "type": "retarget",
    "status": "SUCCEEDED",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:05:00Z",
    "started_at": "2024-01-01T00:01:00Z",
    "completed_at": "2024-01-01T00:05:00Z",
    "message": "Job completed successfully",
    "output": {
        "retarget_output_asset_id": "uuid"
    },
    "download_urls": {
        "retarget_output": "https://..."
    }
}

wait()

Wait for a job to complete.

result = client.jobs.wait(
    job_id,
    interval=2.0,  # optional, polling interval in seconds
    timeout=None  # optional, maximum time to wait in seconds
)

Parameters

  • job_id (str, required) - Job identifier
  • interval (float, optional) - Polling interval in seconds (default: 2.0)
  • timeout (float, optional) - Maximum time to wait in seconds (None = no timeout)

Returns

Final job status dict (same format as get()).

Raises

  • TimeoutError - If timeout is exceeded

Example

# Wait for job to complete (no timeout)
result = client.jobs.wait(job["job_id"])

# Wait with timeout (5 minutes)
result = client.jobs.wait(job["job_id"], timeout=300)

# Custom polling interval (check every 5 seconds)
result = client.jobs.wait(job["job_id"], interval=5.0)

cancel()

Cancel a job.

result = client.jobs.cancel(job_id)

Parameters

  • job_id (str, required) - Job identifier

Returns

Dict with cancellation confirmation:

{
    "job_id": "uuid",
    "status": "CANCELED",
    "message": "Job canceled successfully"
}

list()

List jobs with optional filtering.

result = client.jobs.list(
    status="SUCCEEDED",  # or ["SUCCEEDED", "FAILED"]
    job_type="retarget",
    created_after=datetime(2024, 1, 1),  # optional
    created_before=datetime(2024, 12, 31),  # optional
    run_id="uuid",  # optional
    has_output=True,  # optional
    input_asset_id="uuid",  # optional
    limit=50,  # optional, default: 50
    offset=0  # optional, default: 0
)

Parameters

  • status (str | liststr, optional) - Filter by status: "QUEUED", "RUNNING", "SUCCEEDED", "FAILED", "CANCELED" (or list of statuses)
  • job_type (str | liststr, optional) - Filter by job type: "retarget"
  • created_after (datetime | str, optional) - ISO 8601 timestamp or datetime for lower bound
  • created_before (datetime | str, optional) - ISO 8601 timestamp or datetime for upper bound
  • run_id (str, optional) - Filter by run identifier
  • has_output (bool, optional) - Filter jobs that have (or do not have) output assets
  • input_asset_id (str, optional) - Filter jobs that used a given input asset
  • limit (int, optional) - Items per page (default: 50)
  • offset (int, optional) - Items to skip (default: 0)

Returns

Dict with jobs list and pagination info:

{
    "jobs": [...],
    "total": 100,
    "limit": 50,
    "offset": 0
}

Example

from datetime import datetime, timedelta

# List all succeeded retarget jobs from the last week
week_ago = datetime.now() - timedelta(days=7)
result = client.jobs.list(
    status="SUCCEEDED",
    job_type="retarget",
    created_after=week_ago
)

# List jobs with multiple statuses
result = client.jobs.list(
    status=["SUCCEEDED", "FAILED"],
    limit=100
)

Next Steps

Installation

Install the MyoSapiens Python SDK and set up your development environment.

Error Handling

Exception types and error handling in the MyoSapiens SDK.