JsonCutDocs

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.mp4

The 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. fps can be 12 to 60, width up to 3840 and height up to 2160. muted: true drops the sound, loudness (-30 to -5 LUFS) sets a loudness target, and rangeStart with rangeEnd renders a part of the timeline.
  • Transparent video: transparent: true with 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: true also renders text and graphics as a transparent ProRes 4444 video on the top track.
  • Review: kind: "frame" renders one exact frame and kind: "grid" a contact sheet of sampled frames (frames, times, sampleCount or intervalSeconds, 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.