Content-Veröffentlichung

Du kannst mit der Instagram Graph API einzelne Bilder, Videos, Reels (also Einzelmedien-Posts), Posts mit mehreren Bildern, Videos (Carousel-Posts) oder Stories auf Instagram-Business-Konten veröffentlichen.

Ab dem 1. Juli 2023 werden alle einzelnen Feed-Videos, die über die Instagram Content Publishing API veröffentlicht werden, als Reels gepostet.

Anforderungen

Zugriffsschlüssel

Alle Anfragen müssen den Nutzer*innen-Zugriffsschlüssel des*der App-Nutzer*in enthalten.

Berechtigungen

Zum Veröffentlichen benötigst du eine Kombination aus den folgenden Berechtigungen. Die genaue Kombination hängt davon ab, welche Endpunkte von deiner App verwendet werden. In den Endpunktreferenzen findest du Informationen dazu, welche Berechtigungen jeder Endpunkt erfordert.

Wenn deine App von App-Nutzer*innen verwendet wird, die in deiner App oder in einem Unternehmen, das deine App beansprucht hat, keine Rolle haben, musst du über die App-Review für jede Berechtigung eine Genehmigung beantragen, bevor diese deiner App von App-Nutzer*innen ohne Rolle gewährt werden kann.

Öffentlicher Server

Wir verwenden die in Veröffentlichungsversuchen genutzten Medien in einem cURL-Befehl. Daher müssen die Medien beim Versuch auf einem öffentlich zugänglichen Server gespeichert sein.

Seitenautorisierung

Professionelle Instagram-Konten, die mit einer Seite verbunden sind, die Page Publishing Authorization (PPA) erfordert, können erst veröffentlicht werden, wenn die PPA abgeschlossen wurde.

Es kann sein, dass ein*e App-Nutzer*in Aufgaben auf einer Seite durchführen kann, die zunächst keine PPA erforderte, später aber schon. In diesem Fall könnte der*die App-Nutzer*in erst nach Abschluss der PPA Inhalte im professionellen Instagram-Konto veröffentlichen. Da du nicht wissen kannst, ob die Seite eines*einer App-Nutzer*in eine PPA erfordert, solltest du App-Nutzer*innen empfehlen, die PPA im Vorfeld durchzuführen.

Einschränkungen

Es wird nur das Bildformat JPEG unterstützt. Erweiterte JPEG-Formate wie MPO und JPS werden nicht unterstützt.
Shopping-Markierungen werden nicht unterstützt.
Branded Content-Markierungen werden nicht unterstützt.
Filter werden nicht unterstützt.
Das Veröffentlichen auf Instagram TV wird nicht unterstützt.

Weitere Einschränkungen findest du in der Referenz der einzelnen Endpunkte.

Ratenbegrenzung

Für Instagram-Konten können innerhalb von 24 Stunden maximal 25 Beiträge über die API veröffentlicht werden. Carousels zählen als ein Beitrag. Diese Begrenzung wird auf dem Endpunkt POST /{ig-user-id}/media_publish durchgesetzt, wenn versucht wird, einen Mediencontainer zu veröffentlichen. Deine App sollte ebenfalls die Ratenbegrenzung für Veröffentlichungen durchsetzen. Das gilt vor allem, wenn deine App es Nutzer*innen erlaubt, die Veröffentlichung von Beiträgen für einen bestimmten Zeitpunkt zu planen.

Um die aktuelle Nutzung der Ratenbegrenzung eines Instagram-Business-Kontos zu prüfen, kannst du den Endpunkt GET /{ig-user-id}/content_publishing_limit abfragen.

Endpunkte

Die API besteht aus den folgenden Endpunkten: Informationen zu Nutzungsanforderungen findest du in der Referenzdokumentation zu den einzelnen Endpunkten.

POST /{ig-user-id}/media – Lade Medien hoch und erstelle Medien-Container.
POST /{ig-user-id}/media_publish – Veröffentliche hochgeladene Medien, indem du deren Container verwendest.
GET /{ig-container-id}?fields=status_code – Prüfe Veröffentlichungsberechtigung und -status von Medien-Containern.
GET /{ig-user-id}/content_publishing_limit – Prüfe die aktuelle Nutzung der Ratenbegrenzung für Veröffentlichungen des*der App-Nutzer*in.

Einzelmedien-Posts

