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>"
}
'import requests
url = "https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights"
payload = {
"highlight_duration": 123,
"webhook": "<string>",
"language": "<string>"
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
body: JSON.stringify({highlight_duration: 123, webhook: '<string>', language: '<string>'})
};
fetch('https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'highlight_duration' => 123,
'webhook' => '<string>',
'language' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights"
payload := strings.NewReader("{\n \"highlight_duration\": 123,\n \"webhook\": \"<string>\",\n \"language\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.body("{\n \"highlight_duration\": 123,\n \"webhook\": \"<string>\",\n \"language\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"highlight_duration\": 123,\n \"webhook\": \"<string>\",\n \"language\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"jobId": "bbd75639-c3cb-4add-bf7b-e4e39cffb3b0"
}
}
{
"success": false,
"data": {
"error_code": "4004",
"error_message": "Highlights could not be generated as transcription is still in-progress or not found."
}
}
{
"message": "Unauthorized"
}
Video Summary and Transcription
Generate Highlights from Transcription Job
Generate AI-powered video highlights from a completed transcription job
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>"
}
'import requests
url = "https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights"
payload = {
"highlight_duration": 123,
"webhook": "<string>",
"language": "<string>"
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
body: JSON.stringify({highlight_duration: 123, webhook: '<string>', language: '<string>'})
};
fetch('https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'highlight_duration' => 123,
'webhook' => '<string>',
'language' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights"
payload := strings.NewReader("{\n \"highlight_duration\": 123,\n \"webhook\": \"<string>\",\n \"language\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.body("{\n \"highlight_duration\": 123,\n \"webhook\": \"<string>\",\n \"language\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pictory.ai/pictoryapis/v2/transcription/{jobId}/highlights")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"highlight_duration\": 123,\n \"webhook\": \"<string>\",\n \"language\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"jobId": "bbd75639-c3cb-4add-bf7b-e4e39cffb3b0"
}
}
{
"success": false,
"data": {
"error_code": "4004",
"error_message": "Highlights could not be generated as transcription is still in-progress or not found."
}
}
{
"message": "Unauthorized"
}
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
string
required
API key for authentication
Authorization: YOUR_API_KEY
string
required
Must be set to
application/jsonContent-Type: application/json
Path Parameters
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-5b6d7276451aBody Parameters
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 summarystring
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/highlightsstring
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 SpanishResponse
boolean
Indicates whether the request was successfully queued for processing
object
Contains the job information
Show data properties
Show data properties
string
Unique identifier for the highlights generation job. Use this ID to track the job status via the Get Job by ID API.
Response Examples
{
"success": true,
"data": {
"jobId": "bbd75639-c3cb-4add-bf7b-e4e39cffb3b0"
}
}
{
"success": false,
"data": {
"error_code": "4004",
"error_message": "Highlights could not be generated as transcription is still in-progress or not found."
}
}
{
"message": "Unauthorized"
}
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"
}
}
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"
}'
import requests
job_id = "95333422-8e76-4962-812b-5b6d7276451a" # Transcription job ID
url = f"https://api.pictory.ai/pictoryapis/v2/transcription/{job_id}/highlights"
headers = {
"Authorization": "YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"highlight_duration": 30,
"language": "en",
"webhook": "https://your-domain.com/api/webhooks/highlights"
}
response = requests.post(url, json=payload, headers=headers)
data = response.json()
if data.get("success"):
print(f"Highlights Job ID: {data['data']['jobId']}")
print("Highlights generation started successfully")
else:
print(f"Error: {data.get('message', 'Unknown error')}")
const jobId = '95333422-8e76-4962-812b-5b6d7276451a'; // Transcription job ID
const response = await fetch(
`https://api.pictory.ai/pictoryapis/v2/transcription/${jobId}/highlights`,
{
method: 'POST',
headers: {
'Authorization': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
highlight_duration: 30,
language: 'en',
webhook: 'https://your-domain.com/api/webhooks/highlights'
})
}
);
const data = await response.json();
if (data.success) {
console.log(`Highlights Job ID: ${data.data.jobId}`);
console.log('Highlights generation started successfully');
} else {
console.log(`Error: ${data.message || 'Unknown error'}`);
}
<?php
$jobId = "95333422-8e76-4962-812b-5b6d7276451a"; // Transcription job ID
$url = "https://api.pictory.ai/pictoryapis/v2/transcription/{$jobId}/highlights";
$payload = [
'highlight_duration' => 30,
'language' => 'en',
'webhook' => 'https://your-domain.com/api/webhooks/highlights'
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: YOUR_API_KEY',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($response, true);
if ($httpCode === 200 && $data['success']) {
echo "Highlights Job ID: " . $data['data']['jobId'] . "\n";
echo "Highlights generation started successfully\n";
} else {
echo "Error: " . ($data['message'] ?? 'Unknown error') . "\n";
}
?>
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
jobId := "95333422-8e76-4962-812b-5b6d7276451a" // Transcription job ID
url := fmt.Sprintf("https://api.pictory.ai/pictoryapis/v2/transcription/%s/highlights", jobId)
payload := map[string]interface{}{
"highlight_duration": 30,
"language": "en",
"webhook": "https://your-domain.com/api/webhooks/highlights",
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result map[string]interface{}
json.Unmarshal(body, &result)
if result["success"].(bool) {
data := result["data"].(map[string]interface{})
fmt.Printf("Highlights Job ID: %s\n", data["jobId"])
fmt.Println("Highlights generation started successfully")
} else {
fmt.Printf("Error: %s\n", result["message"])
}
}
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
- Wait for Transcription: Always check that the transcription job status is “completed” before calling this endpoint
- Webhook Implementation: Use webhooks instead of polling for better performance and user experience
- Duration Selection: Choose highlight duration based on your target platform (e.g., 15-30s for TikTok, 60s for YouTube Shorts)
- Error Handling: Implement retry logic for 4004 errors if the transcription is still processing
Related Endpoints
- Video Transcription API - Generate the transcription job first
- Generate Highlights from Custom Transcript - Use edited transcript instead
- Get Job by ID - Check job status and retrieve results
Was this page helpful?
