Render lifecycle and output

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"

Typical states are queued, rendering, completed, failed and cancelled. Treat progress as presentation data; use the terminal status as the durable result.

Download

curl "$JSONCUT_API/api/v2/renders/$RENDER_ID/artifact" \
  -H "X-API-Key: $JSONCUT_API_KEY" \
  --output result.mp4

The artifact route supports binary streaming. Use the file name, MIME type and retention metadata returned by the render resource.

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: PNG, JPEG/JPG and WebP; transparency is meaningful for PNG and WebP.
• Video containers: MP4, WebM, MOV and GIF with only the codec combinations accepted by the live OpenAPI contract.
• Review: exact frames and contact sheets are available through the MCP review workflow; they are not separate public HTTP endpoints.

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 422 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 and can also produce bounded review frames or grids through Studio/MCP review workflows. Transparency is relevant to PNG and WebP stills and must be compatible with the chosen source and output.