Save generated assets to Media

Assets returned by POST /v2/preloads, by movie.preload[] inside a render, or generated by elements in scene.elements[] are normally stored in a temporary cache that expires 3 days after generation. That works fine for one-shot renders, but breaks workflows where you generate an asset once and reuse it for weeks — long-form templates, voiceover libraries, hero images bound to a campaign that ships next month.

To keep a generated asset permanently, set save-to-media: true on the item or element. The URL returned in the response then points to your Media library (the Drive) and never expires.

Why ephemeral by default

Most preloaded assets are throwaway: a one-off image baked into a single render. Auto-persisting every asset would silently fill the Drive with assets you don't recognize a month later and burn storage quota. Opt-in keeps the Drive curated by you.

If you do want everything persisted, simply set the flag on each item — there is no global toggle by design.

Opt-in

Add "save-to-media": true to any preload item whose type is generable (image, video, audio, voice, html, component). External URLs in image / video items are also supported — the file is downloaded once and stored as a permanent asset.

{
  "preload": [
    {
      "id": "campaign_hero",
      "type": "image",
      "model": "flux-schnell",
      "prompt": "a paper plane flying over a city skyline, flat illustration",
      "save-to-media": true
    },
    {
      "id": "intro_voice",
      "type": "voice",
      "model": "elevenlabs",
      "voice": "Adam",
      "text": "Welcome to our weekly digest.",
      "save-to-media": true
    },
    {
      "id": "throwaway_thumb",
      "type": "image",
      "model": "flux-schnell",
      "prompt": "abstract gradient background"
    }
  ]
}

The first two items are persisted; the third stays in the temporary cache.

Response shape

GET /v2/preloads/{preload_id} reports the result per item:

{
  "items": [
    {
      "id": "campaign_hero",
      "type": "image",
      "status": "ready",
      "url": "https://media.json2video.com/{client_id}/files/generated/image/campaign_hero.webp",
      "persistent": true,
      "expires_at": null,
      "width": 1024,
      "height": 1024,
      "size": 37330
    },
    {
      "id": "throwaway_thumb",
      "status": "ready",
      "url": "https://json2video-cdn1.s3.amazonaws.com/tmp/assets/{client_id}/...",
      "persistent": false,
      "expires_at": "2026-05-30T10:00:00Z"
    }
  ]
}

persistent: true — the URL is permanent. Safe to embed in scheduled renders, downstream pipelines, public pages.
persistent: false — the URL is from the temporary cache. expires_at tells you when it stops working (approximately 3 days after generation).

File path & naming

Persisted assets land at:

https://media.json2video.com/{client_id}/files/generated/{type}/{filename}.{ext}

{filename} is the element id if it is a safe identifier (^[a-zA-Z0-9_-]+$). Otherwise, the first 12 characters of the asset hash.
{ext} is the real container/codec returned by the generator. A Flux model that yields WebP produces .webp, not .png — set your downstream consumers accordingly or inspect the returned URL.
If a different asset already occupies that path, the new file is suffixed with -{hash[:6]} to avoid overwriting.

The file is visible in the dashboard at Media → generated → {type} and is manageable via /v2/media like any uploaded asset.

Quota & graceful degradation

If the Drive is blocked for the account (storage quota, billing hold, etc.), the asset is still generated and served from the temporary cache — the request never fails because of save-to-media. The response is:

{
  "status": "ready",
  "url": "https://json2video-cdn1.s3.amazonaws.com/tmp/assets/...",
  "persistent": false,
  "expires_at": "2026-05-30T10:00:00Z",
  "warning": "quota_blocked"
}

Check the warning field if you need to alert on quota.

Cache promotion (no extra cost)

If you already preloaded an asset without save-to-media, asking again with save-to-media: true and the same prompt/source promotes the cached binary into the Media library without re-running the generator. No credits are deducted for the promotion.

If the cache has already purged the binary, JSON2Video re-generates the asset from the stored source request — still at zero credit cost, as compensating for the cache miss is on us.

Lifecycle

Persisted assets stay in your Drive until you delete them. Removing the file via DELETE /v2/media/file (or from the dashboard) automatically clears the backreference. A subsequent preload with save-to-media: true re-persists it as a fresh file.

Save generated assets to Media#

Why ephemeral by default#

Opt-in#

Response shape#

File path & naming#

Quota & graceful degradation#

Cache promotion (no extra cost)#

Lifecycle#

See also#