API Reference

The Render API is available over HTTPS at region-specific endpoints. It supports Cross-Origin Resource Sharing (CORS) for browser-based requests.

Base URL: https://render-{region}.impossible.io

Replace {region} with your project’s region (e.g., us-east-1, eu-west-1). See Regions & Endpoints for the full list.

Token-based rendering (v2)

All render workflows start by creating a token, then using it to retrieve the video.

Render endpoints

Method	Endpoint	Description
POST	`/v2/render/{project-id}`	Render a movie. Blocks until complete by default, or returns immediately with `async: true`.
POST	`/v2/token/{project-id}`	Create a render token without starting the render. Useful for pre-generating URLs.
GET	`/v2/progress/{token}`	Poll render progress for async renders. Returns `done` and `total` frame counts.

Retrieval endpoints

Method	Endpoint	Description
GET	`/v2/render/{token}.{ext}`	Render and deliver when complete. Highest latency, smoothest playback.
GET	`/v2/get/{token}.{ext}`	Progressive download. Starts delivering as frames become available.
GET	`/v2/play/{token}.{ext}`	Streaming. Lowest latency, renders on-demand as playback progresses.
DELETE	`/v2/token/{token}`	Delete a token and its associated rendered data.

Render modes

There are three ways to create a render token, each suited to different use cases.

Synchronous render (default)

POST https://render-{region}.impossible.io/v2/render/{project-id}

The API blocks until the render is complete, then returns the token, output URL, and expiration. This is the simplest approach — you get a ready-to-use URL in a single call.

{
  "movie": "welcome-video",
  "params": { "name": "Alex" }
}

Response:

{
  "token": "v2:us-east-1:abc123-def456-789",
  "url": "https://render-us-east-1.impossible.io/v2/render/v2:us-east-1:abc123-def456-789.mp4",
  "expires": 1709740800,
  "status": 200
}

Asynchronous render

POST https://render-{region}.impossible.io/v2/render/{project-id}

Set "async": true to return immediately with a token. The render continues in the background. Use the progress endpoint to poll until complete, then retrieve the video using the token.

{
  "movie": "welcome-video",
  "params": { "name": "Alex" },
  "async": true
}

Response:

{
  "token": "v2:us-east-1:abc123-def456-789"
}

Poll progress:

GET https://render-{region}.impossible.io/v2/progress/{token}

{
  "token": "v2:us-east-1:abc123-def456-789",
  "done": 42,
  "total": 100
}

When done >= total, the render is complete. Construct the retrieval URL manually:

https://render-{region}.impossible.io/v2/render/{token}.mp4

Token-only (no render)

POST https://render-{region}.impossible.io/v2/token/{project-id}

Creates a token without starting a render. The render is triggered on first retrieval (when someone requests the video URL). Useful for pre-generating URLs before the video is needed.

{
  "movie": "welcome-video",
  "params": { "name": "Alex" }
}

Response:

{
  "token": "v2:us-east-1:abc123-def456-789",
  "expires": 1709740800,
  "status": 200
}

Construct the retrieval URL from the token:

https://render-{region}.impossible.io/v2/render/{token}.mp4

The render starts when this URL is first requested.

* Tip

Use synchronous render when you need the video immediately. Use async render for long renders where you want to show progress. Use token-only when you’re generating URLs ahead of time (e.g., in emails or landing pages) and the video will be rendered on demand.

Request body

Parameter	Type	Required	Default	Description
`movie`	String \| Object	Yes	—	The dynamic movie name, or an object mapping file extensions to movie names for multi-format rendering.
`params`	Object	No	`{}`	Key-value pairs for your dynamic movie variables (names, text, image URLs, colors, etc.).
`async`	Boolean	No	`false`	When true, the render endpoint returns immediately with a token. Poll /v2/progress/{token} for status. Only applies to POST /v2/render.
`parallel`	Number	No	`1`	Number of distributed render servers to use. Higher values render faster for long videos.
`routingkey`	String	No	`"default"`	Routing key for dedicated render clusters. Only needed for enterprise plans.
`upload`	Object \| Array	No	—	Upload task definition(s) to send the rendered video directly to third-party services. See Uploading in the Rendering guide.

Direct rendering (v1)

Renders and delivers in a single request. Simpler but less flexible — no upload support, no token reuse.

Method	Endpoint	Description
GET	`/v1/render/{project-id}/{movie}.{ext}`	Render and deliver when complete.
GET	`/v1/get/{project-id}/{movie}.{ext}`	Progressive download.
GET	`/v1/play/{project-id}/{movie}.{ext}`	Streaming playback.

Pass dynamic parameters as query string values: ?name=Alex&company=Acme.

Supported output formats

Video formats

Format	Extension	Notes
MP4 (H.264)	`.mp4`	Most compatible. Render mode only.
WebM (VP8/VP9)	`.webm`	All retrieval modes. Best for streaming.
Flash Video	`.flv`	Legacy. All retrieval modes.
HLS	`.m3u8`	Adaptive streaming. Render + get modes.
MPEG-DASH	`.mpd`	Adaptive streaming. Render + get modes.
MPEG-2	`.mpeg`	Broadcast use.
Windows Media	`.wmv`	Legacy.
GIF	`.gif`	Animated GIF output.
Apple ProRes	`.mov`	Professional editing.

Image formats

Format	Extension	Parameters
JPEG	`.jpg`	`frame` (frame number), `q` (quality 10-99)
PNG	`.png`	`frame` (frame number), `compression` (0-9)
TIFF	`.tif`	`frame` (frame number)

Image sequences

Format	Extension	Parameters
ZIP archive	`.zip`	`format` (png/jpg/tif), `from` (start frame), `to` (end frame), `q` (JPEG quality), `compression` (PNG compression)

Error responses

Status	Meaning
200	Success. Token or video returned.
201	Accepted (async upload). Processing in background.
400	Bad request. Check your request body.
404	Project or movie not found.
429	Rate limited. Too many concurrent requests.
500	Server error. Retry with backoff.

Authentication

The API accepts an optional API key as a Bearer token in the Authorization header:

Authorization: Bearer <apiKey>

Render and retrieval endpoints do not require authentication. Rate limiting is based on your account tier.