凡是在 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 時間長度。舉例來說,如果影片長度至少 1 分鐘,不到 1 小時,則長度會採用 PT#M#S 格式,其中字母 PT 表示值指定時間範圍,而字母 M 和 S 分別代表長度 (以分鐘和秒為單位)。M 和 S 字母前方的 # 字元都是用來指定影片分鐘數 (或秒數) 的整數。舉例來說,PT15M33S 表示影片長度為 15 分 33 秒。如果影片長度至少一小時,則影片長度會採用 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 影片的 Australia Classification Board (ACB) 或 Australia Communications and Media Authority (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 這部影片的英國電影分級委員會 (British Board of Film Classification,BBFC) 分級。 這個屬性的有效值如下:
|
contentDetails.contentRating.bfvcRating |
string 泰國電影與影片審查委員會的影片評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.bmukkRating |
string Austrian Board of Media Classification (奧地利媒體分類委員會 (Bundesministerium für Unterricht, Kunst und Kultur)) 提供的評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.catvRating |
string 加拿大電視分級系統 - 加拿大電視分類系統 加拿大廣播電視及電信委員會 (CRTC) 對加拿大英語廣播影片的評分。詳情請參閱 Canadian Broadcast Standards Council 網站。 這項資源的有效值如下:
|
contentDetails.contentRating.catvfrRating |
string 加拿大廣播電視及電信委員會 (CRTC) 提供的法語廣播節目評分。詳情請參閱 Canadian Broadcast Standards Council 網站。 這項資源的有效值如下:
|
contentDetails.contentRating.cbfcRating |
string 影片的 Central Board of Film Certificate (CBFC - 印度) 分級。 這項資源的有效值如下:
|
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 ricstographique 這個屬性的有效值如下:
|
contentDetails.contentRating.csaRating |
string 這部影片的評分依據為法國 Conseil supérieur de l?audiovisuel,此費率為廣播內容提供費率。 這個屬性的有效值如下:
|
contentDetails.contentRating.cscfRating |
string 這部影片的分級:盧森堡委員會針對電影分級 (CSCF) 提供。 這個屬性的有效值如下:
|
contentDetails.contentRating.czfilmRating |
string 這部影片在捷克共和國的分級。 這個屬性的有效值如下:
|
contentDetails.contentRating.djctqRating |
string 這部影片的有效值如下:
|
contentDetails.contentRating.djctqRatingReasons[] |
list 說明影片為何獲得 DJCQT (巴西) 分級。 |
contentDetails.contentRating.ecbmctRating |
string 土耳其分級系統 - 文化與觀光部評估與分類委員會 這項資源的有效值如下:
|
contentDetails.contentRating.eefilmRating |
string 愛沙尼亞的影片評分。 這項資源的有效值如下:
|
contentDetails.contentRating.egfilmRating |
string 這部影片在埃及的分級。 這項資源的有效值如下:
|
contentDetails.contentRating.eirinRating |
string 影片的艾林 (映倫) 評級。艾琳是日本的分級系統。 這個屬性的有效值如下:
|
contentDetails.contentRating.fcbmRating |
string 這部影片由馬來西亞電影審查委員會提供的評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.fcoRating |
string 該影片在香港電影、報紙和文章管理局的評分。 這項資源的有效值如下:
|
contentDetails.contentRating.fmocRating |
string 這項資源已於 2015 年 11 月 2 日淘汰。請改用 contentDetails.contentRating.cncRating 資源。這部影片的 Centre National du cinéma et de l'image animé (法國文化部) 分級。 這個房源的有效值如下:
|
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 這部影片的有效值:
|
contentDetails.contentRating.ifcoRating |
string 這部影片的愛爾蘭電影分級辦公室 (IFCO - Ireland) 分級。詳情請參閱 IFCO 網站。 這項資源的有效值如下:
|
contentDetails.contentRating.ilfilmRating |
string 這部影片在以色列的分級。 這個屬性的有效值如下:
|
contentDetails.contentRating.incaaRating |
string 這部影片的 INCAA (《Instituto Nacional de Cine y Artes Audio 視 es (阿根廷) 國家影音娛樂 - 阿根廷) 分級。 這個屬性的有效值如下:
|
contentDetails.contentRating.kfcbRating |
string 這部影片在肯亞電影分級委員會 (Kenya Film Classification Board) 提供的評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.kijkwijzerRating |
string voor de Classificatie van Audiovisuele Media (荷蘭)。 這個屬性的有效值如下:
|
contentDetails.contentRating.kmrbRating |
string 影片的韓國媒體評議會 (Korea Media Rating Board) 評鑑平台核可。KMRB 能為韓國的影片評分。 這項資源的有效值如下:
|
contentDetails.contentRating.lsfRating |
string 這部影片從印尼的 Lembaga Sensor Film 獲得的評分。 這項資源的有效值如下:
|
contentDetails.contentRating.mccaaRating |
string 馬爾他電影年齡分級委員會提供的影片評分。 這個屬性的有效值包括:
|
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 該影片在臺灣文化部 (Ministry of Culture) 的評分。 這項資源的有效值如下:
|
contentDetails.contentRating.mpaaRating |
string 影片的美國電影協會 (MPAA) 分級。 這個屬性的有效值如下:
|
contentDetails.contentRating.mpaatRating |
string 美國電影協會對電影預告片和預告片的評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.mtrcbRating |
string 《Movie and Television Review and Classification Board》(菲律賓電影與電視審查及分類委員會) 提供的影片評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.nbcRating |
string 該影片在馬爾地夫國家分類局的評分。 這個屬性的有效值如下:
|
contentDetails.contentRating.nfrcRating |
string 保加利亞國家電影中心的影片評分。 這項資源的有效值如下:
|
contentDetails.contentRating.nfvcbRating |
string 這部影片在奈及利亞的 National Film and Video Censors Board (國家電影與影片分級委員會) 評比。 這個屬性的有效值如下:
|
contentDetails.contentRating.nkclvRating |
string 該影片的評分依據為拉脫維亞國家電影中心 (National Film Centre of Latvia)。 這個房源的有效值如下:
|
contentDetails.contentRating.oflcRating |
string 影片的《Office of Film and Literature Classification (OFLC - New Zealand)》分級。 這個屬性的有效值如下:
|
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 日止。 重要事項:由於 Freebase 和 Freebase API 已淘汰,主題 ID 的運作方式也從 2017 年 2 月 27 日起開始不同。屆時 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 ID 不再與這部影片連結,則新的視訊仍會在持續播放的頁面上顯示。 |
localizations |
object localizations 物件包含影片中繼資料的翻譯。 |
localizations.(key) |
object 與鍵/值相關聯的本地化文字語言。這個值是包含 BCP-47 語言代碼的字串。 |
localizations.(key).title |
string 本地化影片標題。 |
localizations.(key).description |
string 本地化影片說明。 |