API Reference

Interfejs YouTube Data API pozwala włączyć do własnej witryny lub aplikacji funkcje, które zwykle są wykonywane w YouTube. Na listach poniżej znajdziesz różne typy zasobów, które można pobrać przy użyciu interfejsu API. Interfejs API obsługuje też metody wstawiania, aktualizowania i usuwania wielu z tych zasobów.

Z tego przewodnika dowiesz się, jak wykonywać wszystkie te operacje za pomocą interfejsu API. Przewodnik jest uporządkowany według typu zasobu. Zasób reprezentuje typ elementu, który stanowi część usługi YouTube. Może to być np. film, playlista lub subskrypcja. W przypadku każdego typu zasobu w przewodniku znajduje się co najmniej 1 reprezentacja danych, a zasoby są przedstawiane jako obiekty JSON. Przewodnik zawiera też informacje o co najmniej 1 obsługiwanych metodach (LIST, POST, DELETE itp.) dla każdego typu zasobów oraz wyjaśnia, jak używać tych metod w aplikacji.

Wywoływanie interfejsu API

Żądania do interfejsu YouTube Data API muszą spełniać te wymagania:

  1. Każde żądanie musi określać klucz interfejsu API (z parametrem key) lub podawać token OAuth 2.0. Twój klucz interfejsu API jest dostępny w panelu Dostęp do interfejsu API w Konsoli programisty w przypadku Twojego projektu.

  2. Do każdego żądania wstawienia, aktualizacji i usunięcia musisz wysłać token autoryzacji. Musisz też wysłać token autoryzacji w przypadku każdego żądania pobierającego prywatne dane uwierzytelnionego użytkownika.

    Dodatkowo niektóre metody interfejsu API do pobierania zasobów mogą obsługiwać parametry wymagające autoryzacji lub zawierać dodatkowe metadane po autoryzacji żądań. Na przykład żądanie pobrania filmów przesłanych przez użytkownika może też zawierać filmy prywatne, jeśli dany użytkownik wyraził na to zgodę.

  3. Interfejs API obsługuje protokół uwierzytelniania OAuth 2.0. Token OAuth 2.0 możesz podać na jeden z tych sposobów:

    • Użyj parametru zapytania access_token w ten sposób: ?access_token=oauth2-token
    • Użyj takiego nagłówka HTTP Authorization: Authorization: Bearer oauth2-token

    Pełne instrukcje dotyczące implementowania uwierzytelniania OAuth 2.0 w aplikacji znajdziesz w przewodniku uwierzytelniania.

Typy zasobów

Zadania

Zasób activity zawiera informacje na temat działań wykonanych w YouTube przez określony kanał lub użytkownika. Działania zgłaszane w kanałach aktywności obejmują ocenę filmu, udostępnienie go, oznaczenie go jako ulubionego, przesłanie filmu itd. Każdy zasób activity określa typ działania, powiązany z nim kanał oraz zasoby powiązane z tym działaniem, np. film, który został oceniony lub przesłany.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /activities Zwraca listę zdarzeń aktywności na kanale, które spełniają kryteria żądania. Możesz na przykład pobrać zdarzenia powiązane z określonym kanałem lub z własnym kanałem użytkownika.
insert POST /activities Uwaga: ta metoda została wycofana i nie jest już obsługiwana.

Napisy

Zasób caption reprezentuje ścieżkę napisów w YouTube. Ścieżka napisów jest powiązana tylko z jednym filmem w YouTube.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
delete DELETE /captions Usuwa określoną ścieżkę napisów.
download GET /captions/id Pobiera ścieżkę z napisami. Ścieżka napisów jest zwracana w pierwotnym formacie, chyba że w żądaniu określono wartość parametru tfmt w oryginalnym języku, chyba że w żądaniu określono wartość parametru tlang.
insert POST /captions Przesyła ścieżkę z napisami.
list GET /captions Zwraca listę ścieżek napisów powiązanych z określonym filmem. Pamiętaj, że odpowiedź interfejsu API nie zawiera rzeczywistych napisów, a metoda captions.download umożliwia pobranie ścieżki napisów.
update PUT /captions Aktualizuje ścieżkę z napisami. Podczas aktualizowania ścieżki z napisami możesz zmienić stan wersji roboczej ścieżki, przesłać nowy plik z napisami lub jedno i drugie.

