Render lifecycle and output
Poll, cancel and download asynchronous image and video renders.
Project, template and inline submissions all return the same canonical render resource.
Poll state
curl "$JSONCUT_API/api/v2/renders/$RENDER_ID" \
-H "X-API-Key: $JSONCUT_API_KEY"States are queued, rendering, completed, failed and cancelled. While a render runs, phase reports queued, preparing, capturing, encoding, uploading or finalizing, and progress goes from 0 to 100. Treat progress as presentation data; use the terminal status as the durable result. A failed render carries error, a stable errorCode (for example MISSING_MEDIA or RENDER_TIMEOUT) and errorRetryable.
Download
curl "$JSONCUT_API/api/v2/renders/$RENDER_ID/artifact" \
-H "X-API-Key: $JSONCUT_API_KEY" \
--output result.mp4The artifact route streams the file with its Content-Type and a file name in Content-Disposition, and accepts Range requests (206 Partial Content). Outputs expire 24 hours after completion; artifactExpiresAt on the render resource gives the exact time. The retention request field accepts project and template for compatibility, but every V2 output is temporary. Downloading an output requires a paid plan.
Cancel
curl -X DELETE "$JSONCUT_API/api/v2/renders/$RENDER_ID" \
-H "X-API-Key: $JSONCUT_API_KEY"Cancellation succeeds only while work is cancellable and returns 204 No Content. A later repeated request can report that the render no longer exists in a cancellable state; treat that as a reason to read the latest render resource.
Common outputs
- Images (
kind: "image"): PNG, WebP, JPG/JPEG and PDF. PDF holds one page per page of the design. Transparency works with PNG and WebP.imageQuality(1 to 100, default 90) applies to the lossy formats. - Video (
kind: "video"): MP4 (H.264 or HEVC), WebM (VP9), MOV (H.264 or ProRes) and GIF.fpscan be 12 to 60,widthup to 3840 andheightup to 2160.muted: truedrops the sound,loudness(-30 to -5 LUFS) sets a loudness target, andrangeStartwithrangeEndrenders a part of the timeline. - Transparent video:
transparent: truewith MOV (ProRes 4444) or WebM (VP9). These files render more slowly and are much larger. - Sound only: WAV, MP3, M4A or Opus hold the mixed sound of a video project without rendering frames.
- Editing handoff:
format: "handoff"returns a ZIP with FCPXML, Premiere XML, the media files, SRT captions and a report for editing programs.overlay: truealso renders text and graphics as a transparent ProRes 4444 video on the top track. - Review:
kind: "frame"renders one exact frame andkind: "grid"a contact sheet of sampled frames (frames,times,sampleCountorintervalSeconds, at most 100).
webhookEndpointId on a render request sends only that render's terminal event to one of your webhooks.
Do not retry a failed render blindly. Retry only when the error says retryable: true, and reuse the same idempotency key.
Validate before rendering
Studio and the MCP review workflow can preflight the pinned source and output settings before creating a final artifact. Public API submissions run the same source and output validation as part of the request and return HTTP 422 with the code VALIDATION_FAILED before an invalid render is queued.
For automated workflows, validate typed template inputs first, pin the intended project or template version and treat 422 as a correction step rather than a retry. Use Studio or MCP review before a large batch or whenever output kind, dimensions, codec or transparency changes.
Output compatibility
Image projects render as images. Video projects render as video, sound or a handoff package, and can also produce review frames or grids. Transparency needs a format that keeps alpha: PNG or WebP for stills, MOV (ProRes 4444) or WebM (VP9) for video.