Zum Veröffentlichen von einzelnen Bildern, Videos, Stories oder Reels sind zwei Schritte nötig:

Erstelle mit dem Endpunkt POST /{ig-user-id}/media einen Container aus einem auf deinem öffentlichen Server gehosteten Bild oder Video.
Verwende dann den Endpunkt POST /{ig-user-id}/media_publish, um den Container zu veröffentlichen.

Schritt 1 von 2: Container erstellen

Angenommen, du hast hier ein Bild gespeichert:

https://www.example.com/images/bronz-fonz.jpg

Jetzt möchtest du dieses Bild mit dem Hashtag „#BronzFonz“ als Bildunterschrift veröffentlichen. Sende eine Anfrage an den POST /{ig-user-id}/media-Endpunkt:

Beispielanfrage

POST https://graph.facebook.com/v19.0/17841400008460056/media
  ?image_url=https://www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

Damit wird eine Container-ID für das Bild zurückgegeben.

Beispielantwort

{
  "id": "17889455560051444"  // IG Container ID
}

Schritt 2 von 2: Container veröffentlichen

Verwende den Endpunkt POST /{ig-user-id}/media_publish, um die im vorherigen Schritt zurückgegebene Container-ID zu veröffentlichen.

Beispielanfrage

POST https://graph.facebook.com/v19.0/17841400008460056/media_publish ?creation_id=17889455560051444

Beispielantwort

{
  "id": "17920238422030506" // IG Media ID
}

Carousel-Posts

Du kannst bis zu 10 Bilder und/oder Videos in einem einzigen Beitrag (einem Carousel-Post) veröffentlichen. Das Veröffentlichen von Carousels besteht aus drei Schritten:

Verwende den Endpunkt POST /{ig-user-id}/media, um einzelne Elementcontainer für jedes Bild und Video zu erstellen, die im Carousel angezeigt werden.
Verwende den Endpunkt POST /{ig-user-id}/media erneut, um einen einzelnen Carousel-Container für die Elemente zu erstellen.
Verwende den Endpunkt POST /{ig-user-id}/media_publish, um den Carousel-Container zu veröffentlichen.

Carousel-Posts zählen als Einzelbeiträge zur Ratenbegrenzung des Kontos.

Einschränkungen

Carousels können nicht beworben werden.
Carousels sind auf jeweils 10 Bilder und/oder Videos begrenzt.
Carousel-Bilder werden basierend auf dem ersten Bild im Carousel zugeschnitten. Das standardmäßige Seitenverhältnis ist 1:1.

Schritt 1 von 3: Elementcontainer erstellen

Verwende den Endpunkt POST /{ig-user-id}/media, um einen Elementcontainer für das Bild oder Video zu erstellen, das in einem Carousel angezeigt wird. Carousels dürfen jeweils bis zu 10 Bilder und/oder Videos enthalten.

POST /{ig-user-id}/media

Parameter

Die folgenden Parameter sind erforderlich. Weitere unterstützte Parameter findest du in der Referenz für den Endpunkt POST /{ig-user-id}/media.

is_carousel_item: Setze diesen Parameter auf true. Gibt an, ob das Bild oder Video in einem Carousel erscheint.
image_url (nur Bilder): Der Pfad zum Bild. Wir verwenden die übergebene URL deines Bilds in einem cURL-Befehl. Daher muss es auf einem öffentlichen Server gespeichert sein.
media_type (nur Videos): Setze diesen Parameter auf VIDEO. Damit gibst du an, dass das Medienelement ein Video ist.
video_url (nur Videos): Pfad zum Video. Wir verwenden die übergebene URL deines Videos in einem cURL-Befehl. Daher muss es auf einem öffentlichen Server gespeichert sein.

Wenn der Vorgang erfolgreich ist, gibt die API eine Elementcontainer-ID zurück, die beim Erstellen des Carousel-Containers verwendet werden kann.

Wiederhole diesen Vorgang für alle Bilder oder Videos, die im Carousel erscheinen sollen.

Beispielanfrage

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."

Beispielantwort

{
  "id": "17899506308402767"
}

Schritt 2 von 3: Carousel-Container erstellen

Verwende den Endpunkt POST /{ig-user-id}/media, um einen Carousel-Container zu erstellen.

POST /{ig-user-id}/media

Parameter

Die folgenden Parameter sind erforderlich. Weitere unterstützte Parameter findest du in der Referenz für den Endpunkt POST /{ig-user-id}/media.

