video_id is the numeric video id; the video’s player uuid is also accepted.
The track is processed in the background, so the request answers 202 Accepted with the new track’s id and status processing. Poll GET /v1/audio_tracks/:id until status is complete or error. A completed track is unpublished (published is false) until it is published with PATCH /v1/audio_tracks/:id.
Expected latency: a video’s first added audio track also re-encodes the video itself, so it takes
several minutes to complete. Tracks added after that only encode the new audio.
File URLs: an https original_file_url on an arbitrary host is not fetched: only an
approved partner host is accepted. Other callers upload the file to the Vidyard upload bucket and send its S3 URL. In the example below, APPROVED-PARTNER-HOST is a placeholder: the request only succeeds with a URL on a host Vidyard has approved for your integration.
| Code | Description |
|---|---|
| 401 | Unauthorized: auth_token omitted or authentication failed |
| 403 | Forbidden: This action cannot be performed |
| 400 | The language is not an offered media language; the file URL is neither in the upload bucket nor on an approved partner host; or, for a partner URL, the file is not WAV, the URL is longer than 2048 characters, or duration is missing or not a positive integer |
| 404 | No video exists with that id |
| 422 | language or original_file_url is missing; multi-track audio is not enabled for the account; the video is not a Vidyard-hosted video, is audio-only, is still being duplicated or processed, has embedded alternate audio, or is archived; or the declared duration is more than 2000 ms off the video's length (error_code duration_mismatch) |
| 502 | Audio processing could not be started; retry the request |
REQUEST
POST /v1/videos/456/audio_tracks
Content-Type: application/json
{
"language": "fr",
"original_file_url": "https://APPROVED-PARTNER-HOST/dubs/456-fr.wav?signature=abc123",
"duration": 93450
}
RESPONSE
Code: 202
Content-Type: application/json
{
"id": 123,
"video_id": 456,
"language": "fr",
"status": "processing",
"error_code": null,
"error_message": null,
"published": false
}
RESPONSE
Code: 422
Content-Type: application/json
{
"error": "The audio's length doesn't match the video's length (it must be within 2 seconds).",
"error_code": "duration_mismatch"
}
| Param name | Description |
|---|---|
|
auth_token optional |
API token needed to authorize requests Validations:
|
|
video_id required |
The numeric video id, or the video’s player uuid Validations:
|
|
language required |
Media language code for the track, e.g. fr, es-419 or pt-BR. Must be one of the media languages Vidyard offers for captions and audio (the list in media_languages.yml). Validations:
|
|
original_file_url required |
The audio file’s URL, either an S3 URL in the Vidyard upload bucket or an https URL on an approved partner host pointing at a .wav file (at most 2048 characters). A partner URL may carry a signed query string; it is fetched as-is when processing starts, so it must stay valid for a few hours. Validations:
|
|
duration optional |
The length of the audio file, in integer milliseconds. Required with a partner https URL, ignored otherwise. Must be within 2000 ms of the video’s length, or the request is rejected with 422 and error_code duration_mismatch. |
The new audio track, still processing
| Param name | Description |
|---|---|
|
id required |
The audio track id Validations:
|
|
video_id required |
The id of the video the track belongs to Validations:
|
|
language required |
BCP47 media language code for the track Validations:
|
|
status required |
processing until the track is playable, complete once it is, or error if it failed Validations:
|
|
error_code required , nil allowed |
Machine-readable failure reason; null unless status is error Validations:
|
|
error_message required , nil allowed |
Readable failure reason; null unless status is error Validations:
|
|
published required |
Whether viewers can select the track Validations:
|