JSON2VIDEO Documentation Caching deep-dive
JSON2Video uses a multi-layer cache to make rendering as cheap and fast as possible. Identical inputs produce identical outputs, so the engine reuses previously rendered material whenever it can detect that nothing has changed.
Understanding the cache lets you:
- Reduce render time on iterative workflows.
- Save credits on partial re-renders.
- Force a fresh render when an upstream asset changed silently.
What gets cached
The engine maintains caches at three granularities:
- Movie cache: when an identical movie JSON is submitted again, the existing rendered video is returned without re-running the pipeline.
- Scene cache: when a scene's content is unchanged but the surrounding movie changed, the engine reuses the rendered scene and only re-stitches the final movie.
- Element cache: when an individual element (image, video, voice, …) was downloaded or rendered before, the source asset is reused. This is especially valuable for AI-generated voices and images.
Cache lookups are performed on a content fingerprint of the JSON tree at that scope. Anything that affects the visual or audio result (size, position, source URL, voice text, model parameters) is part of the fingerprint.
The cache property
Every level of the JSON tree accepts a cache boolean:
{
"resolution": "full-hd",
"cache": false,
"scenes": [
{
"cache": true,
"elements": [
{ "type": "image", "src": "https://example.com/poster.jpg", "cache": false }
]
}
]
}
The semantics:
true(or omitted): use the cache when available.false: bypass the cache at this level; force a fresh render or download.
The flag is scoped. Setting cache: false on a scene forces the scene to be re-stitched but does not re-download its elements. Setting cache: false on an element forces that element to be re-fetched / re-generated and also implies the parent scene must be re-stitched, but sibling elements in that scene stay cached.
When to disable the cache
The cache is correct most of the time. Cases where you want to bypass it:
| Situation | Where to set cache: false |
|---|---|
The remote URL still points to the same path but the file changed (e.g. you re-uploaded poster.jpg to the same S3 key) |
On the affected element |
You changed an AI voice's model-settings and want to re-generate audio |
On the voice element |
| You want a known-fresh end-to-end render for a release | On the movie root |
| You're A/B testing two prompts and want to clear cached AI image renders | On each affected image element |
When to keep the cache
For high-volume production with deterministic inputs (e.g. templates filled from a database), leave caching on. The same row in the database yields the same JSON and the cache returns immediately — you only pay for the first render of each unique combination.
For prototyping, the cache also helps: you can iterate on text/positioning of a single element without re-running expensive AI generations elsewhere in the movie.
Cache and AI elements
AI-generated voiceovers and AI-generated images are the most expensive cached items in terms of credits. If you re-submit the same voice element with the same text, voice, model, and model-settings, the audio is served from the cache and does not consume voice credits again.
This is a deliberate optimisation for template-driven pipelines, where the same intro / outro voice line appears in every render. Keep the wording identical and you only pay once.