Banery kanału

Zasób channelBanner zawiera URL, którego można użyć do ustawienia nowo przesłanego obrazu jako obrazu banera kanału.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Przesyła obraz banera kanału do YouTube. Ta metoda przedstawia dwa pierwsze kroki trzyetapowego procesu aktualizowania obrazu banera kanału:

  1. Wywołaj metodę channelBanners.insert, aby przesłać dane obrazu binarnego do YouTube. Obraz musi mieć współczynnik proporcji 16:9 i wymiary co najmniej 2048 x 1152 pikseli. Zalecamy przesłanie obrazu o wymiarach 2560 na 1440 pikseli.
  2. Wyodrębnij wartość właściwości url z odpowiedzi, którą interfejs API zwraca w kroku 1.
  3. Wywołaj metodę channels.update, aby zaktualizować ustawienia marki kanału. Jako wartość właściwości brandingSettings.image.bannerExternalUrl ustaw adres URL uzyskany w kroku 2.

Sekcje kanału

Zasób channelSection zawiera informacje o zbiorze filmów polecanych na kanale. Na przykład sekcja może zawierać najnowsze filmy z kanału, najpopularniejsze filmy lub filmy z co najmniej 1 playlisty.

Pamiętaj, że sekcje kanału są widoczne tylko wtedy, gdy zawartość kanału jest widoczna w widoku przeglądania (a nie w widoku obszaru aktywności). Aby umożliwić wyświetlanie treści na kanale w widoku przeglądania, ustaw w przypadku określonego kanału właściwość brandingSettings.channel.showBrowseView na true.

Kanał może utworzyć maksymalnie 10 półek.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Usuwa sekcję kanału.
insert POST /channelSections Dodaje sekcję kanału do kanału uwierzytelnionego użytkownika. Kanał może utworzyć maksymalnie 10 półek.
list GET /channelSections Zwraca listę channelSection zasobów, które spełniają kryteria żądania do interfejsu API.
update PUT /channelSections Aktualizuje sekcję kanału.

Kanały

Zasób channel zawiera informacje o kanale YouTube.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /channels Zwraca zbiór zawierający 0 lub więcej zasobów channel, które spełniają kryteria żądania.
update PUT /channels Aktualizuje metadane kanału. Pamiętaj, że ta metoda obsługuje obecnie tylko aktualizacje obiektów brandingSettings i invideoPromotion zasobu channel oraz ich właściwości podrzędnych.

Wątki komentarzy

Zasób commentThread zawiera informacje o wątku komentarzy w YouTube, który składa się z komentarza najwyższego poziomu oraz odpowiedzi do tego komentarza (jeśli istnieją). Zasób commentThread może reprezentować komentarze na temat filmu lub kanału.

Zarówno komentarz najwyższego poziomu, jak i odpowiedzi są w rzeczywistości zasobami comment zagnieżdżonymi w zasobie commentThread. Zasób commentThread nie musi zawierać wszystkich odpowiedzi na komentarz. Jeśli chcesz pobrać wszystkie odpowiedzi na dany komentarz, musisz użyć metody comments.list. Pamiętaj też, że na niektóre komentarze nie mają odpowiedzi.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /commentThreads Zwraca listę wątków komentarzy pasujących do parametrów żądania do interfejsu API.
insert POST /commentThreads Tworzy nowy komentarz najwyższego poziomu. Aby dodać odpowiedź na istniejący komentarz, użyj metody comments.insert.

Komentarze

