Skip to main content
POST
/
pictoryapis
/
v2
/
transcription
/
{jobId}
/
highlights
Generate Highlights from Transcription Job
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "highlight_duration": 123,
  "webhook": "<string>",
  "language": "<string>"
}
'
{
  "success": true,
  "data": {
    "jobId": "bbd75639-c3cb-4add-bf7b-e4e39cffb3b0"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Generate concise video highlights from a completed transcription job using AI-powered extraction. This endpoint analyzes the transcript from your transcription job and identifies the most important segments to create a summary of your desired duration. What you will accomplish:
  • Extract key highlights from completed transcription jobs
  • Generate summaries of specific durations
  • Receive webhook notifications when processing completes
  • Create engaging short-form content from long videos
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.
This endpoint requires a completed transcription job. First use the Video Transcription API to generate a transcript, then use the returned jobId with this endpoint.

​
Request Headers

​
Authorization
string
required
API key for authentication
Authorization: YOUR_API_KEY
​
Content-Type
string
required
Must be set to application/json
Content-Type: application/json

​
Path Parameters

​
jobId
string
required
The unique identifier of the transcription job. This is the job ID returned from the Video Transcription API.Example: 95333422-8e76-4962-812b-5b6d7276451a

​
Body Parameters

​
highlight_duration
integer
Target duration for the video summary in seconds. The AI will select highlights that fit within this duration.Example: 30 for a 30-second summary, 60 for a 1-minute summary
​
webhook
string
Webhook URL where the summary results will be posted when processing completes. The webhook will receive a POST request with the summary data.Example: https://your-domain.com/api/webhooks/highlights
​
language
string
default:"en"
Language code for the transcript content.Supported values: en (English), es (Spanish), fr (French), de (German), it (Italian), pt (Portuguese), ja (Japanese), ko (Korean), zh (Chinese), ar (Arabic), hi (Hindi), ru (Russian), and more.Example: en for English, es for Spanish

​
Response

​
success
boolean
Indicates whether the request was successfully queued for processing
​
data
object
Contains the job information

​
Response Examples

{
  "success": true,
  "data": {
    "jobId": "bbd75639-c3cb-4add-bf7b-e4e39cffb3b0"
  }
}

​
Job Status Response (via Get Job API)

While the highlights job is processing: 
{
  "job_id": "bbd75639-c3cb-4add-bf7b-e4e39cffb3b0",
  "success": true,
  "data": {
    "status": "in-progress"
  }
}
When the highlights job completes, you will receive the full result with highlight markers via webhook or by polling the Get Job by ID API.

​
Code Examples

Replace YOUR_API_KEY with your actual API key and YOUR_JOB_ID with the transcription job ID.
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v2/transcription/YOUR_JOB_ID/highlights \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "highlight_duration": 30,
    "webhook": "https://your-domain.com/api/webhooks/highlights",
    "language": "en"
  }'

​
Usage Notes

Async Processing: This endpoint processes highlights asynchronously. You will receive a jobId immediately, and the actual highlights will be generated in the background.
Webhook Notifications: Provide a webhook URL to receive the completed highlights automatically when processing finishes. This is the recommended approach rather than polling.
Transcription Must Be Complete: The transcription job must be fully complete before you can generate highlights. If the transcription is still processing, you will receive a 4004 error.

​
Best Practices

  1. Wait for Transcription: Always check that the transcription job status is “completed” before calling this endpoint
  2. Webhook Implementation: Use webhooks instead of polling for better performance and user experience
  3. Duration Selection: Choose highlight duration based on your target platform (e.g., 15-30s for TikTok, 60s for YouTube Shorts)
  4. Error Handling: Implement retry logic for 4004 errors if the transcription is still processing