Skip to main content
GET
Get Video Generation Job

Overview

This endpoint retrieves the current status and output of an AI video generation job using its unique job ID. While the generation is in progress, it returns the job status. Once the video generation completes, it returns the output including the video URL, thumbnail images, dimensions, duration, and AI credits consumed.
A valid API key is required to use this endpoint. Obtain your API key from the API Access page in your Pictory dashboard.

API Endpoint


Request Parameters

Path Parameters

uuid
required
The unique identifier (UUID) of the video generation job. This is the jobId returned by the Generate Video endpoint.Example: "4a09edf9-d071-4847-bda5-8dea913d80fe"

Headers

string
required
API key for authentication (starts with pictai_)

Response

In-Progress Response

Returned while the video is being generated:
string
The unique identifier of the video generation job
boolean
true while the job is processing
object
string
"in-progress" while the video is still being generated

Completed Response

Returned when the video has been generated successfully:
string
The unique identifier of the video generation job
boolean
true when the job has completed successfully
object
Contains the video generation output.
string
"completed" when the video has been generated successfully
string
Direct download URL for the generated video file (MP4)
string
Duration of the generated video (e.g., "8s")
number
Width of the generated video in pixels
number
Height of the generated video in pixels
string
URL for the video thumbnail image (JPG)
string
URL for the last frame of the video (PNG). This can be used as a firstFrameImageUrl in a subsequent generate video request to create a seamless continuation.
string
URL for the video preview image (JPG)
number
Number of AI credits consumed for this video generation

Failed Response

Returned when the video generation job has failed:
string
The unique identifier of the video generation job
boolean
false when the job has failed
object
string
"failed" when the video generation has failed
string
Error code identifying the failure type (e.g., "5001")
string
Descriptive message explaining the cause of the failure

Response Examples


Status Codes


Completed Response Fields


Code Examples

Replace YOUR_API_KEY with your actual API key and use the jobId returned from the Generate Video endpoint.

Polling Best Practices

Use a polling interval of 10–30 seconds when checking job status. Polling too frequently may result in rate limiting.
  1. Use webhooks when possible. Configure a webhook URL in the original generate video request to receive automatic notification when the job completes, rather than polling.
  2. Implement timeouts. Set a reasonable maximum wait time. Video generation can take several minutes depending on the model and duration selected.
  3. Handle failures gracefully. Inspect error_code and error_message in failed responses to determine the cause and whether the request can be retried.
  4. Use the last frame for continuations. The lastFrameImageUrl from a completed job can be passed as firstFrameImageUrl in a new generate video request to create a seamless video continuation.