Choosing an output format is part of the template contract, not an afterthought: JsonCut renders images as PNG, JPEG or WebP and video as MP4, WebM, MOV or GIF, with quality, transparency and retention set per render. Here is how the options map to real channels — and how validation catches a wrong format before any work is queued.
The format decision happens before the render
Automation pipelines usually fail at the last step, not the first one. The layout renders perfectly, the data maps cleanly, and then the output lands in a channel that cannot use it: a 16:9 MP4 for a vertical story slot, an opaque PNG where the product photo needs transparency, an oversized GIF that no messaging platform accepts.
With a template-based pipeline, the output settings are part of the contract you design up front — the same way you define which text and image variables a template accepts. JsonCut exposes that contract as explicit render options, and this guide walks through the full menu: which still-image and video formats exist, how they map to channels, and which settings — quality, transparency, retention — you set per render.
What JsonCut can render
Every render request carries an output block (or top-level options, depending on the endpoint) with a kind and a format. The rules are simple and validated before any work is queued:
| Output kind | Formats | Notes |
|---|---|---|
image | PNG, JPEG/JPG, WebP | Transparency is meaningful for PNG and WebP only |
video | MP4, WebM, MOV, GIF | Only codec combinations accepted by the live OpenAPI contract |
Image projects render as images; video projects render as video and can also produce bounded review frames or contact sheets through Studio and MCP review workflows. If you request an incompatible combination — a transparent JPEG, for example — the API returns a 422 Validation Failed before the render is queued, so a wrong format decision surfaces as a correction step, never as a broken batch.
Still images: PNG, JPEG and WebP
For one-off artwork, OG images and product cards, three formats cover every realistic target:
| Format | Best for | Transparency | Size behaviour |
|---|---|---|---|
| PNG | Logos, screenshots, line art, anything with sharp edges | Yes | Lossless; largest files at photo-like content |
| JPEG/JPG | Photos and gradients without text overlays | No | Lossy; small files, soft text edges |
| WebP | Web delivery, campaign variants at scale | Yes | Modern compression; usually the best size-to-quality ratio |
Two practical defaults follow from this table. First, when your template renders text — prices, headlines, badges — avoid JPEG: its lossy compression softens exactly the edges your layout depends on. Second, for bulk variants that end up on websites or in emails, WebP typically wins on file size at visually identical quality, which matters when you render hundreds of rows.
JsonCut lets you tune that trade-off explicitly. A template render accepts a format plus an imageQuality value, for example:
{
"values": {
"headline": "Jetzt erhältlich",
"price": 79.9
},
"kind": "image",
"format": "webp",
"imageQuality": 92
}
Video: MP4, WebM, MOV and GIF
Video output is a container decision, and the container follows from where the file will be played:
| Container | Best for | Watch out |
|---|---|---|
| MP4 | Default for social platforms, apps and websites | The safest cross-platform choice |
| WebM | Web-native embedding where bandwidth matters | Not universally accepted by upload surfaces |
| MOV | Editing pipelines that expect QuickTime | Heavier files; rarely needed downstream of automation |
| GIF | Silent looping snippets in chat and docs | No audio; large files; preview loops, not campaigns |
The codec details are intentionally not guessed here: JsonCut accepts only the codec combinations published in its live OpenAPI contract, and the validator rejects anything else before queueing. Treat an unfamiliar codec error as a signal to check the contract, not to retry harder.
One rule keeps GIFs out of trouble: use them for short, silent, looping accents — an animated checkmark, a logo sting — and keep real campaign videos in MP4 or WebM.
Match the canvas to the channel
Formats answer "what file"; the canvas answers "what shape". Both live in the project source (width, height, and for video fps and duration), so channel dimensions should be decided while designing the template, not after the first render. Common shapes from JsonCut's own example projects:
| Channel use | Canvas | Aspect ratio |
|---|---|---|
| Landscape video, YouTube, websites | 1920 × 1080 | 16:9 |
| Feed posts | 1080 × 1080 | 1:1 |
| Portrait feed posts | 1080 × 1350 | 4:5 |
| Stories, Reels, Shorts, TikTok | 1080 × 1920 | 9:16 |
| Social preview (og:image) | 1200 × 630 | ~1.91:1 |
If one campaign needs several shapes, design them as sibling templates from the same layout language rather than stretching one render — aspect ratios are part of the design contract. The dedicated dynamic OG images guide walks through the 1200 × 630 case in depth.
Quality, transparency and retention
Three settings cover the remaining per-render decisions:
| Setting | Values | Use when |
|---|---|---|
imageQuality | Number (e.g. 92) | Tuning WebP/JPEG file size vs. fidelity |
transparent | true / false | The channel composites your artwork (PNG/WebP only) |
retention | project / temporary | Keeping artifacts durably vs. one-shot inline output |
Transparency deserves a note: it is meaningful for PNG and WebP stills and must be compatible with the chosen source and output — the validator checks this, but a transparent canvas over a photo background rarely looks the way teams expect. Retention matters mostly for inline rendering, where temporary artifacts expire according to the returned retention metadata, while project and template renders keep artifacts tied to their render history.
Validate before you render
Output settings are validated the moment a render is submitted, which makes format errors cheap — if they happen at submission time. Two habits keep them from happening later:
- Preflight when the output changes. Studio and the MCP review workflow can preflight the pinned source and output settings before a final artifact is created. Use them before a large batch or whenever output kind, dimensions, codec or transparency change.
- Retry only what is retryable. A failed render should not be resubmitted blindly: retry only when the error says
retryable: true, and reuse the same idempotency key so a corrected attempt cannot duplicate the artifact. Bulk render error handling applies the same discipline per row; here it applies per output format.
While a render is queued or in progress, you can poll the canonical render resource (queued, rendering, completed, failed, cancelled), stream the artifact with its MIME type and retention metadata, or cancel with a single DELETE while the work is still cancellable.
FAQ
Which format should I default to?
For stills, WebP for web delivery, PNG when transparency or pixel-perfect edges matter. For video, MP4 unless a specific surface asks for WebM. Defaults are cheap to change per render because they are request options, not project settings.
Can one template output several formats?
Yes — the format is chosen per render request (or per batch output block), not baked into the template. Render the same pinned template version once as WebP for email and once as PNG for print, keeping every other input identical.
Does the format affect render limits?
Validation runs the same way for every format, and incompatible output settings are rejected before queueing. The codec combinations accepted for video are defined by the live OpenAPI contract, which is the authoritative reference when a container request fails.
Sources
https://jsoncut.com/docs/operations/ (Render lifecycle and output; retrieved 2026-10-13) https://jsoncut.com/docs/templates/ (Typed templates and bulk rendering; retrieved 2026-10-13) https://jsoncut.com/docs/quickstart/ (Project quickstart; retrieved 2026-10-13) https://jsoncut.com/docs/inline-rendering/ (Inline image and video rendering; retrieved 2026-10-13) https://jsoncut.com/examples/ (Example projects and canvas dimensions; retrieved 2026-10-13)