media_type: Setze diesen Parameter auf CAROUSEL. Gibt an, dass der Container für ein Carousel dient.
children: Ein Array mit bis zu 10 Container-IDs der Bilder und Videos, die im veröffentlichten Carousel erscheinen sollen. Carousels können jeweils bis zu 10 Bilder und/oder Videos enthalten.

Beispielanfrage

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."

Beispielantwort

{
  "id": "18000748627392977"
}

Schritt 3 von 3: Carousel-Container veröffentlichen

Verwende den Endpunkt POST /{ig-user-id}/media_publish, um einen Carousel-Container (Carousel-Post) zu veröffentlichen. Pro Konto können innerhalb von 24 Stunden maximal 50 Beiträge veröffentlicht werden. Ein Carousel gilt dabei als einzelner Beitrag.

POST /{ig-user-id}/media_publish

Parameter

Die folgenden Parameter sind erforderlich.

creation_id: Die Carousel-Container-ID.

Wenn der Vorgang erfolgreich ist, gibt die API eine IG-Medien-ID für ein Carousel-Album zurück.

Beispielanfrage

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."

Beispielantwort

{
  "id": "90010778390276"
}

Reels-Beiträge

Reels sind kurze Videos, die für die Anzeige auf dem Tab Reels in der Instagram-App berechtigt sind, sofern sie bestimmte Anforderungen erfüllen und von unserem Algorithmus ausgewählt werden. Befolge für das Veröffentlichen eines Reels die Schritte für das Veröffentlichen eines einzelnen Medienbeitrags und beziehe den media_type=REELS-Parameter zusammen mit dem Pfad zum Video ein, indem du den video_url-Parameter verwendest.

Reels sind kein neuer Medientyp, auch wenn du beim Veröffentlichen eines Reels media_type=REELS festlegst. Wenn du ein Reel veröffentlichst und dann sein media_type-Feld abfragst, ist der zurückgegebene Wert VIDEO. Um festzustellen, ob ein veröffentlichtes Video als Reel designiert wurde, frage stattdessen sein media_product_type-Feld ab.

Mit dem Codebeispiel auf GitHub (insta_reels_publishing_api_sample) kannst du lernen, wie du Reels auf Instagram veröffentlichst.

Als Erleichterung für Entwickler*innen hat Meta eine Sammlung aller Aufrufe an die Graph API Instagram Reels auf der Postman API-Plattform veröffentlicht. Weitere Informationen findest du unter Postman-Sammlungen für Facebook Reels und Instagram Reels.

Weitere Informationen zu Reels findest du in der Reels-Entwicklungsdokumentation.

Story-Beiträge

Aktuell können nur Business-Konten Stories mit der Content Publishing API veröffentlichen.

Stories sind Videos und Bilder, die als IG-Stories auf Instagram verfasst werden. Befolge für das Veröffentlichen einer Story dieselben Schritte wie für das Veröffentlichen eines einzelnen Medienbeitrags und beziehe den media_type=STORIES-Parameter zusammen mit dem Pfad zum Bild bzw. Video ein, indem du den image_url- oder video_url-Parameter verwendest.

Hinweis: Stories stellen keinen neuen Medientyp dar, auch wenn du beim Veröffentlichen einer Story media_type=STORIES festlegst. Wenn du ein Reel veröffentlichst und dann sein media_type-Feld abfragst, wird der Wert IMAGE/VIDEO zurückgegeben. Um festzustellen, ob ein veröffentlichtes Bild/Video als Story designiert wurde, frage stattdessen sein media_product_type-Feld ab.

Collaborator-Markierung

Du kannst öffentliche Instagram-Nutzer*innen in einem Bild, Carousel und Reel also Collaborator hinzufügen und sie erhalten eine Einladung, als Collaborator an diesem bestimmten Medium mitzuwirken. Um Nutzer*innen in einem Bild zu markieren, befolge die obigen Schritte zu Einzelmedien-Posts. Wenn du allerdings den Mediencontainer erstellst, schließe den collaborators-Parameter und ein Array von Strings ein, die die Instagram-Benutzer*innennamen der Nutzer*innen angeben, die du als Collaborator für das Medium einladen möchtest.

Beispielanfrage

