Skip to main content
GET
/
pictoryapis
/
v1
/
jobs
/
{jobid}
Get Video Generation Job
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/jobs/{jobid} \
  --header 'Authorization: <authorization>'
{
    "job_id": "4a09edf9-d071-4847-bda5-8dea913d80fe",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
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

GET https://api.pictory.ai/pictoryapis/v1/jobs/{jobid}

​
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_)
Authorization: YOUR_API_KEY

​
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

{
    "job_id": "4a09edf9-d071-4847-bda5-8dea913d80fe",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
Status Codes

Status CodeDescription
200Request processed successfully. Check the status field in data to determine the job state (in-progress, completed, or failed).
401Unauthorized. The API key in the Authorization header is missing or invalid.
404Job not found. The provided jobid does not match any existing job.
500Internal server error. Retry the request after a brief delay.

​
Completed Response Fields

FieldDescription
urlDirect download link for the generated MP4 video file
durationDuration of the generated video (e.g., "8s")
widthWidth of the generated video in pixels
heightHeight of the generated video in pixels
thumbnailImageUrlAuto-generated thumbnail image for the video (JPG)
lastFrameImageUrlLast frame of the video (PNG), useful for creating video continuations
previewImageUrlPreview image for the video (JPG)
aiCreditsUsedNumber of AI credits consumed for this generation

​
Code Examples

Replace YOUR_API_KEY with your actual API key and use the jobId returned from the Generate Video endpoint.
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/jobs/4a09edf9-d071-4847-bda5-8dea913d80fe' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

​
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.