Upload Captures
This guide explains how to upload a capture file to Teleport using our API and an AWS S3 multipart upload flow.
The process consists of four main steps:
- Create a new capture entry.
- Generate upload URLs for each file part.
- Upload each part directly to S3 using the provided URLs.
- Notify Teleport that the upload is complete.
Authentication
To upload captures, you need to provide an AUTH_TOKEN to authenticate the requests to the API.
Read about how to obtain the token in the authentication page.
1. Create a Capture#
We need first to create a capture entry on the Teleport API. This initializes the upload process and tells the API what file you plan to upload.
Endpoint:
Parameters:
Input data formats:
bulk-images: The file should be a .zip archive containing RGB images. The files can be nested in folders. Non-image files will be ignored. The file can be larger than 5 GB.video: The file should be an mp4 file. It can be larger than 5 GB.
Example curl request:
curl -X POST "https://teleport.varjo.com/api/v1/captures" \
-H "Authorization: Bearer AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "my_capture.zip",
"bytesize": 104857600,
"input_data_format": "bulk-images"
}'
Example response:
eid- unique capture identifier.num_parts- how many chunks your file should be split into.chunk_size- the size (in bytes) of each chunk.
2. Generate Upload URLs#
For each part of your file, request an upload URL from the API. You’ll use these pre-signed URLs to upload each chunk directly to S3.
Endpoint:
Replace EID with the capture identifier (eid) obtained when creating the capture in the previous step.
Example curl request:
curl -X POST "https://teleport.varjo.com/api/v1/captures/EID/create-upload-url/1" \
-H "Authorization: Bearer AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"eid": "EID",
"bytesize": 104857600
}'
Example response:
Repeat this request for each part number (1 through num_parts) to get all upload URLs.
3. Upload File Parts to S3#
Use the returned upload_url to upload each chunk of your file directly to S3 with an HTTP PUT request.
Endpoint:
Example curl request:
When uploading multiple parts, repeat this command for each part, using the corresponding upload URL and file segment.
Make sure to record each part’s ETag from the response headers - you’ll need it in the next step.
4. Complete the Upload#
Once all parts have been uploaded, notify the Teleport API that the upload is complete.
Endpoint:
Replace EID with the capture identifier (eid) obtained when creating the capture in the previouse step.
Example curl request:
curl -X POST "https://teleport.varjo.com/api/v1/captures/EID/uploaded" \
-H "Authorization: Bearer AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"eid": "EID",
"parts": [
{"number": 1, "etag": "etag1"},
{"number": 2, "etag": "etag2"}
]
}'
Example response:
The capture is now successfully uploaded and queued for processing by the 3D reconstruction pipeline.
Summary#
| Step | Description | Endpoint |
|---|---|---|
| 1 | Create capture | POST /api/v1/captures |
| 2 | Create upload URLs | POST /api/v1/captures/{eid}/create-upload-url/{part_no} |
| 3 | Upload parts to S3 | PUT S3 pre-signed URLs |
| 4 | Mark upload as completed | POST /api/v1/captures/{eid}/uploaded |
Once the upload is completed, your capture will appear in your Teleport dashboard and the reconstruction process will start.
💡 Tip: For large uploads, using a script or SDK (like Python’s
httpx) is recommended to automate chunking and part tracking.
What next?#
Check out our code examples: they implement the capture upload flow described above in different programming languages.