Uploading Media

Every video, image, or audio file referenced in a render needs to be reachable from a public URL. Renderly gives you two ways to make that happen.

Option 1 — direct link from your own storage

If you already host media (your own S3, Cloudinary, a CDN, public Pexels URLs, etc.), just pass the URL in your render request.

When to use: you have storage infrastructure already, or you're using public stock assets.

{
  "templateId": "tpl_123",
  "replacements": {
    "backgroundVideo": "https://your-cdn.example.com/bg.mp4",
    "logo": "https://your-cdn.example.com/logo.png"
  }
}

Renderly fetches each URL when it starts the render. The URL must be publicly reachable (no IP allowlists or session-cookie auth) and respond reasonably fast — a slow or flaky origin will slow the render.

Option 2 — signed-URL upload to Renderly storage

If you don't already host media, ask Renderly for a pre-signed S3 URL, upload your file directly to S3, then reference it in your render.

When to use: you don't have storage of your own, the asset is private, or you want it co-located with the renderer for speed.

Step 1 — request a pre-signed URL

curl -X POST https://renderly.video/api/v1/uploads \
  -H "Authorization: Bearer rnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "contentType": "video/mp4" }'

You must declare the contentType. Only the following families are accepted:

• video/* — video/mp4, video/webm, video/quicktime, etc.
• image/* — image/png, image/jpeg, image/webp, etc.
• audio/* — audio/mpeg, audio/wav, audio/aac, etc.

Response:

{
  "success": true,
  "data": {
    "id": "asset_abc123",
    "uploadUrl": "https://bucket.s3.region.amazonaws.com/key?signature=...",
    "fileUrl": "https://bucket.s3.region.amazonaws.com/key",
    "expiresAt": "2026-05-16T10:15:00Z"
  }
}

The pre-signed uploadUrl is good for ~15 minutes.

Step 2 — PUT the file to the signed URL

Use the same Content-Type you declared in step 1:

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

Step 3 — use the file URL in a render

{
  "inputProps": {
    "overlays": [{
      "id": 0, "type": "video",
      "src": "<fileUrl>",
      "from": 0, "durationInFrames": 180,
      "row": 0, "top": 0, "left": 0,
      "width": 1080, "height": 1920,
      "styles": { "objectFit": "cover" }
    }],
    "durationInFrames": 180, "fps": 30,
    "width": 1080, "height": 1920
  }
}

Lazy verification

You don't need to tell Renderly when the upload finishes. When you submit a render that references a Renderly-hosted asset, the server:

1. Checks the asset record — it starts as PENDING.
2. Verifies the file actually exists in storage and that its content type is in the allowed list.
3. Marks the asset READY and proceeds with the render.
4. If the file is missing, the upload was abandoned, or the content type isn't allowed, the render fails immediately with a clear error and no credits are charged.

This means a typical flow looks like:

POST /uploads          → get uploadUrl
PUT  <uploadUrl>       → upload bytes
POST /renders          → reference fileUrl (verification happens here)
GET  /renders/{jobId}  → poll for outputUrl

You can even kick off the render immediately after the PUT completes — Renderly will see the file on its own.

Storage and lifecycle

Uploaded media counts against your account's storage allotment in the dashboard. You can delete an asset from the Library page when you no longer need it — any render that already used the asset keeps its own copy of the final output.

Picking the right option

Where to next

• Rendering — kick off a job that uses your uploaded media
• Overlays reference — every field for video, image, and sound overlays