Zasób comment zawiera informacje o pojedynczym komentarzu w YouTube. Zasób comment może reprezentować komentarz na temat filmu lub kanału. Komentarz może też być komentarzem najwyższego poziomu lub odpowiedzią na komentarz najwyższego poziomu.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /comments Zwraca listę komentarzy pasujących do parametrów żądania do interfejsu API.
setModerationStatus POST /comments/setModerationStatus Określa stan moderowania jednego lub większej liczby komentarzy. Żądanie do interfejsu API musi być autoryzowane przez właściciela kanału lub filmu powiązanego z komentarzami.
insert POST /comments Tworzy odpowiedź na istniejący komentarz. Uwaga: aby utworzyć komentarz najwyższego poziomu, użyj metody commentThreads.insert.
markAsSpam POST /comments/markAsSpam Uwaga: ta metoda została wycofana i nie jest już obsługiwana.
delete DELETE /comments Usuwa komentarz.
update PUT /comments Modyfikuje komentarz.

Kategorie przewodnika

Zasób guideCategory określa kategorię, którą YouTube przypisuje algorytmicznie na podstawie treści kanału lub innych wskaźników, takich jak popularność kanału. Lista jest podobna do kategorii filmów. Różnica polega na tym, że przesyłający może przypisać kategorię filmu, ale tylko YouTube może to zrobić.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /guideCategories Zwraca listę kategorii, które można powiązać z kanałami YouTube.

Języki

Zasób i18nLanguage wskazuje język aplikacji obsługiwany przez witrynę YouTube. Język aplikacji może być też określany jako język interfejsu użytkownika. W przypadku witryny YouTube język aplikacji może być wybierany automatycznie na podstawie ustawień konta Google, języka przeglądarki lub lokalizacji adresu IP. Użytkownik może też ręcznie wybrać język interfejsu ze stopki witryny YouTube.

Każdy zasób i18nLanguage określa kod języka i nazwę. Kod języka może być używany jako wartość parametru hl podczas wywoływania metod API takich jak videoCategories.list czy guideCategories.list.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /i18nLanguages Zwraca listę języków aplikacji obsługiwanych przez witrynę YouTube.

Regiony i regiony

Zasób i18nRegion określa obszar geograficzny, który użytkownik YouTube może wybrać jako preferowany region treści. Region treści można też określić jako język treści. W przypadku witryny YouTube region treści może być wybierany automatycznie na podstawie takich danych heurystycznych, jak domena YouTube czy lokalizacja adresu IP użytkownika. Użytkownik może też ręcznie wybrać odpowiedni region treści w stopce witryny YouTube.

Każdy zasób i18nRegion określa kod regionu i nazwę. Kod regionu może służyć jako wartość parametru regionCode podczas wywoływania metod API takich jak search.list, videos.list, activities.list i videoCategories.list.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /i18nRegions Zwraca listę regionów treści obsługiwanych przez witrynę YouTube.

Wspierający

Zasób member reprezentuje osobę wspierającą kanał w YouTube. Wspierający oferuje cykliczną pomoc finansową twórcy i otrzymuje specjalne korzyści. Na przykład wspierający mogą czatować, gdy twórca włączy tryb tylko dla wspierających w czacie.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /members Wyświetla listę wspierających (dawniej nazywanych sponsorami) kanału. Żądanie do interfejsu API musi być autoryzowane przez właściciela kanału.

Poziomy wspierania

Zasób membershipsLevel określa poziom cen dla twórcy, który autoryzował żądanie do interfejsu API.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację zasobu i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /membershipsLevels Zwraca zbiór zawierający 0 lub więcej zasobów membershipsLevel należących do kanału, który autoryzował żądanie do interfejsu API. Poziomy są zwracane w niejawnej kolejności wyświetlania.

Elementy playlisty

Zasób playlistItem identyfikuje inny zasób (np. film) uwzględniony w playliście. Dodatkowo zasób playlistItem zawiera szczegółowe informacje na temat uwzględnionego zasobu, które odnoszą się konkretnie do sposobu jego wykorzystania na danej playliście.

