Get Storyboard Preview Job by ID

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

Show renderParams

renderParams

object

The rendering data used for previewing and rendering videos. This object contains the complete scene composition, including output settings, audio elements, background visuals, and text overlays.

output

object

Video output configuration

width

integer

Video width in pixels (e.g., 1920)

height

integer

Video height in pixels (e.g., 1080)

format

string

Output format (e.g., "mp4")

name

string

Output file name

title

string

Video title

elements

array

Array of video elements including audio tracks (voice-over, background music), background visuals (videos, images, solid colors), and text overlays (scene text, titles). Each element includes startTime, duration, elementType, and type-specific properties.

sceneMarkers

array

Array of scene marker objects that define scene boundaries.Each marker contains:

time (number) — Scene duration in seconds
showSceneNumber (string) — Scene label (e.g., "Scene 1")
uuid (string) — Unique scene identifier
startTime (number) — Scene start time in seconds

subtitles

array

Array of subtitle objects with timing information.Each subtitle contains:

subtitle (string) — The subtitle text
start (number) — Start time in seconds
end (number) — End time in seconds

projectId

string

The project ID (matches the job ID)

Show storyboard

storyboard

object

The processed input storyboard. This is the fully resolved version of the original storyboard request, with all scenes broken down, voice-over URLs generated, and visual selections applied.

videoName

string

Name of the video project

webhook

string

The webhook URL configured for the job

webhookInput

object

Custom data passed through from the original request

smartLayoutName

string

The smart layout applied to the video

voiceOver

object

Voice-over configuration

backgroundMusic

object

Background music configuration, including enabled, volume, autoMusic, and musicUrl

scenes

array

Array of processed scene objects. Each scene contains:

story (string) — Scene text with keyword highlights in <strong> tags
voiceOver (object) — Voice-over configuration with the generated audio URL and timing clips
backgroundMusic (object) — Per-scene music settings
background (object) — Visual background with visualUrl, type, and settings

language

string

Language code (e.g., "en")

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.

aiCreditsUsed

number

Total AI credits consumed for generating AI visuals (images and video clips) in this storyboard. Present only when the storyboard includes scenes with aiVisual configuration. The value is the sum of credits used across all AI-generated scenes.

Response Examples

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

Key Response Fields

Field	Description
`renderParams`	The 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.
`storyboard`	The 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.
`previewUrl`	URL to view the storyboard preview. Open in a browser or embed in an iframe. Refer to the Embed Preview Player guide for integration details.
`projectUrl`	URL to open the saved project in the Pictory web app. Present only when `saveProject: true`.
`projectId`	Unique identifier of the saved project. Use with the Render Project or Get Project by ID APIs. Present only when `saveProject: true`.
`aiCreditsUsed`	Total AI credits consumed for generating AI visuals (images and video clips). Present only when the storyboard includes scenes with `aiVisual` configuration.

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:

Review the Preview

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

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.

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.

Use webhooks when possible. Configure a webhook URL in the storyboard request to receive automatic notification when the job completes, rather than polling.
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.
Cache results. Once a storyboard job completes, store the renderParams and storyboard data locally. Completed job data may be cleaned after a retention period.

Documentation Index

​Overview

​API Endpoint

​Request Parameters

​Path Parameters

​Headers

​Response

​In-Progress Response

​Failed Response

​Completed Response

​Response Examples

​Key Response Fields

​Code Examples

​Working with the Completed Response

​Customizing and Rendering the Video

​Re-submitting a Modified Storyboard

​Polling Best Practices

Overview

API Endpoint

Request Parameters

Path Parameters

Headers

Response

In-Progress Response

Failed Response

Completed Response

Response Examples

Key Response Fields

Code Examples

Working with the Completed Response

Customizing and Rendering the Video

Re-submitting a Modified Storyboard

Polling Best Practices