Retrieve a video

You can use Retrieve a video endpoint to pull for the video status.

A video that has finished rendering may still be awaiting content moderation review. Until that review is final, the video is returned with in_progress status rather than complete, and its download, thumbnail and captions are not included. Keep polling until the status is complete.

Videos rejected by content moderation return a 404 response unless includeRejected is true, in which case they are returned with rejected status and without download, thumbnail or captions.

Authentication

Authorizationstring

API Key authentication via header

Path parameters

video_idstringRequired

The video ID to retrieve

Query parameters

includeRejectedbooleanOptionalDefaults to false

When true, a video rejected by content moderation is returned with a rejected status instead of a 404 response. Defaults to false.

Response

OK.

callbackIdstringOptional

Use callback ID to link videos back to the initial request. For example, if you are making a personalized video for a customer, you could enter the customer's email as a callback ID. This way, you can tell who the video is for, once its generated..

createdAtintegerOptional

UNIX timestamp representing the time video was created.

ctaSettingsobjectOptional

Settings for a call-to-action button.

descriptionstringOptionalDefaults to

Description of the video to be shown on the share page.

testbooleanOptionalDefaults to false

Test videos are free and not counted towards your quota. If you create a video in the “test” mode, we will overlay a watermark over your video.

downloadstringOptional

Withheld for rejected videos and videos held for moderation review.

durationstringOptional

idstringOptionalformat: "uuid"

lastUpdatedAtintegerOptional

statusenumOptional

Video status. A rendered video that is still awaiting moderation review is reported as in_progress until the review is final.

thumbnailobject or nullOptional

titlestringOptionalDefaults to

Title of the video to be shown on the share page.

visibilityenumOptionalDefaults to private

Public videos will be visible to anyone with a share URL.

Private videos can only be downloaded via a time-limited download link. See Retrieve a video for details.

Visibility can be changed also once the video is created via Update a video.

Allowed values:

captionsobjectOptional

Downloadable captions files. Omitted when no captions are available, and for videos that are rejected or held for moderation review.

contentProvenanceobject or nullOptional

Content provenance (C2PA) information for the video. Only present when the video has been signed.

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error