SDK Reference

Complete reference for the MyoSapiens Python SDK (myosdk).

Experimental Notice: The MyoSapiens SDKs are currently experimental and subject to change. Breaking changes may occur without prior notice as we iterate on the platform.

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://v2m-alb-us-east-1.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: production URL)
• timeout (float, optional) - Request timeout in seconds (default: 30.0)

Properties

• jobs - Access the jobs resource
• assets - Access the assets resource
• characters - Access the characters catalog

Methods

• close() - Close the HTTP client and release resources
• retarget(...) - Run a retarget job and wait for completion (simple one-liner)
• create_retarget_job(...) - Create a retarget job with optional blocking and status streaming

Context Manager

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

with Client(api_key="your_api_key") as client:
    result = client.retarget(tracker="walk.c3d", markerset="markerset.xml")
    result.download_all("out/")
# Client is automatically closed

Retargeting (Recommended API)

client.retarget()

Run a retarget job and wait for completion. This is the simplest way to retarget motion.

result = client.retarget(
    tracker="walk.c3d",           # File path (auto-uploads) or Asset or asset ID
    markerset="markerset.xml",  # File path (auto-uploads) or Asset or asset ID
    export_glb=True,            # Optional: export motion as GLB
    rotation="yup_to_zup",      # Optional: rotate from OpenSim Y-up to MuJoCo Z-up
    output_dir="out/",          # Optional: auto-download to directory
    stream_status=True,         # Optional: print status updates
    timeout=300.0               # Optional: max seconds to wait (default: 300)
)
# result is a JobResult
result.download_all("out/")     # Or use result.download_qpos(), etc.

Parameters

• tracker (str | Path | Asset, required) - Tracker file path, Asset object, or asset ID
• markerset (str | Path | Asset, required) - Markerset file path, Asset object, or asset ID
• output_dir (str | Path, optional) - Directory to download outputs to when complete
• character (Character | str, optional) - Character preset or ID (default: Character.MYOSKELETON_V2)
• export_glb (bool, optional) - Export motion as GLB file (default: False)
• rotation (str | None, optional) - Coordinate rotation to apply before retargeting. Supported values:
  • "yup_to_zup": OpenSim-style Y-up to MuJoCo Z-up
  • "ydown_to_zup": OpenCV-style Y-down to MuJoCo Z-up
• stream_status (bool, optional) - Stream status updates to stdout (default: False)
• on_status (callable, optional) - Callback for each status event (e.g. lambda e: print(e.status))
• timeout (float, optional) - Maximum seconds to wait (default: 300)

See Retarget Parameters for all retargeting options.

Returns

JobResult with output (RetargetOutput), job, processing_time_seconds, and download methods.

client.create_retarget_job()

Create a retarget job with full control over blocking and streaming.

By default, blocks until completion and returns a JobResult. Set block_until_complete=False to get a job handle for manual control.

# Simple blocking call (default)
result = client.create_retarget_job(
    tracker="walk.c3d",
    markerset="markerset.xml",
    export_glb=True,
)
result.download_all("out/")

# With status streaming
result = client.create_retarget_job(
    tracker="walk.c3d",
    markerset="markerset.xml",
    stream_status=True,
    on_status=lambda e: print(f"Status: {e.status}"),
)

# Non-blocking: get job handle, then stream and wait manually
job = client.create_retarget_job(
    tracker="walk.c3d",
    markerset="markerset.xml",
    block_until_complete=False,
)
for event in job.stream():
    print(event.status)
result = job.wait()
result.download_all("out/")

Parameters

Same as retarget(), plus:

• block_until_complete (bool, optional) - If True (default), wait for completion and return JobResult. If False, return a job handle immediately.
• stream_status (bool, optional) - If True and blocking, stream status updates.
• on_status (callable, optional) - Callback for each status event when stream_status=True.

Returns

• If block_until_complete=True: JobResult
• If block_until_complete=False: SyncJobHandle (sync) or AsyncJobHandle (async), with .stream(), .wait(), .id, .status

JobResult and Outputs

When a retarget job completes, you get a JobResult with:

• result.job - The completed job object
• result.output - RetargetOutput with qpos, xpos, model, motion (optional)
• result.processing_time_seconds - Processing time

Download methods (convenience)

• result.download_all(directory) - Download all output files to a directory (same as result.download(directory))
• result.download_qpos(path) - Download qpos (joint angles) Parquet file
• result.download_xpos(path) - Download xpos (joint positions in 3D space) Parquet file
• result.download_model(path) - Download model (.mjb) file
• result.download_motion(path) - Download motion (.glb) file (only if export_glb=True; otherwise raises)

You can also use result.output.download_all(directory) and result.output.qpos.download(path) etc.

Output files

See File Formats for details.

Jobs Resource (Advanced)

For advanced use, you can use the jobs resource directly.

client.jobs.create_retarget()

Create a retarget job without blocking. Returns a job handle.

job = client.jobs.create_retarget(
    tracker="walk.c3d",
    markerset="markerset.xml",
    export_glb=True,
)
print(job.id)
for event in job.stream():
    print(event.status)
result = job.wait(timeout=300)
result.download_all("out/")

client.jobs.retarget()

Run a retarget job and wait for completion (same as client.retarget() but on the jobs resource).

result = client.jobs.retarget(
    tracker="walk.c3d",
    markerset="markerset.xml",
    output_dir="out/",
    stream_status=True,
)

client.jobs.get(job_id)

Get job status by ID.

job = client.jobs.get(job_id)

client.jobs.list()

List jobs with optional filtering.

jobs = client.jobs.list(status=["SUCCEEDED", "FAILED"], limit=20, offset=0)

client.jobs.cancel(job_id)

Cancel a job.

job = client.jobs.cancel(job_id)

Assets

Manage file uploads and downloads.

client.assets.upload()

Upload a file. Purpose is auto-detected from filename (e.g. .c3d, .xml).

asset = client.assets.upload("path/to/file.c3d")
# or with explicit purpose
asset = client.assets.upload("motion.c3d", purpose="retarget")

Parameters

• file (str | Path | bytes, required) - File path or bytes content
• filename (str, optional) - Override filename (required if file is bytes)
• purpose (str, optional) - Asset purpose (auto-detected if not provided)
• content_type (str, optional) - MIME type (auto-detected if not provided)

Returns

Asset with id, filename, purpose, size_bytes, download_url, etc.

client.assets.get(asset_id)

Get asset details.

asset = client.assets.get(asset_id)

client.assets.download(asset_id, path)

Download an asset to a local file.

client.assets.download(asset_id, "output.parquet")

client.assets.list()

List assets with optional filtering.

assets = client.assets.list(purpose="retarget", limit=50, offset=0)

client.assets.delete(asset_id)

Delete an asset.

client.assets.delete(asset_id)

Async Client

For async applications, use AsyncClient:

from myosdk import AsyncClient

async with AsyncClient(api_key="...") as client:
    result = await client.retarget(
        tracker="walk.c3d",
        markerset="markerset.xml",
        export_glb=True,
    )
    await result.download_all_async("out/")

Async methods: create_retarget_job, retarget, job.stream() (async iterator), job.wait(), result.download_all_async(), result.download_qpos_async(), etc.

Next Steps

• Error Handling - Exception types and handling
• File Formats - Output formats (qpos, xpos, model, motion)
• Retargeting Tutorial - Complete workflow example