Skip to main content
POST
https://api.pictory.ai
/
pictoryapis
/
v2
/
transcription
Video Transcription
curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v2/transcription \
  --header 'Content-Type: application/json' \
  --data '
{
  "fileUrl": "<string>",
  "mediaType": "<string>",
  "language": "<string>",
  "webhook": "<string>",
  "transcript": [
    {}
  ],
  "highlight": [
    {}
  ]
}
'
{
  "success": true,
  "data": {
    "jobId": "<string>"
  }
}

​
Overview

The Video Transcription API generates accurate transcriptions and subtitles for your video or audio files. It supports over 20 languages and can automatically detect speech, convert it to text, and provide timing information for subtitle creation. You can also provide your own transcript or request AI-generated highlights from the transcription. This endpoint processes files asynchronously and returns a job ID that you can use to track the transcription status. Once complete, you’ll receive the full transcript with precise timing information in formats suitable for SRT, VTT, or JSON subtitle files.

​
Request Parameters

​
fileUrl
string
required
The URL of the video or audio file to transcribe. The file must be accessible via HTTPS.Supported formats: MP4, MOV, AVI, MP3, WAV, M4A
​
mediaType
string
required
The type of media file being transcribed.Options:
  • video - Video file with audio track
  • audio - Audio-only file
​
language
string
required
The language code for transcription. Must be one of the supported languages.See the Supported Languages section below for the complete list.
​
webhook
string
required
The URL where the transcription results will be sent via POST request when processing is complete.The webhook will receive the complete transcript data including text, timing information, and any requested highlights.
​
transcript
object[]
Optional custom transcript to use instead of automatic speech recognition. Useful when you already have accurate transcript text and want to generate highlights or verify timing.Each object contains:
  • text (string, required): The spoken text segment
  • start (number, required): Start time in seconds (supports integers and decimals, e.g., 0, 2.5, 10.75)
  • end (number, required): End time in seconds (supports integers and decimals, e.g., 3, 5.2, 15.5)
Example format:
[
  {
    "text": "Welcome to our product demo.",
    "start": 0,
    "end": 3.5
  },
  {
    "text": "Today we'll show you the key features.",
    "start": 3.5,
    "end": 7.2
  }
]
​
highlight
object[]
Optional array to request AI-generated highlights from the transcription. Each object specifies desired highlight characteristics.Each object contains:
  • duration (number): Target duration for the highlight in seconds (supports integers and decimals, e.g., 30, 45.5, 60)
  • type (string): Type of highlight (e.g., “summary”, “key_moments”)
Example format:
[
  {
    "duration": 30,
    "type": "summary"
  },
  {
    "duration": 60,
    "type": "key_moments"
  }
]

​
Supported Languages

The transcription service supports the following languages:
  • en-US - English (United States)
  • en-AU - English (Australia)
  • en-GB - English (United Kingdom)
  • fr-CA - French (Canada)
  • de-DE - German (Germany)
  • it-IT - Italian (Italy)
  • es-ES - Spanish (Spain)
  • ja-JP - Japanese (Japan)
  • ko-KR - Korean (South Korea)
  • ru-RU - Russian (Russia)
  • hi-IN - Hindi (India)
  • ta-IN - Tamil (India)
  • pt-BR - Portuguese (Brazil)
  • zh-CN - Chinese (Simplified)
  • ar-SA - Arabic (Saudi Arabia)
  • nl-NL - Dutch (Netherlands)
  • pl-PL - Polish (Poland)
  • tr-TR - Turkish (Turkey)
  • sv-SE - Swedish (Sweden)
  • da-DK - Danish (Denmark)

​
Response

​
success
boolean
Indicates whether the request was successful
​
data
object
Contains the transcription job information
​
jobId
string
Unique identifier for the transcription job. Use this to track the job status and retrieve results.

​
Code Examples

curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v2/transcription \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fileUrl": "https://example.com/video.mp4",
    "mediaType": "video",
    "language": "en-US",
    "webhook": "https://your-domain.com/webhooks/transcription"
  }' | python -m json.tool

​
Common Use Cases

​
1. Basic Video Transcription

Generate a transcript for a video file in English: 
import requests

url = "https://api.pictory.ai/pictoryapis/v2/transcription"
headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "fileUrl": "https://example.com/presentation.mp4",
    "mediaType": "video",
    "language": "en-US",
    "webhook": "https://your-domain.com/webhooks/transcription"
}

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

if data.get("success"):
    print(f"Job ID: {data['data']['jobId']}")
    print("You will receive the transcript at your webhook URL when processing is complete")

​
2. Multi-Language Transcription

Transcribe content in different languages: 
import requests

