Skip to main content
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:
ParameterTypeDescription
videosstr | Path | tuple | SequenceSingle video, (video, metadata) tuple, or list of mixed videos/tuples
Optional Parameters:
ParameterTypeDefaultDescription
namestrNoneCustom 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.
folderstrNoneFolder name for organizing uploads (unique within each scope)
metadata_filestr | PathNoneOverlay 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_timeoutint1200Timeout in seconds for upload completion
wait_for_uploadedboolTrueWait until upload is complete
integration_idstrNoneSaved cloud integration identifier for gs://, s3://, hf://buckets/..., and S3 MCAP imports.
chunk_sizeintNoneOptional chunk size for MCAP ingest.
front_channelstrNoneFront-camera channel name for local MCAP stitching.
channel_rolesMapping[str, str]NoneOptional channel-to-role mapping for local MCAP uploads.
channel_labelsMapping[str, str]NoneOptional channel display labels for local MCAP uploads.
Returns: Dict (single) or List[Dict] (multiple) with {"video_id": "...", "status": "processing" | "uploaded" | ...}