Presigned URLs
Upload large files directly to cloud storage using presigned URLs.
Presigned URLs let you upload files directly to cloud storage, bypassing the API server. This is ideal for large files where streaming through the API would be slow or impractical.
Flow
- Request a presigned PUT URL from the API
- Upload the file directly to cloud storage using the presigned URL
- Confirm the upload with the API to activate the file record
Step 1: Request a Presigned URL
curl -X POST https://api.tzzl.io/api/v1/upload/presign \
-H "Authorization: Bearer sk_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{
"space": "a1b2c3",
"filename": "large-video.mp4",
"content_type": "video/mp4",
"size": 104857600
}'
Parameters
| Parameter | Required | Description |
|---|---|---|
space | Yes | Space handle |
filename | Yes | Original filename (max 255 chars) |
content_type | Yes | MIME type (max 100 chars) |
size | Yes | File size in bytes |
upload_config | No | Upload config name |
ref | No | Custom reference string (max 255 chars) |
Response
{
"file_id": "01HQ...",
"upload_url": "https://...r2.cloudflarestorage.com/...",
"object_key": "a1b2c3/video-01HQ...",
"expires_in": 3600
}
The file record is created with status: "pending" at this point.
Step 2: Upload to Cloud Storage
Use the presigned URL to PUT the file directly to cloud storage:
curl -X PUT "PRESIGNED_UPLOAD_URL" \
-H "Content-Type: video/mp4" \
--data-binary @large-video.mp4
Step 3: Confirm the Upload
After the file is uploaded, confirm it with the API to change the status from pending to active:
curl -X POST https://api.tzzl.io/api/v1/upload/confirm/FILE_ID \
-H "Authorization: Bearer sk_a1b2c3d4..."
The API verifies the object exists in cloud storage and activates the file record.
When to Use
- Files larger than 50 MB
- Video uploads
- Scenarios where you want to minimize API server load
- Large batch uploads
Presigned URL Expiration
The presigned URL expires after the expires_in period (default: 3600 seconds / 1 hour). If the upload is not completed before expiration, you will need to request a new presigned URL.
Pending file records that are never confirmed will remain in pending status.