Guides
Start typing to search…

Recipes

Suggest Edits

This document provides practical recipes of common API usage scenarios.

1. Creating a Transcription Job

The transcription job allows the user to upload their video files to be transcribed utilizing Post-Production profile services created in Captivate. In this scenario the user has a completed file that needs transcription. In order to transcribe a file the user would need to perform the following API operations:

  1. Creating a new job - In order to perform any Post-Production service a job needs to be created. This will require the user to make sure to identify a Post-Production profile needed, which in this case will be the standard_transcription profile. They will be transcribing in US English and will be passing in names of the speakers with a list of glossary terms. After successfully completion the user will get a job_id that they will use throughout the process. To learn more please check out the API reference.

  2. Get Upload URL - The user will need to obtain the upload URL. In this case the user will need to provide the asset name file name or the file URL. This will get a pre-signed URL that will allow the user to upload their file. To learn more please check out the API reference.

  3. Upload media to the provided URL - The user will then upload the file to the provided AWS blob storage, which the job will be able to pull the file. To learn more please check out the API reference.

  4. Add the media to the job - The user will need to now add the media to the job. They will use the asset id that was used in step #2. To learn more please check out the API reference.

  5. Start transcription job - This begins the processing of your file. Here the user can actually submit a callback URL for the job to update status. This may be helpful if you want to automate the status update to a particular integration. To learn more please check out the API reference.

  6. Poll status of job until complete - This endpoint enables the user to periodically check the status of their job. To learn more please check out the API reference.

  7. Download the transcription output - Once the job has completed the user can go ahead and download the transcription. They can download the transcript in a specific output. To learn more please check out the API reference.

Here's a walk-through use the API endpoints:

# 1. Create a new job
curl -X POST "https://api.verbit.co/api/job/new?v=4" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "standard_transcription",
    "job_name": "quarterly_meeting.mp4",
    "external_id": "meeting-2023-Q4",
    "language": "en-US",
    "options": {
      "speakers": ["John Smith", "Jane Doe"],
      "glossary": ["Verbit", "AI", "Machine Learning"]
    }
  }'

# Response:
{
  "job_id": 123456,
  "external_id": "meeting-2023-Q4"
}

# 2. Upload media file (local file)
# First get upload URL
curl -X POST "https://api.verbit.co/api/job/add_asset?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "quarterly_meeting.mp4"
  }'

# Response:
{
  "job_id": 123456,
  "asset_id": "abc123_quarterly_meeting.mp4",
  "upload_url": "https://bucket.s3.amazonaws.com/path/to/upload"
}

# Upload the file to the provided URL
curl -X PUT "https://bucket.s3.amazonaws.com/path/to/upload" \
  --upload-file quarterly_meeting.mp4

# Add media to job
curl -X POST "https://api.verbit.co/api/job/add_media?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_ids": ["abc123_quarterly_meeting.mp4"]
  }'

# 3. Start transcription
curl -X POST "https://api.verbit.co/api/job/perform_transcription?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-server.com/webhook",
    "options": {
      "notes": "Please pay special attention to technical terms"
    }
  }'

# 4. Check status (poll until completed)
curl "https://api.verbit.co/api/job/info?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN"

# 5. Download result when status is "Completed"
curl "https://api.verbit.co/api/job/get_caption?v=4&job_id=123456&caption_format=srt" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  --output transcript.srt

2. Creating a Translation Job with Customer Transcript

The user can perform multiple translations of a specific transcript. In this use-case the user wants to take an existing transcript that is written in English and needs to translate to both French and German. The user has a profile that performs this text translation. Here are the following steps that are performed to translate the script:

  1. Create a job with translation settings - A new job will need to be created with the correct profile that will allow translation to a specific language. Make sure to pull a list of profiles to identify which profile will be able to do the translation. Update the specific languages into an array object under the translation_languages parameter. To learn more please check out the API reference.

  2. Add transcript - Add the transcript text body under the transcription_text parameter. To learn more please check out the API reference.

  3. Start translation processing job - After adding your transcript then start the processing. The job can be polled for status periodically. To learn more please check out the API reference.

  4. Download languages - Once the job has completed then begin downloading the transcript, pass in the languages and formats that were requested. In this case the user will be using the language parameter for the specific language and use the caption_format parameter to get the specific format. To learn more please check out the API reference.

Here's a walk-through use the API endpoints:

# 1. Create job with translation settings
curl -X POST "https://api.verbit.co/api/job/new?v=4" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "translation_profile",
    "job_name": "conference_speech.txt",
    "language": "en-US",
    "translation_languages": ["fr-FR", "de-DE"],
    "translation_processing_mode": "standard"
  }'

# 2. Add your transcript
curl -X POST "https://api.verbit.co/api/job/add_transcription?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transcription_text": "This is the transcript content that needs to be translated..."
  }'