def transcribe_video(video_url, language_code, webhook_url):
    url = "https://api.pictory.ai/pictoryapis/v2/transcription"
    headers = {
        "Authorization": "YOUR_API_KEY",
        "Content-Type": "application/json"
    }

    payload = {
        "fileUrl": video_url,
        "mediaType": "video",
        "language": language_code,
        "webhook": webhook_url
    }

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

# Transcribe videos in different languages
videos = [
    ("https://example.com/english-video.mp4", "en-US"),
    ("https://example.com/spanish-video.mp4", "es-ES"),
    ("https://example.com/japanese-video.mp4", "ja-JP")
]

for video_url, language in videos:
    result = transcribe_video(video_url, language, "https://your-domain.com/webhooks/transcription")
    if result.get("success"):
        print(f"Started transcription for {language}: {result['data']['jobId']}")

​
3. Audio File Transcription

Transcribe audio-only files like podcasts or interviews: 
import requests

url = "https://api.pictory.ai/pictoryapis/v2/transcription"
headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "fileUrl": "https://example.com/podcast-episode.mp3",
    "mediaType": "audio",
    "language": "en-US",
    "webhook": "https://your-domain.com/webhooks/transcription"
}

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

if data.get("success"):
    print(f"Podcast transcription started: {data['data']['jobId']}")

​
4. Transcription with Custom Transcript

Provide your own transcript and request highlights: 
import requests

url = "https://api.pictory.ai/pictoryapis/v2/transcription"
headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "fileUrl": "https://example.com/webinar.mp4",
    "mediaType": "video",
    "language": "en-US",
    "webhook": "https://your-domain.com/webhooks/transcription",
    "transcript": [
        {"text": "Welcome to today's webinar on API integration.", "start": 0, "end": 4},
        {"text": "We'll cover authentication, endpoints, and best practices.", "start": 4, "end": 9},
        {"text": "First, let's discuss API keys and security.", "start": 9, "end": 13}
    ],
    "highlight": [
        {"duration": 60, "type": "summary"}
    ]
}

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

if data.get("success"):
    print(f"Job ID: {data['data']['jobId']}")
    print("Custom transcript submitted with highlight request")

​
5. Batch Processing Multiple Videos

Process multiple videos and track their job IDs: 
import requests
import time

def start_transcription(file_url, language):
    url = "https://api.pictory.ai/pictoryapis/v2/transcription"
    headers = {
        "Authorization": "YOUR_API_KEY",
        "Content-Type": "application/json"
    }

    payload = {
        "fileUrl": file_url,
        "mediaType": "video",
        "language": language,
        "webhook": "https://your-domain.com/webhooks/transcription"
    }

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

# List of videos to transcribe
videos_to_process = [
    {"url": "https://example.com/video1.mp4", "language": "en-US", "title": "Introduction"},
    {"url": "https://example.com/video2.mp4", "language": "en-US", "title": "Tutorial Part 1"},
    {"url": "https://example.com/video3.mp4", "language": "es-ES", "title": "Spanish Version"}
]

job_tracker = []

for video in videos_to_process:
    result = start_transcription(video["url"], video["language"])

    if result.get("success"):
        job_info = {
            "title": video["title"],
            "jobId": result["data"]["jobId"],
            "language": video["language"]
        }
        job_tracker.append(job_info)
        print(f"Started: {video['title']} - Job ID: {result['data']['jobId']}")
        time.sleep(1)  # Rate limiting
    else:
        print(f"Failed to start: {video['title']}")

# Save job IDs for tracking
print(f"\nTotal jobs started: {len(job_tracker)}")
for job in job_tracker:
    print(f"  {job['title']}: {job['jobId']}")

​
Best Practices

  1. Webhook Configuration: Ensure your webhook endpoint is configured to handle POST requests and can process the transcript payload. The webhook should return a 200 status code to acknowledge receipt.
  2. File Accessibility: Make sure your video/audio files are publicly accessible via HTTPS. The transcription service must be able to download the file from the provided URL.
  3. Language Selection: Choose the correct language code for best transcription accuracy. Using the wrong language will result in poor quality transcripts.
  4. File Format: Use common formats like MP4, MP3, or WAV for best results. Ensure audio quality is clear for accurate transcription.
  5. Processing Time: Transcription is an asynchronous process. Processing time varies based on file length and complexity. Use the webhook to receive results rather than polling.
  6. Custom Transcripts: When providing custom transcripts, ensure timing information is accurate with start and end times in seconds. This enables proper synchronization.
  7. Rate Limiting: Implement appropriate delays between batch requests to avoid rate limiting. Process videos sequentially with small delays between API calls.
  8. Error Handling: Implement proper error handling for failed transcriptions. Check the webhook payload for error messages and retry if necessary.