Skip to main content
GET
/
pictoryapis
/
v1
/
jobs
/
{jobid}
Get Storyboard Preview Job by ID
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/jobs/{jobid} \
  --header 'Authorization: <authorization>'
{
    "job_id": "a1d36612-326d-4b81-aece-411f8aed4c70",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
Overview

This endpoint retrieves the current status and results of a storyboard preview job using its unique job ID. While processing is in progress, it returns the current job status. Once the job completes, it returns the full storyboard preview data, including render parameters, the processed storyboard, and the preview URL.
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 storyboard preview job. This value is the jobId returned by the Create Storyboard Preview endpoint.Example: "a1d36612-326d-4b81-aece-411f8aed4c70"

​
Headers

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

​
Response

​
In-Progress Response

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

​
Failed Response

Returned when the storyboard preview job has failed during processing:
​
job_id
string
The unique identifier of the storyboard preview job
​
success
boolean
false when the job has failed
​
data
object
​
status
string
"failed" — the storyboard preview generation has failed
​
error_code
string
Error code identifying the failure type (e.g., "TEXT_TO_VIDEO_FAILED")
​
error_message
string
Descriptive message explaining the cause of the failure

​
Completed Response

Returned when the storyboard preview has been successfully generated. The response contains the full preview data:
​
job_id
string
The unique identifier of the storyboard preview job
​
success
boolean
true when the job has completed successfully
​
data
object
Contains the complete storyboard preview results.
​
status
string
"completed" — the storyboard preview has been generated successfully
​
previewUrl
string
URL to view the storyboard preview in a browser. This URL can also be embedded in an iframe for app integrations. Refer to the Embed Preview Player guide for details.
​
projectUrl
string
URL to open the saved project in the Pictory web app. Present only when saveProject was set to true in the storyboard request.
​
projectId
string
Unique identifier of the saved project. Use this value with the Render Project or Get Project by ID APIs. Present only when saveProject was set to true in the storyboard request.

​
Response Examples

{
    "job_id": "a1d36612-326d-4b81-aece-411f8aed4c70",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
Key Response Fields

FieldDescription
renderParamsThe rendering data for the video. To customize the video, modify this data and submit it to the Render Video API. To update the preview with changes, save the modified data using the Update Storyboard Elements API. After saving, the preview URL will reflect the updates.
storyboardThe processed input storyboard with all scenes resolved. Use this object to submit a new storyboard request with modifications. Re-submissions process faster because the scenes, voices, and visuals have already been resolved.
previewUrlURL to view the storyboard preview. Open in a browser or embed in an iframe. Refer to the Embed Preview Player guide for integration details.
projectUrlURL to open the saved project in the Pictory web app. Present only when saveProject: true.
projectIdUnique identifier of the saved project. Use with the Render Project or Get Project by ID APIs. Present only when saveProject: true.

​
Code Examples

Replace YOUR_API_KEY with your actual API key and use the jobId returned from the Create Storyboard Preview endpoint.
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/jobs/a1d36612-326d-4b81-aece-411f8aed4c70' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

​
Working with the Completed Response

​
Customizing and Rendering the Video

After the storyboard preview is ready, the following options are available:
1

Review the Preview

Open the previewUrl in a browser to review the storyboard preview, including all scenes, visuals, and text overlays.
2

Update Elements (Optional)

To modify scene visuals, text, or other elements, update the renderParams.elements data and save it using the Update Storyboard Elements API. The preview URL will reflect the saved changes.
3

Render the Final Video

Submit the renderParams data (modified or as-is) to the Render Video API to produce the final rendered video file.

​
Re-submitting a Modified Storyboard

To change the original storyboard structure (for example, different text, a different voice, or different scenes), use the storyboard object from the completed response as the request body for a new Create Storyboard Preview request. This approach processes faster because the scenes, voice-over audio, and visual selections have already been resolved.

​
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 storyboard request to receive automatic notification when the job completes, rather than polling.
  2. Implement timeouts. Set a maximum wait time. Storyboard previews typically complete within a few minutes, depending on the number of scenes and voice-over generation requirements.
  3. Cache results. Once a storyboard job completes, store the renderParams and storyboard data locally. Completed job data may be cleaned after a retention period.