# 3. Start processing
curl -X POST "https://api.verbit.co/api/job/perform_transcription?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN"

# 4. Download translations when ready
# French version
curl "https://api.verbit.co/api/job/get_caption?v=4&job_id=123456&language=fr-FR&caption_format=txt" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  --output transcript_fr.txt

# German version
curl "https://api.verbit.co/api/job/get_caption?v=4&job_id=123456&language=de-DE&caption_format=txt" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  --output transcript_de.txt

3. Creating and Using Smart Player

Verbit has an interactive player that utilizes the captions that were transcribed or captioned. This player configuration can be updated via API. Here are the following steps:

  1. Create and get a smart player - Once a job has completed a player can be generated from that same job with the captions or transcriptions. Users can utilize their own CDN to cache the player, but it needs be accessible. The user can also apply other parameter changes as well like the credits and the description to setup the player. After submitting the configuration the user will get a confirmation with the smart player URL. This same player should now be present on the CDN and be accessible. To learn more please check out the API reference.
  2. Make changes to the configuration as needed - Changes can be reapplied to existing players as need. After submission those changes should be refreshed on the CDN. To learn more please check out the API reference.

Here's a walk-through use the API endpoints:

# 1. Create Smart Player for a completed job
curl -X POST "https://api.verbit.co/api/job/smart_player?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.com/videos/presentation.mp4",
    "title": "Annual Conference Keynote",
    "description": "Opening keynote speech from our annual conference",
    "credits": "Presented by Dr. Jane Smith",
    "thumbnail_url": "https://your-cdn.com/thumbnails/keynote.jpg"
  }'

# Response:
{
  "smart_player_url": "https://player.verbit.co/xyz789",
  "config": {
    "video_url": "https://your-cdn.com/videos/presentation.mp4",
    "title": "Annual Conference Keynote",
    "description": "Opening keynote speech from our annual conference",
    "credits": "Presented by Dr. Jane Smith",
    "thumbnail_url": "https://your-cdn.com/thumbnails/keynote.jpg"
  }
}

# 2. Update Smart Player configuration if needed
curl -X PUT "https://api.verbit.co/api/job/smart_player?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.com/videos/presentation_hd.mp4",
    "title": "Annual Conference Keynote 2023",
    "description": "Updated description"
  }'

4. Additional Useful Features

4.1 Getting Job Keywords

This call lets user get the most frequently used keywords. This may be helpful in assisting with SEO or even topic identification. To learn more please check out the API reference.

Extract key terms from completed transcriptions:

curl "https://api.verbit.co/api/job/get_keywords?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN"

# Response:
{
  "keywords": [
    "artificial intelligence",
    "machine learning",
    "neural networks",
    "data science"
  ]
}

4.2 Requesting Review

There will be times that you will need the Verbit Professional Services team to review your transcription or caption.. The request review endpoint lets the user tell the team to what to check specifically as needed. In this case the user is making sure to verify technical terms and speaker names. This call is typically done after a job has completed only. To learn more please check out the API reference.

Request professional review of completed transcription:

curl -X POST "https://api.verbit.co/api/job/request_review?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Please verify technical terms and speaker names"
  }'

4.3 Getting Draft Transcription

There will be times a user may want to see machine-generated text before the job completion. In order to do that the user will need to get the job draft. This is from the draft endpoint, which allows the user to download the draft in same formats as if you were downloading your final transcription or captions. To learn more please check out the API reference.

Access machine-generated draft while waiting for human review:

# Check if draft is ready
curl "https://api.verbit.co/api/job/info?v=4&job_id=123456" \
  -H "Authorization: ApiToken YOUR_API_TOKEN"

# If draft_ready is true, download draft
curl "https://api.verbit.co/api/job/draft?v=4&job_id=123456&caption_format=txt" \
  -H "Authorization: ApiToken YOUR_API_TOKEN" \
  --output draft.txt

Important Notes

  1. Replace YOUR_API_TOKEN with your actual API token
  2. For sandbox testing, use:
    • Base URL: https://sandbox-api.verbit.co/api
    • Your sandbox API token
  3. Webhook notifications are recommended over polling
  4. Always check job status before downloading results
  5. Consider using draft endpoint for faster access to content
  6. Smart Player provides the best accessibility features
  7. Multiple output formats available: srt, web_vtt, txt, docx, pdf

Error Handling

Common error responses:

{
  "ErrorType": "INVALID_OPTION",
  "ErrorComment": "Invalid parameter value"
}

Error types include:

  • BAD_API_TOKEN: Invalid API token
  • ITEM_NOT_FOUND: Requested resource not found
  • INVALID_OPTION: Parameter value incorrect
  • MISSING_PARAMETER: Required parameter omitted
  • INVALID_URL: URL invalid or inaccessible

Updated about 2 months ago

Did this page help you?