Uploading Media

Renderly supports a hybrid approach for media ingestion, giving you flexibility based on your infrastructure.

Methods

1. Direct Link (Fetch from URL)

If your assets are already hosted online (e.g., your own S3 bucket, Cloudinary, or a public server), you can simply pass the URL in your render request.

Best for:

• Users with existing storage infrastructure.
• Publicly accessible assets.
• Quick integration.

Example:

{
  "templateId": "my-template",
  "replacements": {
    "backgroundVideo": "https://mysite.com/assets/video.mp4",
    "logo": "https://mysite.com/assets/logo.png"
  }
}

2. Direct Upload (Upload to Renderly)

If you don't have external storage, you can upload files directly to Renderly's secure storage. We use Signed URLs to allow you to upload directly to S3, ensuring high performance and security.

Best for:

• Users without external storage.
• Private assets.
• Ensuring assets are in the same region as the renderer (faster rendering).

Workflow

1. Request Upload URL: Call POST /api/v1/uploads to get a pre-signed URL. You must provide the contentType of the file you intend to upload.

   curl -X POST https://api.renderly.com/v1/uploads \
     -H "Authorization: Bearer <API_KEY>" \
     -d '{"contentType": "video/mp4"}'

   Copy

2. Upload File: Use the returned uploadUrl to upload your file via PUT. Important: You must set the correct Content-Type header for your file (e.g., video/mp4, image/png).

   curl -X PUT -T video.mp4 "<uploadUrl>" -H "Content-Type: video/mp4"

   Copy

3. Use in Render: Use the returned fileUrl in your render request.

   {
     "templateId": "my-template",
     "replacements": {
       "video": "<fileUrl>"
     }
   }

   Copy

Lazy Verification

For the Direct Upload method, we implement Lazy Verification. You do not need to explicitly tell us when the upload is finished.

When you submit a render job using a Renderly asset URL:

1. We automatically check if the asset status is PENDING.
2. If PENDING, we verify the file exists in our storage.
3. We also verify the file type. Only video/*, image/*, and audio/* are allowed.
4. If found and valid, we mark it READY and proceed.
5. If not found or invalid, the render job fails immediately with a clear error.