YouTube używa też playlisty do wskazania listy przesłanych filmów na kanał. Każdy element playlistItem na tej liście oznacza 1 przesłany film. Identyfikator playlisty dla tej listy możesz pobrać z channel resource dla danego kanału. Następnie możesz użyć metody playlistItems.list do wyświetlania listy.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Usuwa element playlisty.
insert POST /playlistItems Dodaje zasób do playlisty.
list GET /playlistItems Zwraca zbiór elementów playlisty, które pasują do parametrów żądania do interfejsu API. Możesz pobrać wszystkie elementy playlisty znajdujące się na określonej playliście lub co najmniej jeden element, podając ich unikalne identyfikatory.
update PUT /playlistItems Modyfikuje element playlisty. Możesz na przykład zmienić jego pozycję na playliście.

Playlisty

Zasób playlist reprezentuje playlistę w YouTube. Playlista to zbiór filmów, które można oglądać w określonej kolejności i udostępniać innym użytkownikom. Playlista może zawierać do 200 filmów, a YouTube nie ogranicza liczby playlist tworzonych przez każdego użytkownika. Domyślnie playlisty są widoczne publicznie dla innych użytkowników, ale playlisty mogą być publiczne lub prywatne.

YouTube wykorzystuje też playlisty do identyfikowania specjalnych kolekcji filmów na kanale, na przykład:

  • przesłane filmy
  • pozytywnie oceniane filmy wideo (polubione)
  • historia oglądania
  • Do obejrzenia
Mówiąc dokładniej, te listy są powiązane z kanałem, który jest zbiorem filmów, playlist i innych informacji z YouTube należących do osoby, grupy lub firmy. Identyfikatory playlist dla każdej z tych list możesz znaleźć w channel resource dla danego kanału.

Następnie możesz użyć metody playlistItems.list, aby pobrać dowolną z tych list. Możesz też dodawać elementy do tych list i je z nich usuwać, wywołując metody playlistItems.insert i playlistItems.delete.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
delete DELETE /playlists Usuwa playlistę.
list GET /playlists Zwraca zbiór playlist pasujących do parametrów żądania do interfejsu API. Możesz na przykład pobrać wszystkie playlisty należące do uwierzytelnionego użytkownika albo jedną lub więcej playlist, podając ich unikalne identyfikatory.
insert POST /playlists Tworzy playlistę.
update PUT /playlists Modyfikuje playlistę. Możesz na przykład zmienić tytuł, opis lub ustawienia prywatności playlisty.

Wynik wyszukiwania zawiera informacje o filmie, kanale lub playliście w YouTube, które pasują do parametrów wyszukiwania określonych w żądaniu do interfejsu API. Wynik wyszukiwania wskazuje zasób, który można zidentyfikować, np. film, ale nie ma własnych trwałych danych.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /search Zwraca zbiór wyników wyszukiwania pasujących do parametrów zapytania określonych w żądaniu do interfejsu API. Domyślnie zestaw wyników wyszukiwania identyfikuje pasujące zasoby video, channel i playlist, ale możesz też skonfigurować zapytania w taki sposób, aby pobierały tylko określony typ zasobów.

Subskrypcje

Zasób subscription zawiera informacje o subskrypcji użytkownika YouTube. Subskrypcja powiadamia użytkownika, gdy na kanale dodawane są nowe filmy lub gdy inny użytkownik wykona jedną z kilku czynności w YouTube, takich jak przesłanie filmu, wystawienie oceny lub skomentowanie filmu.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions Usuwa subskrypcję.
insert POST /subscriptions Dodaje subskrypcję kanału uwierzytelnionego użytkownika.
list GET /subscriptions Zwraca zasoby subskrypcji pasujące do kryteriów żądania do interfejsu API.

Miniatury

