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

​
Overview

Generate concise video highlights from your own custom or edited transcript. This endpoint is useful when you’ve manually edited the transcription output or want to provide your own transcript data directly. The AI analyzes your transcript and identifies the most important segments to create a summary of your desired duration. What you’ll accomplish:
  • Generate highlights from manually edited transcripts
  • Use custom transcript data that doesn’t come from the transcription API
  • Create summaries from transcripts you’ve corrected or enhanced
  • Apply highlights to videos with pre-existing transcript data
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.
If you haven’t edited the transcript and just want highlights from a transcription job, use the Generate Highlights from Transcription Job endpoint instead - it’s simpler and requires less data.

​
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

​
Body Parameters

​
transcript
object[]
required
Array of sentence-level transcript segments with word-level timing information.
The “Try it now” form cannot properly handle nested array inputs. Please use cURL, Postman, or one of the code examples below to test this endpoint.
Each sentence object must contain:
  • uid (string, required): Unique identifier for the sentence
  • speakerId (number, required): Speaker identifier (e.g., 1)
  • words (array, required): Array of word objects
Each word object must contain:
  • uid (string, required): Unique identifier for the word
  • word (string, required): The word text
  • start_time (number, required): Start time in seconds (supports decimals)
  • end_time (number, required): End time in seconds (supports decimals)
  • speakerId (number, required): Speaker identifier
  • sentence_index (number, required): Index of the sentence
Example format:
[
  {
    "uid": "sentence-1",
    "speakerId": 1,
    "words": [
      {
        "uid": "word-1",
        "word": "Important",
        "start_time": 0.0,
        "end_time": 0.5,
        "speakerId": 1,
        "sentence_index": 0
      },
      {
        "uid": "word-2",
        "word": "content",
        "start_time": 0.5,
        "end_time": 1.0,
        "speakerId": 1,
        "sentence_index": 0
      }
    ]
  }
]
​
highlight_duration
integer
required
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
​
duration
integer
default:"0"
Total duration of the source video in seconds. This helps the AI understand the full context when generating highlights.Example: 120 for a 2-minute video, 300 for a 5-minute video
​
webhook
string
Webhook URL where the summary results will be posted when processing completes.Example: https://your-domain.com/api/webhooks/video-summary
​
language
string
default:"en"
Language code for the transcript content.Supported values: en (English), es (Spanish), fr (French), de (German), it (Italian), pt (Portuguese), 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’ll 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 that starts with pictai_
curl --location 'https://api.pictory.ai/pictoryapis/v2/transcription/highlights' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transcript": [
        {
            "uid": "sentence-1",
            "speakerId": 1,
            "words": [
                {
                    "uid": "word-1-1",
                    "word": "Click",
                    "start_time": 0.64,
                    "end_time": 0.96,
                    "speakerId": 1,
                    "sentence_index": 0
                },
                {
                    "uid": "word-1-2",
                    "word": "the",
                    "start_time": 0.96,
                    "end_time": 1.12,
                    "speakerId": 1,
                    "sentence_index": 0
                },
                {
                    "uid": "word-1-3",
                    "word": "play",
                    "start_time": 1.12,
                    "end_time": 1.36,
                    "speakerId": 1,
                    "sentence_index": 0
                },
                {
                    "uid": "word-1-4",
                    "word": "button.",
                    "start_time": 1.36,
                    "end_time": 1.68,
                    "speakerId": 1,
                    "sentence_index": 0
                }
            ]
        },
        {
            "uid": "sentence-2",
            "speakerId": 1,
            "words": [
                {
                    "uid": "word-2-1",
                    "word": "This",
                    "start_time": 2.0,
                    "end_time": 2.3,
                    "speakerId": 1,
                    "sentence_index": 1
                },
                {
                    "uid": "word-2-2",
                    "word": "is",
                    "start_time": 2.3,
                    "end_time": 2.5,
                    "speakerId": 1,
                    "sentence_index": 1
                },
                {
                    "uid": "word-2-3",
                    "word": "important",
                    "start_time": 2.5,
                    "end_time": 3.0,
                    "speakerId": 1,
                    "sentence_index": 1
                },
                {
                    "uid": "word-2-4",
                    "word": "content.",
                    "start_time": 3.0,
                    "end_time": 3.5,
                    "speakerId": 1,
                    "sentence_index": 1
                }
            ]
        }
    ],
    "highlight_duration": 10,
    "duration": 120,
    "language": "en"
}'

