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

jobid
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

Authorization
string
required
API key for authentication (starts with pictai_)

Response

In-Progress Response

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

Completed Response

Returned when the video has been generated successfully:
job_id
string
The unique identifier of the video generation job
success
boolean
true when the job has completed successfully
data
object
Contains the video generation output.
status
string
"completed" when the video has been generated successfully
url
string
Direct download URL for the generated video file (MP4)
duration
string
Duration of the generated video (e.g., "8s")
width
number
Width of the generated video in pixels
height
number
Height of the generated video in pixels
thumbnailImageUrl
string
URL for the video thumbnail image (JPG)
lastFrameImageUrl
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.
previewImageUrl
string
URL for the video preview image (JPG)
aiCreditsUsed
number
Number of AI credits consumed for this video generation

Failed Response

Returned when the video generation job has failed:
job_id
string
The unique identifier of the video generation job
success
boolean
false when the job has failed
data
object
status
string
"failed" when the video generation has failed
error_code
string
Error code identifying the failure type (e.g., "5001")
error_message
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.