Video APIv1 Home OpenAPI spec

Docs › Best practices

Best practices

  • Keep the key server-side, and pass only pre-signed URLs to browsers and apps.
  • Store the videoId as soon as you create a video: it's how you resume, check status, or abort.
  • Retry safely. Send an Idempotency-Key header with POST /videos, POST /videos/{id}/complete, and POST /videos/{id}/reprocess. Part uploads can be retried with fresh URLs. See Idempotency.
  • Poll politely: every 5–15 seconds, and stop at a final status (SUCCEEDED, FAILED, TIMED_OUT, ABORTED).
  • Fetch download links when needed. They expire after 15 minutes, so don't cache them.
  • Handle errors by the error code, not by the message text.