POST https://api.vidyard.com/dashboard/v1/videos/:video_id/captions
Add an SRT or VTT file to an existing video resource

The URL specified in srt_url or vtt_url will be fetched and the response body used as the content of the SRT or VTT file respectively. If no such URLs were specified, then an empty VTT file will be created instead. If both are provided, we will default to the srt_url.

Warning: It is the responsibility of the caller to verify if the SRT or VTT was fetched successfully. A successful fetch will leave the caption in a success state, otherwise it will be in an error state with an appropriate message.

Supported Formats

json

Errors

Code Description
401 Unauthorized: auth_token omitted or authentication failed
403 Forbidden: This action cannot be performed
406 Not Acceptable: Accept or Content-Type headers must be application/json, text/csv or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
422 Unprocessable Entity: body has wrong attributes
404 Not Found: The requested resource could not be found
400 Bad Request: body has wrong syntax or unable to handle request

Examples

RESPONSE
Code: 201
Content-Type: application/json
{
  "srt_url": "//cdn.vidyard.com/transcriptions/BeQAX/i-UTPAWS.srt",
  "vtt_url": "//cdn.vidyard.com/transcriptions/BeQAX/Yut9l8z4.vtt",
  "txt_url": "//cdn.vidyard.com/transcriptions/BeQAX/Yut9l8z4.txt",
  "language": "en",
  "id": 1011,
  "status": "in_progress",
  "formatted_text": "The quick brown fox\njumped over the lazy dog.",
  "plain_text": "The quick brown fox jumped over the lazy dog.",
  "created_at": 1442297000,
  "updated_at": 1442297001,
  "formatted_language_name": "English (en)",
  "localized_language_name": "English",
  "is_default": true,
  "notes": "Transcription request notes",
  "srt_download_url": "//vidyard.s3.amazonaws.com/transcriptions/BeQAX/i-UTPAWS.srt",
  "vtt_download_url": "//vidyard.s3.amazonaws.com/transcriptions/BeQAX/Yut9l8z4.vtt",
  "txt_download_url": "//vidyard.s3.amazonaws.com/transcriptions/BeQAX/Yut9l8z4.txt",
}
RESPONSE
Code: 404
Content-Type: application/json
{
  "error": "404: No video exists with that id"
}

Params

Param name Description
auth_token
optional

API token needed to authorize requests
This can appear as an attribute in the body of the request or the query parameters on the URL

Validations:

  • Must be a String
srt_url
optional

SRT URL

Validations:

  • Must be a String
vtt_url
optional

VTT URL

Validations:

  • Must be a String
language
optional

Language of caption

Validations:

  • Must be a String
source_language
optional

Language of caption source

Validations:

  • Must be a String
is_default
optional

Set the default caption for the video

Validations:

  • Must be one of: true, false, 1, 0.
creator_type
optional , nil allowed

Type of creator of captions

Validations:

  • Must be one of: Automatic, Manual.

Returns

Code: 201

Description:

The newly added caption for the video

Param name Description
srt_url
required

The URI of the SRT-formatted version of the caption

Validations:

  • Must be a String
vtt_url
required

The URI of the VTT-formatted version of the caption

Validations:

  • Must be a String
txt_url
required

The URI of the TXT-formatted version of the caption

Validations:

  • Must be a String
language
required

The language locale code indicating the language the caption is in

Validations:

  • Must be a String
id
required

The internal ID of the caption

Validations:

  • Parameter has to be Integer.
status
required , nil allowed

The current state of the caption

Validations:

  • Must be one of: captioning, complete, draft, error, initializing, in_process, in_progress, published, saving, transcribing.
created_at
required

The timestamp when the caption was created

Validations:

  • Must be a DateTime
updated_at
required

The timestamp when the caption was last updated

Validations:

  • Must be a DateTime
formatted_language_name
required

The name of the language in which the caption was formatted

Validations:

  • Must be a String
localized_language_name
required

The name of the language in which the caption was localized

Validations:

  • Must be a String
is_default
required

Indicates whether or not this is the default caption for the associated video

Validations:

  • Must be one of: true, false, 1, 0.
notes
required

Additional notes created for the user about the caption

Validations:

  • Must be a String
srt_download_url
required

A fully qualified URL from which the SRT-formatted version of the caption can be downloaded

Validations:

  • Must be a String
vtt_download_url
required

A fully qualified URL from which the VTT-formatted version of the caption can be downloaded

Validations:

  • Must be a String
txt_download_url
required

A fully qualified URL from which the TXT-formatted version of the cpation can be downloaded

Validations:

  • Must be a String
creator_type
required

Indicates if the caption was created automatically or manually

Validations:

  • Must be one of: Automatic, Manual.

Code: 404

Description:

A message indicating why the caption could not be created

Param name Description
error
required

A contextual error message when a request could not be completed

Validations:

  • Must be a String