凡是在 2020 年 7 月 28 日之後建立的未經驗證 API 專案,透過
videos.insert
端點上傳的影片都會限制為私人檢視模式。如要解除這項限制,每個 API 專案都必須接受稽核,驗證是否符合《服務條款》。詳情請參閱 API 修訂版本記錄。video
資源代表 YouTube 影片。
方法
這個 API 支援下列 videos
資源方法:
資源表示法
下列 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 表示影片是即將開始/進行中的現場直播。如果影片不是即將開始/進行中的直播活動,則會設為「無」。 這個屬性的有效值如下:
|
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 時間長度。舉例來說,如果影片長度至少一分鐘,且長度短於一小時,則影片長度的格式為 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 影片自 Garanzie nelle Comunicazioni (AGCOM) 評為 Autorità 的影片。 這項資源的有效值如下:
|
contentDetails.contentRating.anatelRating |
string 這部影片在智利電視的 Anatel (Asociación Nacional de Televisión) 分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.bbfcRating |
string 影片的英國電影分級委員會 (BBFC) 分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.bfvcRating |
string 影片自泰國電影和影片審查局的分級。 這個屬性的有效值如下:
|
contentDetails.contentRating.bmukkRating |
string 影片自奧地利媒體分級委員會 (Bundesministerium für Unterricht, Kunst und Kultur) 的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.catvRating |
string Canadian TV 分級系統 - Canadian Radio-Television and Telecommunications Commission (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 AL AUDIOVIZUALULUI (CNA) 評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.cncRating |
string 法國的分級系統 - 歐盟執委會 (Commission de Mationique) 這個屬性的有效值如下:
|
contentDetails.contentRating.csaRating |
string 影片自 France 的 Conseil supérieur de l?audiovisuel 系統評比,的評分是廣播內容費率。 這個屬性的有效值如下:
|
contentDetails.contentRating.cscfRating |
string 來自盧森堡委員會 (Commission de surveillance de la category des Films,簡稱 CSCF) 的影片評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.czfilmRating |
string 影片在捷克共和國的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.djctqRating |
string 這部影片的「Departamento de Justiça, Classificação, Qualificação e Títulos (DJCQT - Brazil)」分級。 此資源的有效值如下:
|
contentDetails.contentRating.djctqRatingReasons[] |
list 說明影片為何獲得 DJCQT (巴西) 評等的原因。 |
contentDetails.contentRating.ecbmctRating |
string 土耳其的分級系統 - 文化與觀光部評估與分類委員會 這項資源的有效值如下:
|
contentDetails.contentRating.eefilmRating |
string 影片在愛沙尼亞的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.egfilmRating |
string 影片在埃及的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.eirinRating |
string 影片的 Eirin (映倫) 分級。小艾是日本的分級系統。 這項屬性的有效值如下:
|
contentDetails.contentRating.fcbmRating |
string 馬來西亞電影審查委員會 (Film Censorship Board) 提供的影片分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.fcoRating |
string 來自香港電影辦公室、報紙和文章管理局的分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.fmocRating |
string 這項資源已於 2015 年 11 月 2 日淘汰。請改用 contentDetails.contentRating.cncRating 屬性。影片中心的 National 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 - Spain) 分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.ifcoRating |
string 影片的愛爾蘭電影分級辦公室 (IFCO - Ireland) 分級。詳情請參閱 IFCO 網站。 這項資源的有效值如下:
|
contentDetails.contentRating.ilfilmRating |
string 影片在以色列的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.incaaRating |
string 影片的 INCAA (Instituto Nacional de Cine y Artes Audiovisuales - 阿根廷) 分級。 這個屬性的有效值如下:
|
contentDetails.contentRating.kfcbRating |
string 影片自肯亞電影分級委員會 (Kenya Film Classification Board) 的分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.kijkwijzerRating |
string voor de Classificatie van Audiovisuele Media (荷蘭)。 這項屬性的有效值如下:
|
contentDetails.contentRating.kmrbRating |
string 這部影片的韓國媒體分級委員會 (調整大小為會列出不慎修補程式委員會)。KMRB 在韓國為影片評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.lsfRating |
string 自印尼的 Lem Baa Sensor Film 的影片分級。 這個屬性的有效值如下:
|
contentDetails.contentRating.mccaaRating |
string 馬爾他電影年齡分級委員會 (Malta's Film Age-Classification Board) 所提供的影片分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.mccypRating |
string 影片自丹麥電影協會 (Det Danske Filminstitut) 兒童與青少年媒體委員會 (Det Danske Filminstitut) 的審核結果皆為。 這項資源的有效值如下:
|
contentDetails.contentRating.mcstRating |
string 越南的影片分級系統 - MCST 這個屬性的有效值如下:
|
contentDetails.contentRating.mdaRating |
string 影片來自新加坡媒體發展局 (MDA) 的分級,具體來說是美國電影審查局 (BFC)。 這個屬性的有效值如下:
|
contentDetails.contentRating.medietilsynetRating |
string 影片自挪威媒體管理局 Medietilsynet 的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.mekuRating |
string 芬蘭 Kansallinen Audiovisuaalinen Instituutti (國家影音研究所) 的影片評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.mibacRating |
string 影片自《衛報》 (Ministero dei Beni e delle Attività Culturali e del Turismo) 的評分)。 這項資源的有效值如下:
|
contentDetails.contentRating.mocRating |
string 影片的 Cultura (哥倫比亞) 評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.moctwRating |
string 臺灣文化部 (文化部) 提供的影片評分。 這項資源的有效值如下:
|
contentDetails.contentRating.mpaaRating |
string 影片的美國電影協會 (MPAA) 評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.mpaatRating |
string 美國電影協會 (Motion Picture Association of America) 的電影預告片和預覽評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.mtrcbRating |
string 影片自 Movie and Television Review and Classification Board (菲律賓)。 這項資源的有效值如下:
|
contentDetails.contentRating.nbcRating |
string 影片自馬爾地夫國家分類局 (Maldives National Bureau of Classification) 的評分。 這項資源的有效值如下:
|
contentDetails.contentRating.nfrcRating |
string 影片自保加利亞國家電影中心收錄的分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.nfvcbRating |
string 影片自奈及利亞國家電影和影片審查委員會 (National Film and Video Censors Board) 所提供的分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.nkclvRating |
string 影片自 Nacionàis Kino centrs (拉脫維亞國家電影中心) 的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.oflcRating |
string 影片辦公室 (Office of Film and Literature Classification (OFLC - 紐西蘭)) 分級。 這項屬性的有效值如下:
|
contentDetails.contentRating.pefilmRating |
string 影片在秘魯的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.resorteviolenciaRating |
string 影片在委內瑞拉的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.rtcRating |
string 這部影片的「Radio, Television and Cinematography (墨西哥)」分級。 這項資源的有效值如下:
|
contentDetails.contentRating.rteRating |
string 來自愛爾蘭的 Raidió Teilifís Éireann 的影片評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.russiaRating |
string 這部影片的俄羅斯聯邦國家電影登記局 (MKRF - 俄羅斯) 分級。 這個屬性的有效值如下:
|
contentDetails.contentRating.skfilmRating |
string 影片在斯洛伐克的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.smaisRating |
string 影片在冰島的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.smsaRating |
string 影片自美國國家媒體委員會 (Statens Medierød) 提供的評分。 這項屬性的有效值如下:
|
contentDetails.contentRating.tvpgRating |
string 影片的《電視家長指南》(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 物件會封裝影片相關主題的相關資訊。重要事項:請參閱 topicDetails.relevantTopicIds[] 和 topicDetails.topicIds[] 屬性的定義和修訂版本記錄,進一步瞭解主題 ID 即將實施的異動。 |
topicDetails.topicIds[] |
list 重要事項:這項資源已於 2016 年 11 月 10 日淘汰。API 不會再傳回這個屬性的值,而 topicDetails.relevantTopicIds[] 屬性值現在會傳回與影片相關聯的任何主題。 |
topicDetails.relevantTopicIds[] |
list 與影片相關的主題 ID 清單。 這項資源已於 2016 年 11 月 10 日淘汰。自 2017 年 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 本地化影片說明。 |