对于 2020 年 7 月 28 日之后创建的未经验证的 API 项目,通过
videos.insert
端点上传的所有视频都将无法观看私享。如需解除此限制,每个 API 项目都必须接受审核,以验证是否符合服务条款。如需了解详情,请参阅 API 修订历史记录。
video
资源表示 YouTube 视频。
方法
对于 videos
资源,该 API 支持以下方法:
资源表示法
以下 JSON 结构显示了 videos
资源的格式:
{ "kind": "youtube#video", "etag": etag, "id": string, "snippet": { "publishedAt": datetime, "channelId": string, "title": string, "description": string, "thumbnails": { (key): { "url": string, "width": unsigned integer, "height": unsigned integer } }, "channelTitle": string, "tags": [ string ], "categoryId": string, "liveBroadcastContent": string, "defaultLanguage": string, "localized": { "title": string, "description": string }, "defaultAudioLanguage": string }, "contentDetails": { "duration": string, "dimension": string, "definition": string, "caption": string, "licensedContent": boolean, "regionRestriction": { "allowed": [ string ], "blocked": [ string ] }, "contentRating": { "acbRating": string, "agcomRating": string, "anatelRating": string, "bbfcRating": string, "bfvcRating": string, "bmukkRating": string, "catvRating": string, "catvfrRating": string, "cbfcRating": string, "cccRating": string, "cceRating": string, "chfilmRating": string, "chvrsRating": string, "cicfRating": string, "cnaRating": string, "cncRating": string, "csaRating": string, "cscfRating": string, "czfilmRating": string, "djctqRating": string, "djctqRatingReasons": [, string ], "ecbmctRating": string, "eefilmRating": string, "egfilmRating": string, "eirinRating": string, "fcbmRating": string, "fcoRating": string, "fmocRating": string, "fpbRating": string, "fpbRatingReasons": [, string ], "fskRating": string, "grfilmRating": string, "icaaRating": string, "ifcoRating": string, "ilfilmRating": string, "incaaRating": string, "kfcbRating": string, "kijkwijzerRating": string, "kmrbRating": string, "lsfRating": string, "mccaaRating": string, "mccypRating": string, "mcstRating": string, "mdaRating": string, "medietilsynetRating": string, "mekuRating": string, "mibacRating": string, "mocRating": string, "moctwRating": string, "mpaaRating": string, "mpaatRating": string, "mtrcbRating": string, "nbcRating": string, "nbcplRating": string, "nfrcRating": string, "nfvcbRating": string, "nkclvRating": string, "oflcRating": string, "pefilmRating": string, "rcnofRating": string, "resorteviolenciaRating": string, "rtcRating": string, "rteRating": string, "russiaRating": string, "skfilmRating": string, "smaisRating": string, "smsaRating": string, "tvpgRating": string, "ytRating": string }, "projection": string, "hasCustomThumbnail": boolean }, "status": { "uploadStatus": string, "failureReason": string, "rejectionReason": string, "privacyStatus": string, "publishAt": datetime, "license": string, "embeddable": boolean, "publicStatsViewable": boolean, "madeForKids": boolean, "selfDeclaredMadeForKids": boolean }, "statistics": { "viewCount": string, "likeCount": string, "dislikeCount": string, "favoriteCount": string, "commentCount": string }, "player": { "embedHtml": string, "embedHeight": long, "embedWidth": long }, "topicDetails": { "topicIds": [ string ], "relevantTopicIds": [ string ], "topicCategories": [ string ] }, "recordingDetails": { "recordingDate": datetime }, "fileDetails": { "fileName": string, "fileSize": unsigned long, "fileType": string, "container": string, "videoStreams": [ { "widthPixels": unsigned integer, "heightPixels": unsigned integer, "frameRateFps": double, "aspectRatio": double, "codec": string, "bitrateBps": unsigned long, "rotation": string, "vendor": string } ], "audioStreams": [ { "channelCount": unsigned integer, "codec": string, "bitrateBps": unsigned long, "vendor": string } ], "durationMs": unsigned long, "bitrateBps": unsigned long, "creationTime": string }, "processingDetails": { "processingStatus": string, "processingProgress": { "partsTotal": unsigned long, "partsProcessed": unsigned long, "timeLeftMs": unsigned long }, "processingFailureReason": string, "fileDetailsAvailability": string, "processingIssuesAvailability": string, "tagSuggestionsAvailability": string, "editorSuggestionsAvailability": string, "thumbnailsAvailability": string }, "suggestions": { "processingErrors": [ string ], "processingWarnings": [ string ], "processingHints": [ string ], "tagSuggestions": [ { "tag": string, "categoryRestricts": [ string ] } ], "editorSuggestions": [ string ] }, "liveStreamingDetails": { "actualStartTime": datetime, "actualEndTime": datetime, "scheduledStartTime": datetime, "scheduledEndTime": datetime, "concurrentViewers": unsigned long, "activeLiveChatId": string }, "localizations": { (key): { "title": string, "description": string } } }
属性
下表定义了此资源中显示的属性:
属性 | |
---|---|
kind |
string 标识 API 资源类型。其值为 youtube#video 。 |
etag |
etag 此资源的 Etag。 |
id |
string YouTube 用来对视频进行唯一标识的 ID。 |
snippet |
object snippet 对象包含视频的基本详情,例如标题、说明和类别。 |
snippet.publishedAt |
datetime 视频发布的日期和时间。请注意,此时间可能与视频上传的时间不同。例如,如果某个视频作为私享视频上传,后来又变为公开状态,则此属性会指明该视频公开的时间。 存在几种特殊情况:
|
snippet.channelId |
string YouTube 用来唯一标识上传视频的目标频道的 ID。 |
snippet.title |
string 视频的标题。属性值的长度上限为 100 个字符,可以包含除 < 和 > 以外的所有有效的 UTF-8 字符。如果您调用 videos.update 方法并更新 video 资源的 snippet 部分,则必须为此属性设置一个值。 |
snippet.description |
string 视频的说明。属性值的长度上限为 5000 字节,并且可以包含除 < 和 > 以外的所有有效的 UTF-8 字符。 |
snippet.thumbnails |
object 与视频相关的缩略图图。对于映射中的每个对象,键都是缩略图的名称,其值是包含有关缩略图的其他信息的对象。 |
snippet.thumbnails.(key) |
object 有效的键值对包括:
|
snippet.thumbnails.(key).url |
string 图片的网址。 |
snippet.thumbnails.(key).width |
unsigned integer 图片的宽度。 |
snippet.thumbnails.(key).height |
unsigned integer 图片的高度。 |
snippet.channelTitle |
string 视频所属频道的频道标题。 |
snippet.tags[] |
list 与视频相关联的一系列关键字。标记可以包含空格。属性值的长度上限为 500 个字符。在计算字符数限制时,请注意以下规则:
|
snippet.categoryId |
string 与视频相关联的 YouTube 视频类别。如果您调用 videos.update 方法并更新 video 资源的 snippet 部分,则必须为此属性设置值。 |
snippet.liveBroadcastContent |
string 指明视频是否为即将开始/正在进行的直播。如果视频不是即将进行/正在进行的直播,则值为“none”。 此属性的有效值包括:
|
snippet.defaultLanguage |
string video 资源的 snippet.title 和 snippet.description 属性中的文本语言。 |
snippet.localized |
object snippet.localized 对象包含视频的本地化标题和说明,或者包含视频元数据默认语言的标题。
localizations 对象添加、更新或删除本地化影视内容。 |
snippet.localized.title |
string 本地化的视频标题。 |
snippet.localized.description |
string 本地化的视频说明。 |
snippet.defaultAudioLanguage |
string default_audio_language 属性用于指定视频的默认音轨所用的语言。 |
contentDetails |
object contentDetails 对象包含视频内容的相关信息,包括视频时长以及关于视频是否有字幕的指示。 |
contentDetails.duration |
string 视频的长度。属性值是 ISO 8601 时长。例如,对于时长至少为一分钟且时长不到 1 小时的视频,时长的格式为 PT#M#S ,其中字母 PT 表示相应的值表示时间段,字母 M 和 S 分别表示时长(以分钟和秒为单位)。M 和 S 字母前面的 # 字符都是整数,用于指定视频的分钟数(或秒数)。例如,值 PT15M33S 表示视频时长为 15 分 33 秒。如果视频时长至少为 1 小时,则时长格式为 PT#H#M#S ,其中字母 H 前面的 # 指定了视频的时长(以小时为单位),其他所有详细信息与上文所述相同。如果视频时长至少为一天,则字母 P 和 T 会分隔,且值的格式为 P#DT#H#M#S 。如需了解完整详情,请参阅 ISO 8601 规范。 |
contentDetails.dimension |
string 指明视频支持 3D 还是 2D。 |
contentDetails.definition |
string 指明视频是能够以高清 ( HD ) 模式播放,还是仅能以标清模式播放。此属性的有效值包括:
|
contentDetails.caption |
string 指明视频是否提供字幕。 此属性的有效值包括:
|
contentDetails.licensedContent |
boolean 指明视频是否代表许可内容,即内容已上传到与 YouTube 内容合作伙伴关联的频道,并由该合作伙伴提出版权主张。 |
contentDetails.regionRestriction |
object regionRestriction 对象包含有关视频可(或无法)观看的国家/地区的信息。该对象将包含 contentDetails.regionRestriction.allowed 属性或 contentDetails.regionRestriction.blocked 属性。 |
contentDetails.regionRestriction.allowed[] |
list 地区代码列表,用于标识哪些国家/地区的用户可以观看视频。如果此属性存在,但其值中未列出某个国家/地区,则表示该视频无法在该国家/地区显示。如果此属性存在且包含空列表,则视频在所有国家/地区禁播。 |
contentDetails.regionRestriction.blocked[] |
list 地区代码列表,用于标识视频遭到禁播的国家/地区。如果该属性存在,但其值中未列出某个国家/地区,则表示该视频在该国家/地区是可观看的。如果此属性存在且包含空列表,则视频在所有国家/地区均可观看。 |
contentDetails.contentRating |
object 指定视频根据各种分级制度获得的分级。 |
contentDetails.contentRating.acbRating |
string 视频的澳大利亚分类委员会 (ACB) 或澳大利亚通信和媒体管理局 (ACMA) 的分级。ACMA 分级用于对儿童电视节目进行分类。 此属性的有效值包括:
|
contentDetails.contentRating.agcomRating |
string 该视频由意大利 Autorità per le Garanzie nelle Comunicazioni (AGCOM) 给出的视频分级。 此属性的有效值包括:
|
contentDetails.contentRating.anatelRating |
string 该视频在智利电视机的 Anatel (Asociación Nacional de Televisión) 的分级。 此属性的有效值包括:
|
contentDetails.contentRating.bbfcRating |
string 该视频的英国电影分类委员会 (BBFC) 分级。 此属性的有效值包括:
|
contentDetails.contentRating.bfvcRating |
string 该视频由泰国电影和视频审核委员会 (Board of Film and Video Censors) 评定。 此属性的有效值包括:
|
contentDetails.contentRating.bmukkRating |
string 该视频由奥地利媒体分类委员会 (Bundesministerium für Unterricht, Kunst und Kultur) 给出的分级。 此属性的有效值包括:
|
contentDetails.contentRating.catvRating |
string 加拿大电视分级系统 - 加拿大电视分级系统 加拿大无线电电视与电信委员会 (CRTC) 针对加拿大英语广播的视频分级。如需了解详情,请访问加拿大广播标准委员会网站。 此属性的有效值包括:
|
contentDetails.contentRating.catvfrRating |
string 该视频由加拿大无线电电视与电信委员会 (CRTC) 对加拿大法语广播所做的分级。如需了解详情,请访问加拿大广播标准委员会网站。 此属性的有效值包括:
|
contentDetails.contentRating.cbfcRating |
string 该视频的中央电影认证委员会 (CBFC - India) 的分级。 此属性的有效值包括:
|
contentDetails.contentRating.cccRating |
string 该视频的 Consejo de Calificación Cinematográfica(智利)评分。 此属性的有效值包括:
|
contentDetails.contentRating.cceRating |
string 该视频由葡萄牙 Comissão de Classificação de Espect ́culos 分级。 此属性的有效值包括:
|
contentDetails.contentRating.chfilmRating |
string 视频在瑞士的分级。 此属性的有效值包括:
|
contentDetails.contentRating.chvrsRating |
string 该视频的加拿大家庭视频分级系统 (CHVRS) 分级。 此属性的有效值包括:
|
contentDetails.contentRating.cicfRating |
string 该视频由 Commission de Contrôle des Films(比利时)提供的分级。 此属性的有效值包括:
|
contentDetails.contentRating.cnaRating |
string 该视频由罗马尼亚 CONSILIUL NATIONAL AUDIOVIZUALULUI (CNA) 发布。 此属性的有效值包括:
|
contentDetails.contentRating.cncRating |
string 法国的分级制度 - Commission de category movietographique 此属性的有效值包括:
|
contentDetails.contentRating.csaRating |
string 该视频由法国 Conseil supérieur de l?audiovisuel 给出,用于对广播内容进行评分。 此属性的有效值包括:
|
contentDetails.contentRating.cscfRating |
string 该视频由卢森堡的 Commission de surveillance de la 敏感类别 desmovies (CSCF) 提供的分级。 此属性的有效值包括:
|
contentDetails.contentRating.czfilmRating |
string 视频在捷克的分级。 此属性的有效值包括:
|
contentDetails.contentRating.djctqRating |
string 该视频的 Leaveamento de Justiça, Classificação, Qualificação e Títulos (DJCQT - 巴西) 评分。 此属性的有效值包括:
|
contentDetails.contentRating.djctqRatingReasons[] |
list 说明视频获得 DJCQT(巴西)分级的原因。 |
contentDetails.contentRating.ecbmctRating |
string 土耳其的分级制度 - 文化旅游部评估与分类委员会 此属性的有效值包括:
|
contentDetails.contentRating.eefilmRating |
string 视频在爱沙尼亚的评分。 此属性的有效值包括:
|
contentDetails.contentRating.egfilmRating |
string 该视频在埃及的分级。 此属性的有效值包括:
|
contentDetails.contentRating.eirinRating |
string 视频的 Eirin(映伦)分级。Eirin 是日本的分级制度。 此属性的有效值包括:
|
contentDetails.contentRating.fcbmRating |
string 该视频由马来西亚电影审查委员会发布的分级。 此属性的有效值包括:
|
contentDetails.contentRating.fcoRating |
string 该视频由香港电影、报纸与文献管理局提供的分级。 此属性的有效值包括:
|
contentDetails.contentRating.fmocRating |
string 此属性自 2015 年 11 月 2 日起已弃用。请改用 contentDetails.contentRating.cncRating 属性。该视频的 Centrenation du cinéma et de l'image animé (French Ministry of Culture) 评分。 此属性的有效值包括:
|
contentDetails.contentRating.fpbRating |
string 该视频由南非电影和出版委员会提供的分级。 此属性的有效值包括:
|
contentDetails.contentRating.fpbRatingReasons[] |
list 说明视频获得 FPB(南非)分级的原因。 |
contentDetails.contentRating.fskRating |
string 该视频的 Freiwillige Selbstkontrolle der Filmwirtschaft(FSK - 德国)评分。 此属性的有效值包括:
|
contentDetails.contentRating.grfilmRating |
string 该视频在希腊的评分。 此属性的有效值包括:
|
contentDetails.contentRating.icaaRating |
string 该视频的 Instituto de la Cinematografía y de las Artes Audiovisuales (ICAA - 西班牙) 分级。 此属性的有效值包括:
|
contentDetails.contentRating.ifcoRating |
string 视频的爱尔兰电影分级办公室 (IFCO - Ireland) 的分级。如需了解详情,请参阅 IFCO 网站。 此属性的有效值包括:
|
contentDetails.contentRating.ilfilmRating |
string 视频在以色列的分级。 此属性的有效值包括:
|
contentDetails.contentRating.incaaRating |
string 该视频的 IncAA(国家电影音像学院 - 阿根廷)分级。 此属性的有效值包括:
|
contentDetails.contentRating.kfcbRating |
string 肯尼亚电影分类委员会的视频分级。 此属性的有效值包括:
|
contentDetails.contentRating.kijkwijzerRating |
string voor de Classificatie van Audiovisuele Media(荷兰)。 此属性的有效值包括:
|
contentDetails.contentRating.kmrbRating |
string 该视频的韩国媒体分级委员会 (Experienceวิลลิงหลั) 的分级。韩国的视频采用 KMRB 费率。 此属性的有效值包括:
|
contentDetails.contentRating.lsfRating |
string 该视频在印度尼西亚 Lembaga 传感器电影中的评分。 此属性的有效值包括:
|
contentDetails.contentRating.mccaaRating |
string 马耳他电影年龄分类委员会的视频分级。 此属性的有效值包括:
|
contentDetails.contentRating.mccypRating |
string 该视频由丹麦电影学院(Det Danske Filminstitut)的儿童与年轻人媒体委员会 (Media Council for Children and Young People) 评定的分级。 此属性的有效值包括:
|
contentDetails.contentRating.mcstRating |
string 该视频的越南分级制度 - MCST 此属性的有效值包括:
|
contentDetails.contentRating.mdaRating |
string 该视频由新加坡媒体发展管理局 (MDA) 以及新加坡电影审查委员会 (BFC) 提供的分级。 此属性的有效值包括:
|
contentDetails.contentRating.medietilsynetRating |
string 该视频来自挪威媒体管理局 Medietilsynet 的分级。 此属性的有效值包括:
|
contentDetails.contentRating.mekuRating |
string 该视频来自芬兰 Kansallinen Audiovisualinen Instituutti(国家视听研究所)的分级。 此属性的有效值包括:
|
contentDetails.contentRating.mibacRating |
string 该视频由 Ministero dei Beni e delle Attività Culturali e del Turismo(意大利)提供的评分。 此属性的有效值包括:
|
contentDetails.contentRating.mocRating |
string 该视频的文化部(哥伦比亚)分级。 此属性的有效值包括:
|
contentDetails.contentRating.moctwRating |
string 该视频由台湾文化部授予的分级。 此属性的有效值包括:
|
contentDetails.contentRating.mpaaRating |
string 视频的美国电影协会 (MPAA) 分级。 此属性的有效值包括:
|
contentDetails.contentRating.mpaatRating |
string 美国电影协会对电影预告片和预览的分级。 此属性的有效值包括:
|
contentDetails.contentRating.mtrcbRating |
string 该视频由电影和电视评论与分类委员会(菲律宾)提供的分级。 此属性的有效值包括:
|
contentDetails.contentRating.nbcRating |
string 该视频由马尔代夫国家分类局提供的分级。 此属性的有效值包括:
|
contentDetails.contentRating.nfrcRating |
string 保加利亚国家电影中心的视频分级。 此属性的有效值包括:
|
contentDetails.contentRating.nfvcbRating |
string 该视频由尼日利亚国家电影和视频审查委员会 (National Film and Video Censors Board) 评定。 此属性的有效值包括:
|
contentDetails.contentRating.nkclvRating |
string 该视频由拉脱维亚国家电影中心 (Nacionêlais Kino centrs)(拉脱维亚国家电影中心)给出的分级。 此属性的有效值包括:
|
contentDetails.contentRating.oflcRating |
string 该视频的影片与文学分类办公室 (OFLC - New Zealand) 的分级。 此属性的有效值包括:
|
contentDetails.contentRating.pefilmRating |
string 视频在秘鲁的评分。 此属性的有效值包括:
|
contentDetails.contentRating.resorteviolenciaRating |
string 视频在委内瑞拉的评分。 此属性的有效值包括:
|
contentDetails.contentRating.rtcRating |
string 该视频的广播、电视和电影总局(墨西哥)的分级。 此属性的有效值包括:
|
contentDetails.contentRating.rteRating |
string 该视频由爱尔兰 Raidió Teilifís Éireann 提供的分级。 此属性的有效值包括:
|
contentDetails.contentRating.russiaRating |
string 该视频的俄罗斯联邦国家电影注册机构 (MKRF - Russia) 的分级。 此属性的有效值包括:
|
contentDetails.contentRating.skfilmRating |
string 视频在斯洛伐克的评分。 此属性的有效值包括:
|
contentDetails.contentRating.smaisRating |
string 视频在冰岛的评分。 此属性的有效值包括:
|
contentDetails.contentRating.smsaRating |
string 该视频由瑞典国家媒体委员会 Statens medieråd 提供的分级。 此属性的有效值包括:
|
contentDetails.contentRating.tvpgRating |
string 该视频的 TV 家长控制 (TVPG) 分级。 此属性的有效值包括:
|
contentDetails.contentRating.ytRating |
string YouTube 用于识别有年龄限制的内容的分级。 此属性的有效值包括:
|
contentDetails.projection |
string 指定视频的投影格式。 此属性的有效值包括:
|
contentDetails.hasCustomThumbnail |
boolean 指明视频上传者是否已为视频提供了自定义缩略图。只有视频上传者可以看到此属性。 |
status |
object status 对象包含视频的上传、处理和隐私状态的相关信息。 |
status.uploadStatus |
string 已上传的视频的状态。 此属性的有效值包括:
|
status.failureReason |
string 此值用于说明视频上传失败的原因。只有当 uploadStatus 属性表明上传失败时,此属性才会显示。此属性的有效值包括:
|
status.rejectionReason |
string 此值用于说明 YouTube 拒绝上传的视频的原因。仅当 uploadStatus 属性指明上传遭拒时,此属性才会显示。此属性的有效值包括:
|
status.privacyStatus |
string 视频的隐私状态。 此属性的有效值包括:
|
status.publishAt |
datetime 安排发布视频的日期和时间。只有当视频的隐私权状态为“私享”时,才能设置此参数。该值以 ISO 8601 格式指定。关于此属性的行为,请注意以下几点:
|
status.license |
string 视频的许可。 此属性的有效值包括:
|
status.embeddable |
boolean 此值用于指明视频是否可以嵌入到其他网站中。 |
status.publicStatsViewable |
boolean 此值用于指明视频观看页面上的扩展视频统计信息是否公开显示。默认情况下,这些统计信息可供查看,视频的观看次数和评分等统计信息仍会公开显示,即使该属性的值设为 false 也是如此。 |
status.madeForKids |
boolean 此值指示视频是否被指定为面向儿童的内容,并且包含视频当前的“面向儿童的内容”状态。例如,可以根据 selfDeclaredMadeForKids 属性的值来确定状态。请访问 YouTube 帮助中心,详细了解如何为您的频道、视频或广播设置观众群。
|
status.selfDeclaredMadeForKids |
boolean 在 videos.insert 或 videos.update 请求中,此属性可让频道所有者将视频指定为面向儿童的视频。在 videos.list 请求中,只有在频道所有者为 API 请求授权的情况下,系统才会返回属性值。 |
statistics |
object statistics 对象包含视频的相关统计信息。 |
statistics.viewCount |
unsigned long 视频的观看次数。 |
statistics.likeCount |
unsigned long 已表示喜欢该视频的用户数量。 |
statistics.dislikeCount |
unsigned long 注意:
statistics.dislikeCount 属性自 2021 年 12 月 13 日起已变为私有属性。这意味着只有在 API 请求通过视频所有者的身份验证时,该属性才会包含在 API 响应中。如需了解详情,请参阅修订历史记录。表示不喜欢视频的用户数量。 |
statistics.favoriteCount |
unsigned long 注意:此属性已废弃。弃用从 2015 年 8 月 28 日起生效。现在,该属性的值始终设置为 0 。 |
statistics.commentCount |
unsigned long 视频的评论数。 |
player |
object player 对象包含用于在嵌入式播放器中播放视频的信息。 |
player.embedHtml |
string <iframe> 代码,用于嵌入播放视频的播放器。 |
player.embedHeight |
long player.embedHtml 属性中返回的嵌入式播放器的高度。只有在请求为 maxHeight 和/或 maxWidth 参数指定了值且视频的宽高比已知时,系统才会返回此属性。 |
player.embedWidth |
long 在 player.embedHtml 属性中返回的嵌入式播放器的宽度。只有在请求为 maxHeight 和/或 maxWidth 参数指定了值且视频的宽高比已知时,系统才会返回此属性。 |
topicDetails |
object topicDetails 对象封装了与视频相关联的主题的相关信息。重要提示:如需详细了解与主题 ID 相关的即将发生的更改,请参阅 topicDetails.relevantTopicIds[] 和 topicDetails.topicIds[] 属性的定义以及修订历史记录。 |
topicDetails.topicIds[] |
list 重要提示:此属性自 2016 年 11 月 10 日起已弃用。API 不再返回此属性的值,且现在会由 topicDetails.relevantTopicIds[] 属性值返回与视频关联的所有主题。 |
topicDetails.relevantTopicIds[] |
list 与视频相关的主题 ID 列表。 此属性自 2016 年 11 月 10 日起已弃用。截至 2017 年 11 月 10 日。 重要提示:由于 Freebase 和 Freebase API 已被废弃,因此自 2017 年 2 月 27 日起,主题 ID 的工作方式开始有所不同。届时,YouTube 开始返回一小部分精选主题 ID。 |
topicDetails.topicCategories[] |
list 提供视频内容简要说明的维基百科网址列表。 |
recordingDetails |
object recordingDetails 对象封装了有关录制视频的位置、日期和地址的信息。 |
recordingDetails.locationDescription |
string 此属性自 2017 年 6 月 1 日起已弃用。如需了解详情,请参阅弃用公告。 视频录制位置的文字说明。 |
recordingDetails.location |
object 与视频关联的地理定位信息。请注意,子属性值会标识视频所有者想要与视频关联的位置。该值可修改,可在公开视频上搜索到,并且可能会针对公开视频向用户显示。 |
recordingDetails.location.latitude |
double 此属性自 2017 年 6 月 1 日起已弃用。如需了解详情,请参阅弃用公告。 纬度(以度为单位)。 |
recordingDetails.location.longitude |
double 此属性自 2017 年 6 月 1 日起已弃用。如需了解详情,请参阅弃用公告。 经度(以度为单位)。 |
recordingDetails.location.altitude |
double 此属性自 2018 年 7 月 9 日起已弃用。如需了解详情,请参阅弃用公告。 参考椭球上方的海拔高度(以米为单位)。 |
recordingDetails.recordingDate |
datetime 录制视频的日期和时间。该值以 ISO 8601 ( YYYY-MM-DDThh:mm:ss.sssZ ) 格式指定。 |
fileDetails |
object fileDetails 对象封装了已上传到 YouTube 的视频文件的相关信息,包括文件的分辨率、时长、音频和视频编解码器、视频流比特率等。该数据只能由视频所有者检索。仅当 processingDetails.fileAvailability 属性的值为 available 时,系统才会返回 fileDetails 对象。 |
fileDetails.fileName |
string 已上传文件的名称。无论上传的是视频文件还是其他类型的文件,此字段显示。 |
fileDetails.fileSize |
unsigned long 上传的文件的大小(以字节为单位)。无论上传的是视频文件还是其他类型的文件,此字段显示。 |
fileDetails.fileType |
string YouTube 的视频处理引擎检测到的已上传文件的类型。目前,YouTube 仅处理视频文件,但无论上传的是视频文件还是其他类型的文件,此字段都会显示。 此属性的有效值包括:
|
fileDetails.container |
string 所上传视频文件的容器格式。 |
fileDetails.videoStreams[] |
list 所上传的视频文件中包含的视频流列表。列表中的每一项都包含关于视频流的详细元数据。 |
fileDetails.videoStreams[].widthPixels |
unsigned integer 已编码视频内容的宽度(以像素为单位)。您可以将视频的编码宽高比计算为 width_pixels / height_pixels 。 |
fileDetails.videoStreams[].heightPixels |
unsigned integer 已编码视频内容的高度(以像素为单位)。 |
fileDetails.videoStreams[].frameRateFps |
double 视频流的帧速率(以每秒帧数为单位)。 |
fileDetails.videoStreams[].aspectRatio |
double 视频内容的显示宽高比,用于指定视频的显示宽高比。 |
fileDetails.videoStreams[].codec |
string 视频流使用的视频编解码器。 |
fileDetails.videoStreams[].bitrateBps |
unsigned long 视频流的比特率(以每秒传输的位数表示)。 |
fileDetails.videoStreams[].rotation |
string YouTube 旋转原始源内容以正确显示视频所需的时长。 此属性的有效值包括:
|
fileDetails.videoStreams[].vendor |
string 一个唯一标识视频供应商的值。通常,该值是四个字母的供应商代码。 |
fileDetails.audioStreams[] |
list 所上传的视频文件中包含的音频流列表。列表中的每一项都包含有关音频流的详细元数据。 |
fileDetails.audioStreams[].channelCount |
unsigned integer 流中包含的音频声道数。 |
fileDetails.audioStreams[].codec |
string 流使用的音频编解码器。 |
fileDetails.audioStreams[].bitrateBps |
unsigned long 音频流的比特率(以每秒传输的位数表示)。 |
fileDetails.audioStreams[].vendor |
string 一个唯一标识视频供应商的值。通常,该值是四个字母的供应商代码。 |
fileDetails.durationMs |
unsigned long 上传的视频的时长(以毫秒为单位)。 |
fileDetails.bitrateBps |
unsigned long 所上传视频文件的组合(视频和音频)比特率(以每秒传输的位数表示)。 |
fileDetails.creationTime |
string 上传的视频文件的创建日期和时间。该值以 ISO 8601 格式指定。目前,支持以下 ISO 8601 格式:
|
processingDetails |
object processingDetails 对象封装了有关 YouTube 处理所上传视频文件的进度信息。对象中的属性用于标识当前的处理状态以及预计 YouTube 完成视频处理所需的剩余时间。该部分还会指明视频是否存在不同类型的数据或内容,例如文件详细信息或缩略图。processingProgress 对象设计为可轮询,以便上传的视频可以跟踪 YouTube 处理上传的视频文件的进度。该数据只能由视频所有者检索。 |
processingDetails.processingStatus |
string 视频的处理状态。此值用于指明 YouTube 是能够处理视频,还是视频仍在处理中。 此属性的有效值包括:
|
processingDetails.processingProgress |
object processingProgress 对象包含 YouTube 在处理视频方面所取得的进度信息。只有当视频的处理状态为 processing 时,这些值才具有相关性。 |
processingDetails.processingProgress.partsTotal |
unsigned long 视频需要处理的部分总数估算值。在 YouTube 处理视频期间,系统可能会更新该数字,以提供更精确的估算值。 |
processingDetails.processingProgress.partsProcessed |
unsigned long YouTube 已处理的视频部分数量。您可以通过计算以下公式来估算 YouTube 已处理的视频所占的百分比: 100 * parts_processed / parts_total 请注意,由于估算的部分数量增加,但已处理的部分数量不会相应地增加,因此当 YouTube 处理视频时,计算出的进度可能会周期性地减少。 |
processingDetails.processingProgress.timeLeftMs |
unsigned long YouTube 完成视频处理所需的时间(以毫秒计)的估算值。 |
processingDetails.processingFailureReason |
string YouTube 无法处理视频的原因。仅当 processingStatus 属性的值为 failed 时,此属性才会有值。此属性的有效值包括:
|
processingDetails.fileDetailsAvailability |
string 此值用于指明已上传视频的文件详情。您可以通过在 videos.list() 请求中请求 fileDetails 部分来检索视频的文件详情。 |
processingDetails.processingIssuesAvailability |
string 此值用于指明视频处理引擎是否生成了可能会提高 YouTube 处理视频能力的建议、解释视频处理问题的警告,或导致视频处理问题的错误。您可以通过在 videos.list() 请求中请求 suggestions 部分来检索这些建议。 |
processingDetails.tagSuggestionsAvailability |
string 此值用于指明视频是否有可用的关键字(标签)建议。您可以在视频的元数据中添加标签,以便其他用户更轻松地找到该视频。您可以通过在 videos.list() 请求中请求 suggestions 部分来检索这些建议。 |
processingDetails.editorSuggestionsAvailability |
string 此值用于指明视频是否有可用的视频编辑建议,此类建议有助于提升视频画质或播放体验。您可以通过在 videos.list() 请求中请求 suggestions 部分来检索这些建议。 |
processingDetails.thumbnailsAvailability |
string 此值用于指明是否已为视频生成缩略图。 |
suggestions |
object suggestions 对象封装了有助于识别提升视频质量或所上传视频元数据的机会的建议。该数据只能由视频所有者检索。仅当 processingDetails.tagSuggestionsAvailability 属性或 processingDetails.editorSuggestionsAvailability 属性的值为 available 时,系统才会返回 suggestions 对象。 |
suggestions.processingErrors[] |
list 一系列错误,这些错误会导致 YouTube 无法成功处理上传的视频。这些错误表明,无论视频当前的处理状态如何,该状态最终肯定都为 failed 。此属性的有效值包括:
|
suggestions.processingWarnings[] |
list YouTube 可能难以对上传的视频进行转码或可能导致转码错误的一系列原因。这些警告是在 YouTube 实际处理上传的视频文件之前生成的。此外,它们还会找出一些问题,并不一定表示视频处理会失败,但仍可能导致同步问题、视频失真或音轨缺失等问题。 此属性的有效值包括:
|
suggestions.processingHints[] |
list 可能有助于提升 YouTube 处理视频能力的建议列表。 此属性的有效值包括:
|
suggestions.tagSuggestions[] |
list 可添加到视频元数据中的一系列关键字标签,以便提高用户在 YouTube 上搜索或浏览时找到您视频的可能性。 |
suggestions.tagSuggestions[].tag |
string 为视频建议的关键字标记。 |
suggestions.tagSuggestions[].categoryRestricts[] |
list 与此标签相关的一组视频类别。您可以根据这些信息,根据视频上传者与视频相关联的视频类别显示适当的标签建议。默认情况下,如果未给关键字定义任何限制,则标记建议适用于所有类别。 |
suggestions.editorSuggestions[] |
list 可用于改善所上传视频的视频画质或播放体验的视频编辑操作列表。 此属性的有效值包括:
|
liveStreamingDetails |
object liveStreamingDetails 对象包含有关直播视频直播的元数据。仅当视频是即将开始、正在进行或已完成的直播时,该对象才会显示在 video 资源中。 |
liveStreamingDetails.actualStartTime |
datetime 直播实际开始的时间。该值以 ISO 8601 格式指定。在广播开始前,此值不可用。 |
liveStreamingDetails.actualEndTime |
datetime 直播实际结束的时间。该值以 ISO 8601 格式指定。直播结束后,此值才可用。 |
liveStreamingDetails.scheduledStartTime |
datetime 预定的直播开始时间。该值以 ISO 8601 格式指定。 |
liveStreamingDetails.scheduledEndTime |
datetime 直播的预定结束时间。该值以 ISO 8601 格式指定。如果值为空或该属性不存在,则广播会被安排无限期地继续。 |
liveStreamingDetails.concurrentViewers |
unsigned long 当前观看直播的观看者人数。如果直播目前有观看者,并且直播所有者未隐藏视频的观看次数,则此属性及其值将存在。请注意,直播结束后,YouTube 会停止跟踪直播的同时观看人数。因此,此属性不会标识在观看已结束的直播归档视频的观看者人数。 YouTube Data API 返回的并发观看者计数可能与 YouTube 数据分析中经过处理、不含垃圾内容的并发观看者计数不同。如需详细了解直播指标,请访问 YouTube 帮助中心。
|
liveStreamingDetails.activeLiveChatId |
string 此视频随附的当前进行中的实时聊天的 ID。只有当视频是当前启用了实时聊天的直播时,此字段才会填充。待直播过渡到完成此字段后,系统将移除此字段,并关闭实时聊天。对于持续进行的直播,实时聊天 ID 将不再与此视频相关联,而是与常驻页面上显示的新视频相关联。 |
localizations |
object localizations 对象包含视频元数据的翻译。 |
localizations.(key) |
object 与键值对关联的本地化文本的语言。该值是一个包含 BCP-47 语言代码的字符串。 |
localizations.(key).title |
string 本地化的视频标题。 |
localizations.(key).description |
string 本地化的视频说明。 |