Captions

Add captions to an existing video resource.

Supported Formats

json
>>>

GET https://api.vidyard.com/dashboard/v1/videos/:video_id/captions
Get a Video's captions

Get a Video’s captions

Supported Formats

json

Errors

Code Description
400 Bad Request: body has wrong syntax or unable to handle request
401 Unauthorized: auth_token omitted or authentication failed
403 Forbidden: This action cannot be performed
404 Not Found: The requested resource could not be found
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

Examples

RESPONSE
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": "complete",
    "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",
  },
  {
    "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": "fr",
    "id": 1011,
    "status": "complete",
    "created_at": 1442297000,
    "updated_at": 1442297001,
    "formatted_language_name": "Francais (fr)",
    "localized_language_name": "Francais",
    "is_default": false,
    "notes": "",
    "srt_download_url": "//vidyard.s3.amazonaws.com/transcriptions/BeQAX/z-X1PAWS.srt",
    "vtt_download_url": "//vidyard.s3.amazonaws.com/transcriptions/BeQAX/Yut7l8z4.vtt",
    "txt_download_url": "//vidyard.s3.amazonaws.com/transcriptions/BeQAX/Yut9l8z4.txt",
  }
]

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
language
optional

Optional two letter language code used to return the first caption with the matching language code.

Validations:

  • Must be a String
order_by
optional

The attribute to order the list by
Value: Must be one of: name, views, created_at, updated_at

Validations:

  • Must be one of: language, created_at, updated_at.
direction
optional

When the direction to order the list
Only applies when order_by used
Default: asc
Value: Must be one of: asc, desc

Validations:

  • Must be one of: asc, desc.
>>>

GET https://api.vidyard.com/dashboard/v1/captions/:id
Get a caption

Get a caption by id

Supported Formats

json

Errors

Code Description
400 Bad Request: body has wrong syntax or unable to handle request
401 Unauthorized: auth_token omitted or authentication failed
403 Forbidden: This action cannot be performed
404 Not Found: The requested resource could not be found
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

Examples

REQUEST
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": "complete",
  "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",
}

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
>>>

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

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 for the SRT or VTT file.

If no ‘srt_url’ or ‘vtt_url’ is specified an empty VTT file will be created.

The initial response will be a 201 Created if successful with the status of the caption set to ‘in_progress’.

It is the caller’s responsibility to check that the SRT or VTT was fetched successfully.

If retrieval of the SRT or VTT file fails the caption will still return a 201 but an error will be set on the caption 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

REQUEST
Content-Type: application/json
caption: {
  srt_url: "s3://...",
  vtt_url: "s3://...",
  language: "en",
  is_default: true
}

RESPONSE
201 (Created)
{
  "id": 1011,
  "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",
  "status": "complete",
  "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": "",
  "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",
  "creator_type": "Automatic",
}

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
caption
optional

Validations:

  • Must be a Hash
caption[srt_url]
optional

SRT URL

Validations:

  • Must be a String
caption[vtt_url]
optional

VTT URL

Validations:

  • Must be a String
caption[language]
optional

Language of caption

Validations:

  • Must be a String
caption[source_language]
optional

Language of caption source

Validations:

  • Must be a String
caption[is_default]
optional

Set the default caption for the video

Validations:

  • Parameter has to be Boolean.
caption[creator_type]
optional

Type of creator of captions

Validations:

  • Must be a String
>>>

PATCH https://api.vidyard.com/dashboard/v1/captions/:id
Update a caption

Update a caption file

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

REQUEST
Content-Type: application/json
caption_file: {
  language: "fr"
}

RESPONSE
200
{
  "language": "fr"
}

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
caption
optional

Validations:

  • Must be a Hash
caption[language]
optional

Language code

Validations:

  • Must be a String
caption[content]
optional

VTT content

Validations:

  • Must be a String
caption[error_message]
optional

Set error message of caption

Validations:

  • Must be a String
caption[is_default]
optional

Set the default caption for the video

Validations:

  • Parameter has to be Boolean.
caption[vtt_url]
optional

VTT URL

Validations:

  • Must be a String
caption[creator_type]
optional

Type of caption

Validations:

  • Must be a String
>>>

GET https://api.vidyard.com/dashboard/v1/captions/:id/content
Get caption VTT content

Get caption VTT content

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

REQUEST
Content-Type: application/json
RESPONSE
200
{
  "content": "WEBVTT\n\n00:00:01.200 --> 00:00:03.360\nIf there is unrest"
}

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
>>>

PATCH https://api.vidyard.com/dashboard/v1/captions/:id/draft
Set caption to draft

Update a caption file

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

REQUEST
Content-Type: application/json
RESPONSE
200
{
  "status": "draft"
}

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
>>>

PATCH https://api.vidyard.com/dashboard/v1/captions/:id/publish
Set caption to published

Update a caption file

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

REQUEST
Content-Type: application/json
RESPONSE
200
{
  "status": "published"
}

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
>>>

DELETE https://api.vidyard.com/dashboard/v1/captions/:id
Delete a caption

Delete a caption

Supported Formats

json

Errors

Code Description
400 Bad Request: body has wrong syntax or unable to handle request
401 Unauthorized: auth_token omitted or authentication failed
403 Forbidden: This action cannot be performed
404 Not Found: The requested resource could not be found
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

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