Inline rendering and durable projects share one source format but promise different lifecycles. A decision table, a migration path and the gray zone where one-shot rendering quietly becomes a template problem.
Two ways to hand the API the same design
Every JsonCut render starts as the same thing: an HTML-first source document that describes layers, text, media, motion and variables. The V2 API accepts that source in two modes. You can send it with a render request and get one disposable artifact back — inline rendering — or you can store it as a durable project that keeps versions, opens in Studio and can later be published as a typed template.
The format does not change between the two paths. The lifecycle does. That distinction is the whole decision: inline rendering is built for output you need once, while projects and typed templates are built for output you will touch again — another variant, another reviewer, another quarter. Choosing wrong is rarely catastrophic, but it quietly shapes how much coordination your pipeline needs later.
What inline rendering actually gives you
An inline render is a single POST /api/v2/renders call. The request carries the complete bounded source — canvas, HTML, CSS, variables and values — plus output settings, and the API queues the render immediately:
{
"source": {
"format": "jsoncut-html",
"version": 1,
"id": "inline-card",
"name": "Inline card",
"compositionKind": "image",
"canvasBackground": "transparent",
"width": 1200,
"height": 630,
"fps": 1,
"duration": 1,
"html": "<main id=\"card\"></main>",
"css": "#card{position:absolute;inset:0;background:linear-gradient(135deg,#17191f,#ff9418)}",
"variables": [],
"values": {},
"customBlocks": []
},
"kind": "image",
"format": "png",
"transparent": true,
"retention": "temporary"
}
Three properties matter more than the payload shape:
| Property | What the API guarantees |
|---|---|
| Validation | The same validator used by projects runs before queueing — a broken source fails fast, not after minutes of rendering. |
| Media handling | Large media must be uploaded first; only small bounded data URLs belong inline. |
| Retention | Artifacts are temporary by default and expire according to the retention metadata returned with the render. |
Because nothing durable is created, there is no project to version, no template to pin and nothing to clean up. You poll the render resource — or receive a signed webhook in production — and stream the artifact from the render endpoint. If you need the same image next week, the honest answer is: render it again from the request body you kept in your own code.
What durability adds: projects and templates
A project stores that same source. The project quickstart flow — create the project, save the returned id and numeric version, queue a render against it — looks almost identical from the outside. The storage is what changes what your team can do afterwards:
| Capability | Inline render | Durable project | Published template |
|---|---|---|---|
| Source stored server-side | No | Yes, with versions | Yes, version-pinned |
| Editable in Studio | Not applicable | Yes | Through its project |
| Typed input contract | None | Variables in the source | Discovered via a dedicated inputs endpoint, validated per row |
| Bulk from CSV or JSON | Not applicable | Not applicable | Yes, capped at 500 rows per batch |
| Render history | Single render | Per project | Per template, batch-pinned to one immutable version |
| Artifact retention | Temporary | Managed with the project | Managed with the project |
The template column is where reuse becomes contractual. Publishing a template freezes one project version behind a small typed input contract — string, number, boolean, color, media, sanitized HTML or bounded string arrays — and every render, single or bulk, is validated against exactly that version. Bulk rows are checked before queueing, invalid rows are reported without blocking valid ones, and Studio can correct and resubmit just the failures. That is the machinery you give up when you inline everything.
The decision in one table
| Situation | Choose | Why |
|---|---|---|
| One chart, OG image or diagram generated on demand | Inline | One consumer, one output, nothing to curate afterwards. |
| An export triggered by a user action ("render my summary card") | Inline | The artifact is a response, not an asset you manage. |
| A design a human still iterates on | Project | Studio editing, versions and review beat re-sending payloads. |
| An agent drafts, reviews and refines visuals | Project | Agents iterate, inspect versions and reuse media — the docs recommend projects for exactly this. |
| Monthly campaign variants from a spreadsheet | Template | Typed inputs, per-row validation and bulk with stable version pinning. |
| The same inline payload called from a second service | Project or template | A second consumer implies a contract; inline offers none. |
| Personalization at scale across hundreds of rows | Template | Bulk batches, per-row validation, corrected-row resubmits. |
The gray zone: repeated one-shots
The expensive anti-pattern is not using inline rendering — it is using it as a template substitute. If the same source body is deployed in three services, it drifts: one service gets the rounded-corners fix, two do not. There is no version to pin, no inputs endpoint to discover and no render history to compare against.
A practical rule keeps this honest: the first time a second consumer appears, or the third time you copy the payload, move the source into a project and publish it. Until then, inline is not a shortcut — it is the correct tool for the job.
From inline to reusable in four steps
The migration is deliberately boring because the format is shared:
| Step | Action | What changes |
|---|---|---|
| 1. Store the source | Create a project with the exact inline source | You receive a project id and a numeric version; nothing else changes. |
| 2. Lift moving parts into variables | Edit the project in Studio or via the API | Headlines, prices, images and colors become typed variables. |
| 3. Publish | Create the template from the project | The version is pinned; inputs become discoverable. |
| 4. Switch callers | Render through the template with an Idempotency-Key | Callers stop shipping design payloads; they ship values. |
Your inline request bodies do not become waste — they become the first version of the project. And because an image or video created through the API still opens in Studio, the designer who spots a kerning problem can fix it where the source lives instead of filing a ticket against a JSON blob in your repository.
Operational notes worth deciding early
Two details keep both modes honest in production. First, use an Idempotency-Key when creating renders — retries then converge on the same output instead of producing duplicate artifacts on either path. Second, prefer signed webhooks over frequent polling once one-shots leave your local machine; the four-step API loop (upload media, submit a source, queue a render, receive the result) is identical either way.
Keep the boundary honest in review, too: inline is a rendering tool, projects are a collaboration surface, templates are a contract. Most mature pipelines end up using all three — the only question is which one a given source deserves on day one.
FAQ
Is inline rendering cheaper than a project?
That is a pricing question rather than a rendering question — check the current plans on the pricing page before doing cost math. The lifecycle trade-offs above hold regardless of plan.
Can I render video inline as well?
Yes — inline rendering covers image and video sources. Set the same composition kind, frame rate and duration fields any video source uses, and remember that large media must be uploaded before the request.
Do inline renders appear in Studio?
No. Nothing durable is created, so there is no project to open — that is the point of the mode.
When should an agent use inline instead of a project?
When it truly needs one disposable frame and will not iterate. As soon as review loops, version inspection or media reuse begin, the guidance switches to projects.
Sources
https://jsoncut.com/docs/ — retrieved 2026-10-10 https://jsoncut.com/docs/inline-rendering/ — retrieved 2026-10-10 https://jsoncut.com/docs/templates/ — retrieved 2026-10-10 https://jsoncut.com/docs/quickstart/ — retrieved 2026-10-10 https://jsoncut.com/examples/ — retrieved 2026-10-10