Videos: insert

Lädt ein Video auf YouTube hoch und legt optional die Metadaten des Videos fest.

Diese Methode unterstützt den Media-Upload. Hochgeladene Dateien müssen die folgenden Einschränkungen erfüllen:

  • Maximale Dateigröße:256 GB
  • Akzeptierte MIME-Typen für Medien:video/*, application/octet-stream

Auswirkungen auf das Kontingent:100 Aufrufe pro Tag. Ein Aufruf dieser Methode hat Kontingentkosten von 1 Einheit im Kontingent-Bucket „Video-Uploads“.

Gängige Anwendungsfälle

Anfrage

HTTP-Anfrage

POST https://www.googleapis.com/upload/youtube/v3/videos

Autorisierung

Diese Anfrage benötigt eine Autorisierung mit mindestens einem der folgenden Bereiche (weitere Informationen zu Authentifizierung und Autorisierung).

Bereich
https://www.googleapis.com/auth/youtube.upload
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtubepartner
https://www.googleapis.com/auth/youtube.force-ssl

Parameter

In der folgenden Tabelle sind die Parameter aufgeführt, die von dieser Abfrage unterstützt werden. Alle aufgeführten Parameter sind Abfrageparameter.

Parameter
Erforderliche Parameter
part string
Der Parameter part hat bei diesem Vorgang zwei Funktionen. Er gibt die Eigenschaften an, die durch den Schreibvorgang festgelegt werden, sowie die Eigenschaften, die in der API-Antwort enthalten sein sollen.

Beachten Sie, dass nicht alle Teile Eigenschaften enthalten, die beim Einfügen oder Aktualisieren eines Videos festgelegt werden können. Das Objekt statistics enthält beispielsweise Statistiken, die von YouTube für ein Video berechnet werden, und keine Werte, die Sie festlegen oder ändern können. Wenn der Parameterwert einen part angibt, der keine veränderlichen Werte enthält, ist dieser part trotzdem in der API-Antwort enthalten.

Die folgende Liste enthält die part-Namen, die Sie im Parameterwert angeben können:
  • brandPartner
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
Optionale Parameter
notifySubscribers boolean
Der Parameter notifySubscribers gibt an, ob YouTube eine Benachrichtigung über das neue Video an Nutzer senden soll, die den Kanal des Videos abonniert haben. Ein Parameterwert von True bedeutet, dass Abonnenten über neu hochgeladene Videos benachrichtigt werden. Wenn ein Kanalinhaber jedoch viele Videos hochlädt, kann er den Wert auf False setzen, um zu vermeiden, dass Abonnenten des Kanals über jedes neue Video benachrichtigt werden. Der Standardwert ist True.
onBehalfOfContentOwner string
Dieser Parameter kann nur in einer ordnungsgemäß autorisierten Anfrage verwendet werden. Hinweis: Dieser Parameter ist ausschließlich für YouTube-Content-Partner vorgesehen.

Der onBehalfOfContentOwner Parameter gibt an, dass die Autorisierungsdaten der Anfrage einen YouTube-CMS-Nutzer identifizieren, der im Namen des im Parameterwert angegebenen Content-Inhabers handelt. Dieser Parameter ist für YouTube-Content-Partner vorgesehen, die viele verschiedene YouTube-Kanäle besitzen und verwalten. So können Rechteinhaber sich einmal authentifizieren und auf alle ihre Video- und Kanaldaten zugreifen, ohne für jeden einzelnen Kanal Authentifizierungsdaten angeben zu müssen. Das CMS-Konto, mit dem sich der Nutzer authentifiziert, muss mit dem angegebenen YouTube-Rechteinhaber verknüpft sein.
onBehalfOfContentOwnerChannel string
Dieser Parameter kann nur in einer ordnungsgemäß autorisierten Anfrage verwendet werden. Dieser Parameter kann nur in einer ordnungsgemäß autorisierten Anfrage verwendet werden. Hinweis: Dieser Parameter ist ausschließlich für YouTube-Content-Partner vorgesehen.

Der onBehalfOfContentOwnerChannel Parameter gibt die YouTube-Kanal-ID des Kanals an, dem ein Video hinzugefügt wird. Dieser Parameter ist erforderlich, wenn in einer Anfrage ein Wert für den Parameter onBehalfOfContentOwner angegeben wird, und er kann nur in Verbindung mit diesem Parameter verwendet werden. Außerdem muss die Anfrage mit einem CMS-Konto autorisiert werden, das mit dem Content-Inhaber verknüpft ist, der im Parameter onBehalfOfContentOwner angegeben ist. Schließlich muss der Kanal, der im Parameterwert onBehalfOfContentOwnerChannel angegeben ist, mit dem Content-Inhaber verknüpft sein, der im Parameter onBehalfOfContentOwner angegeben ist.

Dieser Parameter ist für YouTube-Content-Partner vorgesehen, die viele verschiedene YouTube-Kanäle besitzen und verwalten. So können Rechteinhaber sich einmal authentifizieren und Aktionen im Namen des im Parameterwert angegebenen Kanals ausführen, ohne für jeden einzelnen Kanal Authentifizierungsdaten angeben zu müssen.

Anfragetext

Geben Sie im Anfragetext eine Videoressource an. Für diese Ressource gilt Folgendes:

  • Sie können Werte für diese Eigenschaften festlegen:

    • snippet.title
    • snippet.description
    • snippet.tags[]
    • snippet.categoryId
    • snippet.defaultLanguage
    • localizations.(key)
    • localizations.(key).title
    • localizations.(key).description
    • status.embeddable
    • status.license
    • status.privacyStatus: Wenn Sie keinen Wert für diese Eigenschaft angeben, wird der Datenschutzstatus des hochgeladenen Videos standardmäßig auf public gesetzt. Bestimmte Uploads können je nach den Kontoeinstellungen des Creators standardmäßig auf private gesetzt werden, wie in der YouTube-Hilfe erläutert. Für Videos, die über nicht verifizierte API-Projekte hochgeladen wurden, ist der private Betrachtungsmodus nicht erforderlich.
    • status.publicStatsViewable
    • status.publishAt
    • status.selfDeclaredMadeForKids
    • status.containsSyntheticMedia
    • recordingDetails.recordingDate

Antwort

Bei Erfolg gibt diese Methode eine Videoressource im Antworttext zurück.

Beispiele

Hinweis:Die folgenden Codebeispiele stellen möglicherweise nicht alle unterstützten Programmiersprachen dar. Eine Liste der unterstützten Sprachen finden Sie in der Dokumentation zu den Clientbibliotheken.

Ok

In diesem Codebeispiel wird die Methode videos.insert der API aufgerufen, um ein Video auf den Kanal hochzuladen, der mit der Anfrage verknüpft ist.

In diesem Beispiel wird die Go-Clientbibliothek verwendet.

package main

import (
	"flag"
	"fmt"
	"log"
	"os"
	"strings"

	"google.golang.org/api/youtube/v3"
)

var (
	filename    = flag.String("filename", "", "Name of video file to upload")
	title       = flag.String("title", "Test Title", "Video title")
	description = flag.String("description", "Test Description", "Video description")
	category    = flag.String("category", "22", "Video category")
	keywords    = flag.String("keywords", "", "Comma separated list of video keywords")
	privacy     = flag.String("privacy", "unlisted", "Video privacy status")
)

func main() {
	flag.Parse()

	if *filename == "" {
		log.Fatalf("You must provide a filename of a video file to upload")
	}

	client := getClient(youtube.YoutubeUploadScope)

	service, err := youtube.New(client)
	if err != nil {
		log.Fatalf("Error creating YouTube client: %v", err)
	}

	upload := &youtube.Video{
		Snippet: &youtube.VideoSnippet{
			Title:       *title,
			Description: *description,
			CategoryId:  *category,
		},
		Status: &youtube.VideoStatus{PrivacyStatus: *privacy},
	}

	// The API returns a 400 Bad Request response if tags is an empty string.
	if strings.Trim(*keywords, "") != "" {
		upload.Snippet.Tags = strings.Split(*keywords, ",")
	}

	call := service.Videos.Insert("snippet,status", upload)

	file, err := os.Open(*filename)
	defer file.Close()
	if err != nil {
		log.Fatalf("Error opening %v: %v", *filename, err)
	}

	response, err := call.Media(file).Do()
	handleError(err, "")
	fmt.Printf("Upload successful! Video ID: %v\n", response.Id)
}

.NET

In diesem Codebeispiel wird die Methode videos.insert der API aufgerufen, um ein Video auf den Kanal hochzuladen, der mit der Anfrage verknüpft ist.

In diesem Beispiel wird die .NET-Clientbibliothek verwendet.

using System;
using System.IO;
using System.Reflection;
using System.Threading;
using System.Threading.Tasks;

using Google.Apis.Auth.OAuth2;
using Google.Apis.Services;
using Google.Apis.Upload;
using Google.Apis.Util.Store;
using Google.Apis.YouTube.v3;
using Google.Apis.YouTube.v3.Data;

namespace Google.Apis.YouTube.Samples
{
  /// <summary>
  /// YouTube Data API v3 sample: upload a video.
  /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher.
  /// See https://developers.google.com/api-client-library/dotnet/get_started
  /// </summary>
  internal class UploadVideo
  {
    [STAThread]
    static void Main(string[] args)
    {
      Console.WriteLine("YouTube Data API: Upload Video");
      Console.WriteLine("==============================");

      try
      {
        new UploadVideo().Run().Wait();
      }
      catch (AggregateException ex)
      {
        foreach (var e in ex.InnerExceptions)
        {
          Console.WriteLine("Error: " + e.Message);
        }
      }

      Console.WriteLine("Press any key to continue...");
      Console.ReadKey();
    }

    private async Task Run()
    {
      UserCredential credential;
      using (var stream = new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read))
      {
        credential = await GoogleWebAuthorizationBroker.AuthorizeAsync(
            GoogleClientSecrets.Load(stream).Secrets,
            // This OAuth 2.0 access scope allows an application to upload files to the
            // authenticated user's YouTube channel, but doesn't allow other types of access.
            new[] { YouTubeService.Scope.YoutubeUpload },
            "user",
            CancellationToken.None
        );
      }

      var youtubeService = new YouTubeService(new BaseClientService.Initializer()
      {
        HttpClientInitializer = credential,
        ApplicationName = Assembly.GetExecutingAssembly().GetName().Name
      });

      var video = new Video();
      video.Snippet = new VideoSnippet();
      video.Snippet.Title = "Default Video Title";
      video.Snippet.Description = "Default Video Description";
      video.Snippet.Tags = new string[] { "tag1", "tag2" };
      video.Snippet.CategoryId = "22"; // See https://developers.google.com/youtube/v3/docs/videoCategories/list
      video.Status = new VideoStatus();
      video.Status.PrivacyStatus = "unlisted"; // or "private" or "public"
      var filePath = @"REPLACE_ME.mp4"; // Replace with path to actual movie file.

      using (var fileStream = new FileStream(filePath, FileMode.Open))
      {
        var videosInsertRequest = youtubeService.Videos.Insert(video, "snippet,status", fileStream, "video/*");
        videosInsertRequest.ProgressChanged += videosInsertRequest_ProgressChanged;
        videosInsertRequest.ResponseReceived += videosInsertRequest_ResponseReceived;

        await videosInsertRequest.UploadAsync();
      }
    }

    void videosInsertRequest_ProgressChanged(Google.Apis.Upload.IUploadProgress progress)
    {
      switch (progress.Status)
      {
        case UploadStatus.Uploading:
          Console.WriteLine("{0} bytes sent.", progress.BytesSent);
          break;

        case UploadStatus.Failed:
          Console.WriteLine("An error prevented the upload from completing.\n{0}", progress.Exception);
          break;
      }
    }

    void videosInsertRequest_ResponseReceived(Video video)
    {
      Console.WriteLine("Video id '{0}' was successfully uploaded.", video.Id);
    }
  }
}

Ruby

In diesem Beispiel wird die Methode videos.insert der API aufgerufen, um ein Video auf den Kanal hochzuladen, der mit der Anfrage verknüpft ist.

In diesem Beispiel wird die Ruby-Clientbibliothek verwendet.

#!/usr/bin/ruby

require 'rubygems'
gem 'google-api-client', '>0.7'
require 'google/api_client'
require 'google/api_client/client_secrets'
require 'google/api_client/auth/file_storage'
require 'google/api_client/auth/installed_app'
require 'trollop'

# A limited OAuth 2 access scope that allows for uploading files, but not other
# types of account access.
YOUTUBE_UPLOAD_SCOPE = 'https://www.googleapis.com/auth/youtube.upload'
YOUTUBE_API_SERVICE_NAME = 'youtube'
YOUTUBE_API_VERSION = 'v3'

def get_authenticated_service
  client = Google::APIClient.new(
    :application_name => $PROGRAM_NAME,
    :application_version => '1.0.0'
  )
  youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION)

  file_storage = Google::APIClient::FileStorage.new("#{$PROGRAM_NAME}-oauth2.json")
  if file_storage.authorization.nil?
    client_secrets = Google::APIClient::ClientSecrets.load
    flow = Google::APIClient::InstalledAppFlow.new(
      :client_id => client_secrets.client_id,
      :client_secret => client_secrets.client_secret,
      :scope => [YOUTUBE_UPLOAD_SCOPE]
    )
    client.authorization = flow.authorize(file_storage)
  else
    client.authorization = file_storage.authorization
  end

  return client, youtube
end

def main
  opts = Trollop::options do
    opt :file, 'Video file to upload', :type => String
    opt :title, 'Video title', :default => 'Test Title', :type => String
    opt :description, 'Video description',
          :default => 'Test Description', :type => String
    opt :category_id, 'Numeric video category. See https://developers.google.com/youtube/v3/docs/videoCategories/list',
          :default => 22, :type => :int
    opt :keywords, 'Video keywords, comma-separated',
          :default => '', :type => String
    opt :privacy_status, 'Video privacy status: public, private, or unlisted',
          :default => 'public', :type => String
  end

  if opts[:file].nil? or not File.file?(opts[:file])
    Trollop::die :file, 'does not exist'
  end

  client, youtube = get_authenticated_service

  begin
    body = {
      :snippet => {
        :title => opts[:title],
        :description => opts[:description],
        :tags => opts[:keywords].split(','),
        :categoryId => opts[:category_id],
      },
      :status => {
        :privacyStatus => opts[:privacy_status]
      }
    }

    videos_insert_response = client.execute!(
      :api_method => youtube.videos.insert,
      :body_object => body,
      :media => Google::APIClient::UploadIO.new(opts[:file], 'video/*'),
      :parameters => {
        :uploadType => 'resumable',
        :part => body.keys.join(',')
      }
    )

    videos_insert_response.resumable_upload.send_all(client)

    puts "Video id '#{videos_insert_response.data.id}' was successfully uploaded."
  rescue Google::APIClient::TransmissionError => e
    puts e.result.body
  end
end

main

Fehler

In der folgenden Tabelle sind die Fehlermeldungen aufgeführt, die von der API als Antwort auf einen Aufruf dieser Methode zurückgegeben werden können. Weitere Informationen finden Sie in der Dokumentation zu Fehlermeldungen.

Fehlertyp Fehlerdetails Beschreibung
badRequest (400) defaultLanguageNotSet In der Anfrage werden lokalisierte Videodetails hinzugefügt, ohne die Standardsprache der Videodetails anzugeben.
badRequest (400) invalidCategoryId Die Eigenschaft snippet.categoryId gibt eine ungültige Kategorie-ID an. Verwenden Sie die Methode videoCategories.list, um unterstützte Kategorien abzurufen.
badRequest (400) invalidDescription In den Metadaten der Anfrage wird eine ungültige Videobeschreibung angegeben.
badRequest (400) invalidFilename Der im Header Slug angegebene Videodateiname ist ungültig.
badRequest (400) invalidPublishAt In den Metadaten der Anfrage wird eine ungültige geplante Veröffentlichungszeit angegeben.
badRequest (400) invalidRecordingDetails Das Objekt recordingDetails in den Metadaten der Anfrage gibt ungültige Aufnahmedetails an.
badRequest (400) invalidTags In den Metadaten der Anfrage werden ungültige Video-Keywords angegeben.
badRequest (400) invalidTitle In den Metadaten der Anfrage wird ein ungültiger oder leerer Videotitel angegeben.
badRequest (400) invalidVideoGameRating In den Metadaten der Anfrage wird eine ungültige Videospielbewertung angegeben.
badRequest (400) invalidVideoMetadata Die Metadaten der Anfrage sind ungültig.
badRequest (400) mediaBodyRequired Die Anfrage enthält keine Videoinhalte.
badRequest (400) uploadLimitExceeded Der Nutzer hat die zulässige Anzahl von Videos überschritten, die er hochladen darf.
forbidden (403) forbidden
forbidden (403) forbiddenLicenseSetting In der Anfrage wird versucht, eine ungültige Lizenz für das Video festzulegen.
forbidden (403) forbiddenPrivacySetting In der Anfrage wird versucht, eine ungültige Datenschutzeinstellung für das Video festzulegen.

Testen!

Mit dem APIs Explorer können Sie diese API aufrufen und sich die API-Anfrage und -Antwort ansehen.