POST graph.facebook.com/17841400008460056/media
?image_url=https://www.example.com/images/bronzed-fonzes.jpg
&caption=#BronzedFonzes!
&collaborators= [‘username1’,’username2’]

Hinweise

Der Wert „collaborators“ muss ein Array von Strings sein.
Du kannst nur Nutzer*innen mit öffentlichen Instagram-Konten markieren.
Maximal drei Collaborator können zu einem Medium hinzugefügt werden.
Collaborator können nicht zu Story-Medien hinzugefügt werden.

Standort-Markierungen

Du kannst die Pages Search API verwenden. Stelle sicher, dass du das Feld „location“ in deine Abfrage einbeziehst, um nach Seiten zu suchen, deren Name mit einem String übereinstimmt. Analysiere dann die Ergebnisse, um Seiten zu identifizieren, die für einen physischen Standort erstellt wurden. Wenn du beim Veröffentlichen eines Bilds oder Videos die ID einer Seite einschließt, wird das Element mit dem Standort markiert, der dieser Seite zugeordnet ist.

Einschränkungen

Damit eine Seite markiert werden kann, muss sie Standortdaten mit Breiten- und Längengraden aufweisen.

Stelle sicher, dass die gewünschte Seite Längen- und Breitengraddaten in der Antwort enthält. Wenn du versuchst, einen Container mit einer Seite zu erstellen, für die keine Standortdaten vorhanden sind, schlägt der Vorgang mit der codierten Ausnahme INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID fehl.

Weise die Seiten-ID beim Veröffentlichen von Einzelmedien- oder Carousel-Element-Containern dem Parameter location_id zu.

Produktmarkierungen

Du kannst sowohl einzelne Medien- als auch Carousel-Beiträge veröffentlichen, die mit Produkten von Instagram Shopping markiert sind. Informationen zur Vorgehensweise findest du im Leitfaden für Produktmarkierungen.

Nutzer*innenmarkierungen

Du kannst öffentliche Instagram-Nutzer in einem Bild markieren. Sie erhalten dann eine Benachrichtigung, dass sie markiert wurden.

Um Nutzer*innen in einem Bild zu markieren, befolge die obigen Schritte zu Einzelmedien-Posts. Wenn du allerdings den Mediencontainer erstellst, schließe den user_tags-Parameter und ein Array von Objekten ein, mit denen die Instagram-Nutzer*innen im Bild und ihre x/y-Koordinaten im Bild selbst angegeben werden.

Beispielanfrage

POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &user_tags= [ { username:'kevinhart4real', x: 0.5, y: 0.8 }, { username:'therock', x: 0.3, y: 0.2 } ]

Damit erhältst du eine Container-ID, die du dann mit dem Endpunkt IG-Nutzermedienveröffentlichung veröffentlichst.

Hinweise

Der user_tags-Wert muss ein Array von Objekten sein, die mit JSON formatiert sind.
Du kannst nur Nutzer mit öffentlichen Instagram-Konten markieren.
Das Objekt muss für jede*n Nutzer*in alle drei Eigenschaften (username, x und y) enthalten.
Die x- und y-Werte müssen float-Zahlen mit Ursprung in der oberen linken Ecke des Bilds sein und im Bereich zwischen 0.0 und 1.0 liegen.
Nutzer*innenmarkierungen können mit Bildern in Carousels verwendet werden.

Problembehebung

Wenn du einen Container für ein Video erstellen kannst, der POST /{ig-user-id}/media_publish-Endpunkt die veröffentlichte Medien-ID aber nicht zurückgibt, kannst du den Veröffentlichungsstatus des Containers durch eine Abfrage des GET /{ig-container-id}?fields=status_code-Endpunkts abrufen. Dieser Endpunkt gibt einen der folgenden Werte zurück:

EXPIRED: Der Container wurde innerhalb von 24 Stunden nicht veröffentlicht und ist abgelaufen.
ERROR: Der Container konnte den Veröffentlichungsprozess nicht abschließen.
FINISHED: Der Container und sein Medienobjekt sind für die Veröffentlichung bereit.
IN_PROGRESS: Der Container befindet sich noch im Veröffentlichungsprozess.
PUBLISHED: Das Medienobjekt des Containers wurde veröffentlicht.

Wir empfehlen, den Status eines Containers maximal fünf Minuten lang einmal pro Minute abzufragen.

Fehler

Weitere Informationen findest du in den Referenzen zu Fehlercodes.