---
title: "Media URLs, uploads and output files"
canonical_url: https://docs.zvid.io/docs/concepts/media-assets/
source: docs/concepts/media-assets.md
content_revision: 6338386a1dd87e4a
---

# Media URLs, uploads and output files

The hosted renderer downloads the media referenced by your project. A URL that works in your signed-in browser may still fail when the render worker requests it without your cookies.

## Source requirements

- Use an absolute public HTTP or HTTPS URL that returns the media file itself.
- Keep the URL accessible until the queued render has finished. Short-lived signed source links can expire while a job waits.
- Do not use a local file path, browser `blob:` URL, login page, or private-network address.
- Do not embed credentials in a URL. The worker rejects private/internal addresses and unsafe URL forms.
- Respect your plan's source size, duration, resolution and element limits. A small crop does not make an oversized original source exempt from input limits.

Validation checks the request structure and account limits. Download failures, actual media decoding, or source changes can still cause a later render failure.

## Upload your own media

Use [Create upload](https://docs.zvid.io/docs/endpoints/create-upload/) with a server-side API key. The returned `upload` object describes the uploaded file; use its returned URL in the relevant element's `src`. Do not invent a CDN path from a filename.

The editor's [media library](https://docs.zvid.io/docs/editor/media/) provides a visual upload workflow. List and inspect your uploads through the API or dashboard before deleting assets used by active projects and templates.

## Use Zvid's stock library

Choose media returned by Zvid's stock search or by the editor's stock library. Use the render-ready source URL from the selected result, rather than a search result page or thumbnail when a full-resolution source is available. Confirm that the media is appropriate for your intended use.

Keep the selected source and its relevant metadata with your project. A library search can return different results over time; saving only the original search phrase is not enough to reproduce a composition.

## Diagnose a source failure

| Failure | Check |
| --- | --- |
| Authentication required or link expired | Replace the source with a directly accessible media URL or upload it to Zvid |
| Private/unsafe host rejected | Use a public media host; `localhost` on your computer is not reachable as your local filesystem from the renderer |
| File too large or source too long | Check the source itself against the active plan limits, then reduce it or select another source |
| Invalid media or decoding failed | Verify the response is a real supported media file rather than HTML or an error page |
| Wrong dimensions or crop | Check the original media size, crop and [resize settings](https://docs.zvid.io/docs/concepts/layout/) |

Record the job ID and returned failure reason when requesting help. Never include an API key in a support message.

## Completed output

A completed job returns a media URL. The normal queue response has an object at `result` with `url`; a database-backed job response can return the URL as a string. See [Render lifecycle](https://docs.zvid.io/docs/operations/render-lifecycle/) for a helper that handles both.

Persist the job ID and output URL in your application. Download a copy to your own storage when your workflow requires independent retention. The API response does not promise a universal expiration or permanent retention period, and deleting a render can remove its stored output. Do not infer a retention guarantee from the current URL's shape.

Use [webhooks](https://docs.zvid.io/docs/automation/webhooks/) or bounded polling to begin downstream processing only after the job has completed.