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, set save-to-media: true on the item or element. The URL returned in the response then points 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.

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 has no expiry date and is stable. 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#