Local File & URL Uploads

Upload local files or HTTP/HTTPS URLs. Returns a video_id per video.

Local file & URL upload examples

# Single local file
result = client.upload("video.mp4")

# Single video with custom display name
result = client.upload("video.mp4", name="Morning Commute.mp4")

# Single video with metadata
result = client.upload(("video.mp4", "video.json"))

# Multiple local files
batch = client.upload(["a.mp4", "b.mp4"])

# Multiple videos with mixed metadata
batch = client.upload([
    ("video1.mp4", "video1.json"),     # Video with metadata
    "video2.mp4",                       # Video without metadata
    ("video3.mp4", "video3.json")      # Another video with metadata
])

# Batch upload with per-video custom names (dict syntax)
batch = client.upload([
    {"video": "dashcam_001.mp4", "name": "Trip to Downtown"},
    {"video": "dashcam_002.mp4", "name": "Highway Merge"},
    {"video": "dashcam_003.mp4", "name": "Parking Lot Exit", "metadata": "trip3.json"}
])

# Public GCS URL (any accessible HTTPS URL)
remote = client.upload("https://storage.googleapis.com/my-bucket/videos/demo.mp4")

# URL with custom display name
remote = client.upload(
    "https://storage.googleapis.com/my-bucket/videos/scene-1.mp4",
    name="scene_1.mp4"
)

# With folder organization
result = client.upload("video.mp4", folder="my_folder")

# With metadata JSON file and folder
result = client.upload(("dashcam.mp4", "dashcam.json"), folder="fleet_videos")

# Organization scope
result = client.upload("launch.mp4", folder="robotics_org", scope="org")

Local MCAP Uploads

Upload local .mcap files through the same upload() helper. The initial response contains an mcap_ingest_id; wait for completion to retrieve the derived videos.

Local MCAP upload

queued = client.upload("sample.mcap")

final = client.wait_for_mcap_ingest(queued["mcap_ingest_id"])
print("video_ids:", final["video_ids"])
print("videos_by_channel:", final.get("videos_by_channel", {}))

S3 MCAP Cloud Ingest

For large MCAPs already stored in S3, create a role-based S3 Storage Transfer integration, then pass the s3://...mcap URI to upload(). This avoids routing the source MCAP through your local machine or the Nomadic backend before storage transfer starts.

S3 MCAP cloud ingest

BUCKET = "your-mcap-bucket"
PREFIX = "mcap/"
ROLE_ARN = "arn:aws:iam::123456789012:role/NomadicMcapTransferRole"

integration = client.cloud_integrations.add_s3_storage_transfer(
    name="MCAP archive",
    bucket=BUCKET,
    prefix=PREFIX,
    role_arn=ROLE_ARN,
)

job = client.upload(
    f"s3://{BUCKET}/{PREFIX}example-017-droid-ds.mcap",
    folder="mcap_cloud_test",
    integration_id=integration["id"],
    wait_for_uploaded=False,
)

final = client.wait_for_mcap_import_job(
    job["mcap_import_job_id"],
    timeout=7200,
)

print(final["status"])
print(final["video_ids"])

See Cloud Storage Uploads for the AWS IAM role setup required before creating the S3 Storage Transfer integration.

Multi-view (local/URL)

Use a dict mapping view names to local files or URLs. front is required in every set.

# Single multi-view set
multi = client.upload(
  {
    "front": "https://example.com/trip-042/front.mp4",
    "left": "https://example.com/trip-042/left.mp4",
    "right": "https://example.com/trip-042/right.mp4",
  },
  folder="fleet_uploads",
  scope="org",
)

# Multiple multi-view sets in one call
multi_batch = client.upload([
  {
    "front": "https://example.com/set1/front.mp4",
    "left": "https://example.com/set1/left.mp4",
    "right": "https://example.com/set1/right.mp4",
  },
  {
    "front": "https://example.com/set2/front.mp4",
    "left": "https://example.com/set2/left.mp4",
    "right": "https://example.com/set2/right.mp4",
  },
])

Local/HTTP multi-view uploads return the stitched front video_id.

Metadata sidecars must share the same base filename as the video (e.g., launch.mp4 + launch.json). See the Metadata Ingestion Spec for the full schema.
Custom names (name param) are supported for single files, URLs, and batch dict syntax — not for cloud imports or multi-view.
Folders are auto-created if they don’t exist. Defaults to personal scope; use scope="org" for shared org folders.

Required Parameters:

Parameter	Type	Description
`videos`	`str \| Path \| tuple \| Sequence`	Single video, (video, metadata) tuple, or list of mixed videos/tuples

Optional Parameters:

Parameter	Type	Default	Description
`name`	`str`	`None`	Custom display name for the uploaded video. Overrides the original filename. Only supported for single file uploads, URLs, or per-video in batch dict syntax. Not supported for cloud imports or multi-view uploads.
`folder`	`str`	`None`	Folder name for organizing uploads (unique within each scope)
`metadata_file`	`str \| Path`	`None`	Overlay metadata JSON file (must share the video’s base filename) per spec (ignored when using tuples)
`scope`	`'user' \| 'org'`	`'user'`	Scope hint for folder resolution. Use `'org'` for shared org folders and `'user'` for personal uploads.
`upload_timeout`	`int`	`1200`	Timeout in seconds for upload completion
`wait_for_uploaded`	`bool`	`True`	Wait until upload is complete
`integration_id`	`str`	`None`	Saved cloud integration identifier for `gs://`, `s3://`, `hf://buckets/...`, and S3 MCAP imports.
`chunk_size`	`int`	`None`	Optional chunk size for MCAP ingest.
`front_channel`	`str`	`None`	Front-camera channel name for local MCAP stitching.
`channel_roles`	`Mapping[str, str]`	`None`	Optional channel-to-role mapping for local MCAP uploads.
`channel_labels`	`Mapping[str, str]`	`None`	Optional channel display labels for local MCAP uploads.

Returns: Dict (single) or List[Dict] (multiple) with {"video_id": "...", "status": "processing" | "uploaded" | ...}

​Local MCAP Uploads

​S3 MCAP Cloud Ingest

​Multi-view (local/URL)

Local MCAP Uploads

S3 MCAP Cloud Ingest

Multi-view (local/URL)