In order use captions for video or audio you have to create a subtitle first. Subtitles are a kind of container which contains the actual captions.
The subtitle contains information about the language or the publication status.
Reference
Find subtitles
Returns all subtitles for a given mediacontainer
GET/v5/subtitle/:mediaContainerId
Returns all subtitles for a given mediacontainer.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| mediaContainerId | integer | ✓ | Return all subtitles for the given mediaContainerId |
Response
| Field | Type | Description |
|---|---|---|
| creatorId | integer | Id of the user who created this subtitle setting. |
| customerId | integer | Id of the customer this subtitle setting belongs to. |
| id | integer | |
| language | iso-639 | |
| mediaContainerId | integer | Return all subtitles for the given mediaContainerId |
| name | string | |
| published | boolean | If true this subtitle is available for external pages/weblinks |
| settings | object | Setting/Definition for this subtitle. |
| └ PrimaryColour | integer | Primary color for the subtitle |
| └ Fontsize | integer | The point size of the font for the subtitle |
| └ BorderStyle | integer | BorderStyle of the subtitle according to SSA definition. 1 – Outline with shadow, 3 – Rendered with an opaque box allowed values: 13 |
| └ Outline | integer | The width of the text outline, in pixels. |
| subtitleSettingId | integer | |
| updatedAt | dateTime | Date and time of the latest update |
Examples
Simple example
Request
/v5/subtitle/123
Response
{
"id": 100,
"name": "My first subtitle",
"language": "en",
"published": false,
"subtitleSettingId": null,
"settings": null,
"mediaContainerId": 123,
"customerId": 147,
"creatorId": 10,
"updatedAt": "2020-07-20 13:20:50"
}Create a new subtitle
Creates the subtitle file which is the basis for 1-n captions.
POST/v5/subtitle
Creates the subtitle file which is the basis for 1-n captions.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| language | iso-639 | ✓ | Language for this subtitle. Please use ISO-639-2, even though ISO-639-1 is currently working as well. |
| mediaContainerId | integer | ✓ | mediaContainerId for this subtitle |
| name | string | ✓ | Name of this subtitle setting. |
| published | boolean | ✗ | Set to true if you want the subtitle to be published |
| subtitleSettingId | integer | ✗ | Id of subtitle settings id to use for this subtitle. |
Response
| Field | Type | Description |
|---|---|---|
| creatorId | integer | Id of the user who created this subtitle setting. |
| customerId | integer | Id of the customer this subtitle setting belongs to. |
| id | integer | |
| language | iso-639 | Language for this subtitle. Please use ISO-639-2, even though ISO-639-1 is currently working as well. |
| mediaContainerId | integer | mediaContainerId for this subtitle |
| name | string | Name of this subtitle setting. |
| published | boolean | If true this subtitle is available for external pages/weblinks |
| settings | object | Setting/Definition for this subtitle. |
| └ PrimaryColour | integer | Primary color for the subtitle |
| └ Fontsize | integer | The point size of the font for the subtitle |
| └ BorderStyle | integer | BorderStyle of the subtitle according to SSA definition. 1 – Outline with shadow, 3 – Rendered with an opaque box allowed values: 13 |
| └ Outline | integer | The width of the text outline, in pixels. |
| subtitleSettingId | integer | Id of subtitle settings id to use for this subtitle. |
| updatedAt | dateTime | Date and time of the latest update |
Examples
Create a new subtitle
Request
/v5/subtitle
Response
{
"id": 100,
"name": "My first subtitle",
"language": "en",
"published": false,
"subtitleSettingId": null,
"settings": null,
"mediaContainerId": 123,
"customerId": 147,
"creatorId": 10,
"updatedAt": "2020-07-20 13:20:50"
}Update an existing subtitle
Update subtitle file with a different name or language or publish state.
PUT/v5/subtitle/:mediaContainerId/:id
Update subtitle file with a different name or language or publish state.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | ✓ | Id of the subtitle to update |
| language | iso-639 | ✗ | Language for the subtitle to update. Please use ISO-639-2, even though ISO-639-1 is currently working as well. |
| mediaContainerId | integer | ✓ | mediaContainerId for this subtitle |
| name | string | ✗ | Name of this subtitle setting. |
| published | boolean | ✗ | Set to true if you want the subtitle to be published |
| subtitleSettingId | integer | ✗ | Id of the setting to update. |
Response
| Field | Type | Description |
|---|---|---|
| creatorId | integer | Id of the user who created this subtitle setting. |
| customerId | integer | Id of the customer this subtitle setting belongs to. |
| id | integer | Id of the subtitle to update |
| language | iso-639 | Language for the subtitle to update. Please use ISO-639-2, even though ISO-639-1 is currently working as well. |
| mediaContainerId | integer | mediaContainerId for this subtitle |
| name | string | Name of this subtitle setting. |
| published | boolean | If true this subtitle is available for external pages/weblinks |
| settings | object | Setting/Definition for this subtitle. |
| └ PrimaryColour | integer | Primary color for the subtitle |
| └ Fontsize | integer | The point size of the font for the subtitle |
| └ BorderStyle | integer | BorderStyle of the subtitle according to SSA definition. 1 – Outline with shadow, 3 – Rendered with an opaque box allowed values: 13 |
| └ Outline | integer | The width of the text outline, in pixels. |
| subtitleSettingId | integer | Id of the setting to update. |
| updatedAt | dateTime | Date and time of the latest update |
Examples
Update existing subtitle
Request
/v5/subtitle/123/100
Response
{
"id": 100,
"name": "My first subtitle",
"language": "en",
"published": true,
"subtitleSettingId": null,
"settings": null,
"mediaContainerId": 123,
"customerId": 147,
"creatorId": 10,
"updatedAt": "2020-07-20 13:20:55"
}Delete a subtitle
Destroys a subtitle file including all captions! This will permamently delete the subtitles and all captions!
DELETE/v5/subtitle/:mediaContainerId/:id
Destroys a subtitle file including all captions! This will permamently delete the subtitles and all captions.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | ✓ | Id of the subtitle to destroy |
| mediaContainerId | integer | ✓ | mediaContainerId for this subtitle |
Response
| Field | Type | Description |
|---|---|---|
| id | integer | Id of the subtitle to destroy |
Examples
Destroy existing subtitle
Request
/v5/subtitle/123/100
Response
{
"id": 100
}Duplicate subtitle
You can duplicate a subtitle including all captions with a single call. You can use it to prepare a translation document for a new language.
POST/v5/subtitle/duplicate
Duplicates a subtitle including all captions. Publish state is automatically set to false!
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | ✓ | Id of the subtitle to duplicate |
| language | iso-639 | ✗ | Language for the subtitle duplicate. Please use ISO-639-2, even though ISO-639-1 is currently working as well. |
| mediaContainerId | integer | ✓ | mediaContainerId for the subtitle to duplicate |
| moveTo | integer | ✗ | |
| name | string | ✗ | |
| subtitleId | integer | ✓ | Please use id instead of subtitleId Use id instead of subtitleId |
Response
| Field | Type | Description |
|---|---|---|
| creatorId | integer | Id of the user who created this subtitle setting. |
| customerId | integer | Id of the customer this subtitle setting belongs to. |
| id | integer | Id of the subtitle to duplicate |
| language | iso-639 | Language for the subtitle duplicate. Please use ISO-639-2, even though ISO-639-1 is currently working as well. |
| mediaContainerId | integer | mediaContainerId for the subtitle to duplicate |
| name | string | |
| published | boolean | If true this subtitle is available for external pages/weblinks |
| settings | object | Setting/Definition for this subtitle. |
| └ PrimaryColour | integer | Primary color for the subtitle |
| └ Fontsize | integer | The point size of the font for the subtitle |
| └ BorderStyle | integer | BorderStyle of the subtitle according to SSA definition. 1 – Outline with shadow, 3 – Rendered with an opaque box allowed values: 13 |
| └ Outline | integer | The width of the text outline, in pixels. |
| subtitleSettingId | integer | |
| updatedAt | dateTime | Date and time of the latest update |
Examples
Duplicate existing subtitle
Request
/v5/subtitle/duplicate
Response
{
"id": 101,
"name": "My first subtitle",
"language": "en",
"published": false,
"subtitleSettingId": null,
"settings": null,
"mediaContainerId": 123,
"customerId": 147,
"creatorId": 10,
"updatedAt": "2020-07-20 13:20:50"
}Import Subtitle
In order to import a subtitle follow the tutorial “Import subtitles”.
Export Subtitle
Export all captions for a given subtitle. Please note that this is still beta.
GET/v5/subtitle/:mediaContainerId/export/:id
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | ✗ | |
| mediaContainerId | integer | ✗ |
Response
| Field | Type | Description |
|---|---|---|