Skip to main content

Submit, track and retrieve a render

A render submission creates an asynchronous job. Acceptance means the job was submitted, not that a video or image is ready.

The complete flow​

  1. Build a project or select a stored template and variable values.
  2. Validate the exact request and inspect its cost.
  3. Submit to the video or image endpoint. Credits are reserved during submission.
  4. Store the returned jobId with your own business record before doing other work.
  5. Poll GET /api/jobs/{jobId} or receive a webhook.
  6. On completion, read the output URL and store it where your application needs it. On failure, record failedReason and decide whether the cause can be corrected.

The downloadable Node.js example implements validation, a single submission and bounded polling. It validates only unless you explicitly pass --render.

Job state and progress​

The queue may report intermediate states such as waiting, delayed, prioritized, active or waiting-children. Keep waiting within your deadline unless state is completed or failed. An unexpected state is useful diagnostic information; do not invent a successful result from it.

progress can be a number or an object with percentage and other stage information. It is a progress hint, not a completion test. A value of 100 does not replace checking state and result.

Job data can come from the live queue or stored history. Queue timestamps use epoch milliseconds; stored timestamp fields can be date strings. Normalize them before doing arithmetic. Do not assume the response has one timestamp representation forever.

Extract the output URL​

For a completed job, result can be an object with url or a URL string from stored history:

const url = typeof job.result === "string" ? job.result : job.result?.url;
if (job.state === "completed" && !url) {
  throw new Error("Completed job has no output URL; retain the job ID for investigation.");
}

Only use the final media when the job reports completion and a usable URL. A thumbnail or preview is not the finished output. Keep your job ID alongside the output URL for support and reconciliation.

Polling and webhooks​

For polling, use a delay, an overall deadline and a timeout on each network request. Retry safe status reads after temporary failures; honor Retry-After when present. A polling timeout means the client stopped waiting, not that rendering failed. Resume tracking the same job.

For production automation, signed account webhooks avoid constant polling. Verify the original request bytes and timestamp, acknowledge promptly, and handle repeated deliveries idempotently. A per-request webhookUrl is unsigned; see webhook security and payloads.

Failures, cancellation and retention​

Submission failures and render failures are different. A rejected submission may have no job ID. An accepted job can later fail while fetching media or rendering. See errors and retries before resubmitting.

Job deletion requires a dashboard session/JWT; an API key can read job status but cannot call the delete endpoint. Deleting a queued job can cancel work and trigger the applicable refund behavior. An active job cannot simply be deleted; the API returns a conflict. Deleting a completed render can also remove its stored output. Treat deletion as a lifecycle action, not as a way to hide a dashboard row.

Do not assume CDN output is a permanent archive. If your product requires long-term retention, copy completed media to storage you control under your own retention policy. See media and URLs.