Video¶
An individual video represented in the Graph API.
Test this object with the API Explorer
To read a video, perform an HTTP GET request on https://api.dailymotion.com/video/VIDEO_ID. By default, only a small number of fields are returned. To request specific fields, pass the list of wanted fields in the fields query-string parameter (ex: https://api.dailymotion.com/video/VIDEO_ID?fields=field1,field2,...).
Global API Parameters¶
The following parameters are valid globally on the API:
- localization – Change the default localization of the user. This will affect results language and content selection.
Note that changing the localization won’t give access to geoblocked content of the defined localization. The IP of the API consumer is always used for this kind of restriction. You can use a standard locale like fr_FR, en_US or simply en, it.
- family_filter – Enable/disable the family filter. By default, the family filter is on. Changing this parameter will filter-out
explit content from searches and global contexts. You should always check the explicit field when applicable as some contexts may return those contents. You should then flag those content in your UI to warn the user about the nature of the content.
Fields¶
| Name | Description | Permissions | Format |
|---|---|---|---|
| 3d | A boolean indicating that the video is in 3D format (true) or not (false). | No access_token required for reading. | Returns boolean. |
| access_error | An error message explaining why the access to the video can’t be granted. | No access_token required for reading. | Returns dict, min size: 1, max size: 150. |
| ads | Defines is video accepts associated ads | No access_token required for reading. | Returns boolean. |
| allow_comments | If true, allows comments to be posted on this video. | No access_token required for reading. This field is writable. | Returns boolean. |
| allow_embed | Tell if the video can be embeded outside of Dailymotion | No access_token required for reading. | Returns boolean. |
| aspect_ratio | The aspect ratio of the video frame (i.e.: 1.33333 for 4/3, 1.77777 for 16/9...). | No access_token required for reading. | Returns number, min value: 0. |
| available_formats | The video available formats | No access_token required for reading. | Returns array, min size: 1, max size: 150. |
| bookmarks_total | The total number of times a video has been added to users’ favorites. | No access_token required for reading. | Returns number, min value: 0. |
| channel | The short channel name of the video. | This field can be used as filter. No access_token required for reading. This field is writable. | Return a channel. You can request sub-fields by using channel.<sub-field> notation. |
| comments_total | The total number of comments on the video. | No access_token required for reading. | Returns number, min value: 0. |
| country | The country of the video (declarative, may be null). | This field can be used as filter. No access_token required for reading. This field is writable. | Returns string, min size: 1, max size: 150. |
| created_time | The date the video was uploaded to the site. | No access_token required for reading. | Returns date. |
| description | The description of the video. | No access_token required for reading. This field is writable. | Returns string, min size: 1, max size: 2000. |
| duration | The duration of the video in seconds. | No access_token required for reading. | Returns number, min value: 0. |
| embed_html | The HTML embed code. | No access_token required for reading. | Returns string, min size: 1, max size: 150. |
| embed_url | The URL to embed the video. | No access_token required for reading. | Returns url. |
| encoding_progress | When the video status is processing, this parameter indicates a number between 0 and 100 corresponding to the percentage of encoding already completed. For other statuses this parameter is -1. | No access_token required for reading. | Returns number, min value: -1, max value: 100. |
| end_time | the end date of the stream | No access_token required for reading. This field is writable. | Returns date. |
| explicit | True if the video is explicit. | No access_token required for reading. | Returns boolean. |
| filmstrip_small_url | returns sprite url of snapshot of the video if it exists | No access_token required for reading. | Returns url. |
| filters | A list of filters available to reduce the result set. | This field can be used as filter but can’t be read nor written. | Returns array, allowed values: featured, hd, official, creative, creative-official, ugc, buzz, buzz-premium, 3d, live, all-live, live-upcoming, no-live, premium, premium-paidvideos, premium-offers, no-premium, quicklist, history. |
| geoblocking | A list of countries where the video is or isn’t accessible. The list of countries start with the “deny” or “allow” keyword to define if this is a black or a whitelist. Examples: [“fr”, “us”, “it”] or [“allow”, “fr”, “us”, “it”] will both allow the video to be accessed in France, US and Italy and deny all other countries. [“deny”, “us”] will deny the access to the video from the US and allow it everywhere else. An empty list or [“allow”] (the default) will allow it from everywhere. | No access_token required for reading. | Returns array, min size: 1, max size: 150. |
| geoloc | Geolocalization for the video. Result is an array with the longitude and latitude using point notation. Longitude range is from -180.0 (West) to 180.0 (East). Latitude range is from -90.0 (South) to 90.0 (North). | No access_token required for reading. This field is writable. | Returns array, min size: 1, max size: 150. |
| id | The video object ID | No access_token required for reading. | Returns the object id. |
| ids | Limit the result to a specified list of video ids. | This field can be used as filter but can’t be read nor written. | Returns array, min size: 1, max size: 150. |
| isrc | The detected ISRC (International Standard Recording Code) of the soundtrack | No access_token required for reading. | Returns string, min size: 1, max size: 150. |
| language | The language of the video (declarative). | This field can be used as filter. No access_token required for reading. This field is writable. | Returns string, min size: 1, max size: 150. |
| live_hd_publish_url | The URL to publish live HD stream on (current logged user need to own the video in order to retreive this field) | No access_token required for reading. | Returns url. |
| live_hq_publish_url | The URL to publish live HQ stream on (current logged user need to own the video in order to retreive this field) | No access_token required for reading. | Returns url. |
| live_publish_url | The URL to publish live source stream on (current logged user need to own the video in order to retreive this field) | No access_token required for reading. | Returns url. |
| live_sd_publish_url | The URL to publish live SD stream on (current logged user need to own the video in order to retreive this field) | No access_token required for reading. | Returns url. |
| mediablocking | The list of blocking rules per country and device to be applied on the video. Each rule has the following format : country/[country code]/media/[media id] Available country codes are : ar, at, br, ca, ch, cn, de, dk, es, fr, gb, gr, ie, in, it, js, jp, kr, mx, nl, pl, pr, pt, ro, ru, se, tr, us, other. Available medias id are : iptv, mobile, tvhz, web, other. | No access_token required for reading. | Returns array, min size: 1, max size: 150. |
| mode | The stream mode, can be vod, simulcast or live. | No access_token required for reading. This field is writable. | Returns string, allowed values: vod, simulcast, live. |
| modified_time | The date the video was last modified. | No access_token required for reading. | Returns date. |
| onair | True if the video is in mode live and currently airing. | No access_token required for reading. | Returns boolean. |
| owner | The id of the owner of the video (use owner.screenname to show the user name). | This field can be used as filter. No access_token required for reading. | Return a user. You can request sub-fields by using owner.<sub-field> notation. |
| paywall | True is the access to the video is subject to conditions | No access_token required for reading. | Returns boolean. |
| price_details | The price and duration for a tvod or svod video | No access_token required for reading. | Returns number, min value: 0. |
| private | True if the video is private. | No access_token required for reading. This field is writable. | Returns boolean. |
| published | True if the video is published (may still wait for encoding, see status field for more info). | No access_token required for reading. This field is writable. | Returns boolean. |
| rating | The average number of stars the video has (float between 0 and 5). | No access_token required for reading. | Returns number, min value: 0, max value: 5. |
| ratings_total | The number of users who voted for the video. | No access_token required for reading. | Returns number, min value: 0. |
| recurrence | The recurrence of the stream | No access_token required for reading. | Returns string, allowed values: once, daily, weekly. |
| rental_duration | The standard rental duration of the video in hours. Will be null if the video is not behind a paywall | No access_token required for reading. | Returns number, min value: 0. |
| rental_price | The price as float in the current currency. Will be null if the video is not behind a paywall. See currency field of the /locale endpoint to get the current currency. | No access_token required for reading. | Returns string, min size: 1, max size: 150. |
| rental_price_formatted | The price, formatted with currency according to the request localization. Will be null if the video is not behind a paywall | No access_token required for reading. | Returns string, min size: 1, max size: 150. |
| search | Full text search for videos | This field can be used as filter but can’t be read nor written. | Returns string, min size: 1, max size: 150. |
| sort | Change result ordering | This field can be used as filter but can’t be read nor written. | Returns string, allowed values: recent, visited, visited-hour, visited-today, visited-week, visited-month, commented, commented-hour, commented-today, commented-week, commented-month, rated, rated-hour, rated-today, rated-week, rated-month, relevance, random, ranking. |
| soundtrack_info | Get available information about the soundtrack | No access_token required for reading. | Returns dict, min size: 1, max size: 150. |
| start_time | The started time of the stream | No access_token required for reading. This field is writable. | Returns date. |
| status | The state of the video. A video requires the published status to be watchable. | No access_token required for reading. | Returns string, allowed values: waiting, processing, ready, published, rejected, deleted, encoding_error. |
| swf_url | The URL of the legacy SWF embed player (use this only to embed player into a flash movie, otherwise use ``embed_url) | No access_token required for reading. | Returns url. |
| sync_allowed | sync_allowed | No access_token required for reading. | Returns boolean. |
| tags | The list of tags for the video. | This field can be used as filter. No access_token required for reading. This field is writable. | Returns array, min size: 1, max size: 150. |
| taken_time | The date the video was taken (declarative). | No access_token required for reading. This field is writable. | Returns date. |
| thumbnail_large_s_url | The secure URL of the video thumbnail (320px by 240px). | No access_token required for reading. | Returns url. |
| thumbnail_large_url | The URL of the video thumbnail (320px by 240px). | No access_token required for reading. | Returns url. |
| thumbnail_medium_s_url | The secure URL of the video thumbnail (160px by 120px). | No access_token required for reading. | Returns url. |
| thumbnail_medium_url | The URL of the video thumbnail (160px by 120px). | No access_token required for reading. | Returns url. |
| thumbnail_s_url | The secure URL of the raw thumbnail. | No access_token required for reading. | Returns url. |
| thumbnail_small_s_url | The secure URL of the video thumbnail (80px by 60px). | No access_token required for reading. | Returns url. |
| thumbnail_small_url | The URL of the video thumbnail (80px by 60px). | No access_token required for reading. | Returns url. |
| thumbnail_url | The URL of the video raw thumbnail (full size respecting ratio). Some users have the right to change this value by providing an URL to a custom thumbnail. To extract the preview from a live stream, use extract://live | No access_token required for reading. This field is writable. | Returns url. |
| title | The title of the video. | No access_token required for reading. This field is writable. | Returns string, min size: 1, max size: 255. |
| type | The content type of the video (can be official, creative or null). | No access_token required for reading. This field is writable. | Returns string, allowed values: ugc, creative, official. |
| upc | The detected UPC (Universal Product Code) of the soundtrack | No access_token required for reading. | Returns string, min size: 1, max size: 150. |
| url | The URL of the video on Dailymotion site. Writing this parameter defines where to download the video source. You may either use this parameter at video creation time or change this parameter later if you want to change the source video afterward. To change an existing video, the authenticated user may need some additional rights like motionmaker right. When replacing an existing source, the video will put offline for some minute during the re-encoding. You may use the GET /file/upload API ressource to upload a video file and create a URL to provide to this method or use an existing URL pointing to a video file. Writing to this parameter is subject to rate limiting. | No access_token required for reading. This field is writable. | Returns url. |
| views_last_day | The number of views in the last 24 sliding hours. | No access_token required for reading. | Returns number, min value: 0. |
| views_last_hour | The number of views in the last sliding hour. | No access_token required for reading. | Returns number, min value: 0. |
| views_last_month | The number of views in the last 30 sliding days. | No access_token required for reading. | Returns number, min value: 0. |
| views_last_week | The number of views in the last 7 sliding days. | No access_token required for reading. | Returns number, min value: 0. |
| views_total | The number of views on the video since its publication. | No access_token required for reading. | Returns number, min value: 0. |
Connections¶
| Name | Description | Permissions | Returns |
|---|---|---|---|
| comments | Comments for this video | No access_token required for reading. This connection is writable. | A list of Comment. |
| contests | Contest this video is part of | No access_token required for reading. | A list of Contest. |
| groups | Groups this video is part of | No access_token required for reading. This connection is writable. | A list of Group. |
| playlists | Playlists this video is part of | No access_token required for reading. This connection is writable. | A list of Playlist. |
| related | Video relateds to this video | No access_token required for reading. | A list of Video. |
| subtitles | Available subtitles for this video | No access_token required for reading. This connection is writable. | A list of Subtitle. |
The comments connection¶
Read¶
You can read the list of a video‘s comments by issuing an HTTP GET to /video/VIDEO_ID/comments. You can requests the list of comment‘s fields to be returned using the fields parameter.
Test with the API Explorer
Create¶
You can create a comment by issuing an HTTP POST request to /video/VIDEO_ID/comments with the following parameters. You will get in return a dict containing the newly created object id.
| Parameter | Description | Type | Required |
|---|---|---|---|
| message | The comment’s message | string | Yes |
| language | The comment’s language | string | No |
Test with the API Explorer
Delete¶
You can delete a comment by issuing an HTTP DELETE request to /comment/COMMENT_ID.
Test with the API Explorer
The contests connection¶
Read¶
You can read the list of a video‘s contests by issuing an HTTP GET to /video/VIDEO_ID/contests. You can requests the list of contest‘s fields to be returned using the fields parameter.
Test with the API Explorer
The groups connection¶
Read¶
You can read the list of a video‘s groups by issuing an HTTP GET to /video/VIDEO_ID/groups. You can requests the list of group‘s fields to be returned using the fields parameter.
Test with the API Explorer
You can also see if a video has a group by issuing an HTTP GET to /video/VIDEO_ID/groups/GROUP_ID. This will return a list containing only the group if connected or an empty list otherwise.
Create¶
You can add a group by issuing an HTTP POST request to /video/VIDEO_ID/groups/GROUP_ID.
Test with the API Explorer
Delete¶
You can remove a group by issuing an HTTP DELETE request to /video/VIDEO_ID/groups/GROUP_ID.
Test with the API Explorer
The playlists connection¶
Read¶
You can read the list of a video‘s playlists by issuing an HTTP GET to /video/VIDEO_ID/playlists. You can requests the list of playlist‘s fields to be returned using the fields parameter.
Test with the API Explorer
You can also see if a video has a playlist by issuing an HTTP GET to /video/VIDEO_ID/playlists/PLAYLIST_ID. This will return a list containing only the playlist if connected or an empty list otherwise.
Create¶
You can add a playlist by issuing an HTTP POST request to /video/VIDEO_ID/playlists/PLAYLIST_ID.
Test with the API Explorer
Delete¶
You can remove a playlist by issuing an HTTP DELETE request to /video/VIDEO_ID/playlists/PLAYLIST_ID.
Test with the API Explorer
The subtitles connection¶
Read¶
You can read the list of a video‘s subtitles by issuing an HTTP GET to /video/VIDEO_ID/subtitles. You can requests the list of subtitle‘s fields to be returned using the fields parameter.
Test with the API Explorer
Create¶
You can create a subtitle by issuing an HTTP POST request to /video/VIDEO_ID/subtitles with the following parameters. You will get in return a dict containing the newly created object id.
| Parameter | Description | Type | Required |
|---|---|---|---|
| language | The language of the subtitle | string | Yes |
| url | A url to the subtitle data in one of the valid formats, You don’t need to host the file, you can use the GET /file/upload API ressource to create a temporary url to a file you own, just like you do when uploading a video source file | url | Yes |
| format | The data format, either SRT, STL (EBU style) or Time Text (TT) with all the following variants (W3C, SMTPE-TT, EBU-TT) | string | Yes |
Test with the API Explorer
Delete¶
You can delete a subtitle by issuing an HTTP DELETE request to /subtitle/SUBTITLE_ID.
Test with the API Explorer