Zasób thumbnail określa różne rozmiary miniatur powiązanych z danym zasobem. Pamiętaj o tych cechach miniatur:

  • Właściwość snippet.thumbnails zasobu to obiekt, który wskazuje miniatury dostępne dla tego zasobu.
  • Zasób thumbnail zawiera serię obiektów. Nazwa każdego obiektu (default, medium, high itd.) odnosi się do rozmiaru obrazu miniatury.
  • Różne rodzaje zasobów mogą obsługiwać różne rozmiary miniatur.
  • Różne typy zasobów mogą definiować różne rozmiary miniatur o tej samej nazwie. Na przykład miniatura zasobu default w przypadku zasobu video ma zwykle wymiary 120 x 90 pikseli, a w przypadku zasobu channel miniatura default ma zwykle wymiary 88 x 88 pikseli.
  • Zasoby tego samego typu mogą nadal mieć różne rozmiary miniatur w przypadku niektórych obrazów w zależności od rozdzielczości oryginalnego obrazu lub treści przesłanej do YouTube. Na przykład film HD może obsługiwać miniatury w wyższej rozdzielczości niż filmy w innych formatach.
  • Każdy obiekt zawierający informacje o rozmiarze obrazu miniatury ma właściwość width i właściwości height. W przypadku tego obrazu mogą jednak nie być zwracane właściwości szerokości i wysokości.
  • Jeśli przesłany obraz miniatury nie ma wymaganych wymiarów, jego rozmiar zostanie zmieniony tak, aby pasował do właściwego rozmiaru, bez zmiany proporcji. Obraz nie jest przycięty, ale może zawierać czarne paski informujące o prawidłowym rozmiarze.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Przesyła niestandardową miniaturę filmu do YouTube i ustawia ją jako film.

Przyczyny zgłaszania nadużyć do filmów

Zasób videoAbuseReportReason zawiera informacje o przyczynie oznaczenia filmu jako zawierającego nieodpowiednie treści. Gdy aplikacja wywołuje metodę videos.reportAbuse, aby zgłosić nadużycie wideo, żądanie korzysta z informacji z zasobu videoAbuseReportReason, aby ustalić przyczynę zgłoszenia filmu.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Pobierz listę powodów, na podstawie których możesz zgłosić filmy naruszające zasady.

Kategorie wideo

Zasób videoCategory określa kategorię, która została lub może być powiązana z przesłanymi filmami.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
list GET /videoCategories Zwraca listę kategorii, które można powiązać z filmami w YouTube.

Filmy

Zasób video reprezentuje film w YouTube.

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
insert POST /videos Przesyła film do YouTube i opcjonalnie ustawia jego metadane.
list GET /videos Zwraca listę filmów, które pasują do parametrów żądania do interfejsu API.
delete DELETE /videos Usuwa film z YouTube.
update PUT /videos Aktualizuje metadane filmu.
rate POST /videos/rate Dodaj ocenę filmu lub ocenę treści jako „Nie podoba mi się” lub usuń ocenę z filmu.
getRating GET /videos/getRating Pobiera oceny, które autoryzowany użytkownik przyznał liście określonych filmów.
reportAbuse POST /videos/reportAbuse Zgłoś film, który zawiera obraźliwe treści.

Znaki wodne

Zasób watermark określa obraz, który wyświetla się podczas odtwarzania filmów na konkretnym kanale. Możesz też określić kanał docelowy, do którego będzie link z obrazem, a także szczegóły czasu (w tym te decydujące o tym, kiedy znak wodny pojawi się podczas odtwarzania filmu oraz jak długo jest on widoczny).

Aby uzyskać więcej informacji o tym zasobie, zobacz jego reprezentację i listę właściwości.

Metoda Żądanie HTTP Opis
Identyfikatory URI względem obiektu https://www.googleapis.com/youtube/v3
set POST /watermarks/set Przesyła obraz znaku wodnego do YouTube i ustawia go jako kanał.
unset POST /watermarks/unset Usuwa znak wodny kanału.