Save generated assets to Media#

Assets produced 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, set save-to-media: true on the item or element. The asset is then saved to your Media library (the Drive), where files have no expiry date — they are kept as long as your account holds credits. See File retention.

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 in the Drive.

{
  "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.

Where the saved file appears#

A saved asset is a file in your Media library, with a URL that has no expiry date. You find it:

• in the dashboard, under Media → generated → {type};
• through the API, with GET /v2/media/folder on the generated/{type} folder.

An item without save-to-media stays in the temporary cache: it is used by the render and removed about 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 used by the render from the temporary cache: a render never fails because of save-to-media. The file is not added to your Media library in that case.

Cache promotion (no extra cost)#

If an asset was already generated 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. The next render that asks for it with save-to-media: true saves it again as a fresh file.

See also#

• Media panel — persisted generated assets
• Caching deep-dive