​
Common Use Cases

​
1. Generate Highlights from Edited Transcript

After manually correcting or enhancing a transcript: 
import requests

def generate_highlights_from_edited_transcript(edited_transcript, duration, api_key):
    """
    Generate highlights after editing the transcript for accuracy
    """
    url = "https://api.pictory.ai/pictoryapis/v2/transcription/highlights"
    headers = {
        "Authorization": api_key,
        "Content-Type": "application/json"
    }

    payload = {
        "transcript": edited_transcript,
        "highlight_duration": 30,
        "duration": duration,
        "language": "en",
        "webhook": "https://your-domain.com/webhooks/highlights"
    }

    response = requests.post(url, json=payload, headers=headers)
    data = response.json()

    if data.get("success"):
        print(f"Highlights job created: {data['data']['jobId']}")
        return data['data']['jobId']
    else:
        print(f"Failed: {data.get('message')}")
        return None

# Use after editing transcript
edited_transcript = load_edited_transcript_from_database()
job_id = generate_highlights_from_edited_transcript(edited_transcript, 120, "YOUR_API_KEY")

​
2. Use Custom Transcript from External Source

When you have transcript data from a third-party service: 
async function generateHighlightsFromExternalTranscript(externalTranscript) {
  // Convert external transcript format to Pictory format
  const pictoryTranscript = externalTranscript.sentences.map((sentence, index) => ({
    uid: `sentence-${index + 1}`,
    speakerId: sentence.speaker_id || 1,
    words: sentence.words.map((word, wordIndex) => ({
      uid: `word-${index + 1}-${wordIndex + 1}`,
      word: word.text,
      start_time: word.start,
      end_time: word.end,
      speakerId: sentence.speaker_id || 1,
      sentence_index: index
    }))
  }));

  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v2/transcription/highlights',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        transcript: pictoryTranscript,
        highlight_duration: 60,
        duration: externalTranscript.total_duration,
        language: 'en'
      })
    }
  );

  const data = await response.json();
  return data.success ? data.data.jobId : null;
}

​
Usage Notes

Async Processing: This endpoint processes highlights asynchronously. You’ll 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. This is the recommended approach instead of polling.
Transcript Format: Ensure your transcript segments are in chronological order with accurate start and end times. The AI uses timing information to create seamless highlight clips.
Duration Limits: The highlight_duration should be shorter than your total transcript duration. The AI will select the most important segments that fit within the target duration.

​
Best Practices

​
Transcript Quality

  1. Accurate Timing: Ensure start and end times are precise for smooth highlight transitions
  2. Complete Sentences: Structure transcript at natural sentence boundaries for better context
  3. No Overlaps: Word timings should not overlap
  4. Chronological Order: Sentences and words must be ordered by time
  5. Unique IDs: Use unique uid values for all sentences and words

​
Duration Selection

  1. Platform Optimization:
    • TikTok/Reels: 15-30 seconds
    • Instagram: 30-60 seconds
    • YouTube Shorts: 60 seconds
    • LinkedIn: 30-90 seconds
  2. Content Type:
    • Product demos: 60-90 seconds
    • Testimonials: 30-45 seconds
    • Educational: 45-60 seconds

​
Webhook Implementation

  1. Return 200 OK Quickly: Process the webhook payload asynchronously to avoid timeouts
  2. Implement Retry Logic: Webhooks may be retried if they fail
  3. Validate Signatures: Implement webhook signature validation for security
  4. Log All Webhooks: Keep logs for debugging and audit trails