Instagram oEmbed

Du kannst den oEmbed-Endpunkt von Instagram abfragen, um den HTML-Einbettungscode und grundlegende Metadaten eines Instagram-Beitrags zu erhalten und den Beitrag auf einer anderen Website oder in einer anderen App anzuzeigen. Das Posten von Fotos, Videos, Reels und Guides wird unterstützt.

Häufige Anwendungsfälle

Rendern von Beiträgen in Messaging-Apps
Einbetten von Beiträgen in Websites und Blogs
Rendern von Beiträgen in einem Content-Management-System

Endpunkte

Endpunkt	Beschreibung
`GET /instagram_oembed`	Den HTML-Einbettungscode und grundlegende Metadaten eines Instagram-Beitrags abrufen

Anforderungen

Einschränkungen

Der oEmbed-Endpunkt von Instagram ist nur dazu gedacht, um Instagram-Inhalte in Websites und Apps einzubetten. Er darf nicht für andere Zwecke verwendet werden. Es ist strengstens untersagt, Metadaten und Seiten-, Beitrags- oder Videoinhalte (oder deren Ableitungen) vom Endpunkt für andere Zwecke zu verwenden, als eine Frontend-Ansicht der Seite, des Beitrags oder des Videos bereitzustellen. Dieses Verbot umfasst das Verwenden, Bearbeiten, Extrahieren oder die dauerhafte Speicherung der Metadaten und Inhalte, insbesondere das Ableiten von Informationen über Seiten, Beiträge und Videos aus den Metadaten zu Analysezwecken.
Beiträge in privaten, inaktiven und altersbeschränkten Instagram-Konten werden nicht unterstützt.
Konten mit deaktivierten Einbettungen werden nicht unterstützt.
Stories werden nicht unterstützt.
Shadow DOM wird nicht unterstützt.

App-Review

Um oEmbed nutzen zu können, muss deine App einer App-Review für das Feature oEmbed Read unterzogen werden.

Verwende für das Formularfeld zum Bereitstellen einer URL, unter der wir oEmbed Read testen können, den Instagram oEmbed-Endpunkt, um den HTML-Einbettungscode für alle öffentlichen Beiträge auf unserer offiziellen Facebook-Seite oder Instagram-Seite abzurufen (oder rufe den HTML-Einbettungscode für eine der Seiten selbst ab). Füge den zurückgegebenen HTML-Einbettungscode deiner eigenen Seite hinzu, auf der du oEmbed-Inhalt anzeigen möchtest und gib die URL dieser Seite in das Formularfeld ein.

Sobald du eine Genehmigung für das Feature oEmbed Read erhalten hast, kannst du deine eigenen Seiten, Posts oder Videos einbetten, indem du die entsprechenden URLs verwendest.

Zugriffsschlüssel

Für den oEmbed-Endpunkt von Instagram wird entweder ein App-Zugriffsschlüssel (empfohlen) oder ein Client-Zugriffsschlüssel benötigt.

App-Zugriffsschlüssel

Wenn deine App einen Backend-Server verwendet, empfehlen wir, beim Zugriff auf den oEmbed-Endpunkt einen App-Zugriffsschlüssel zu verwenden. Ratenbegrenzungen hängen von der Art des Zugriffsschlüssels ab, der in der Anfrage enthalten ist, und Ratenbegrenzungen für App-Zugriffsschlüssel erlauben bis zu 5 Millionen Anfragen pro Tag.

Eine Anleitung zur Generierung von App-Zugriffsschlüsseln findest du in unserer Dokumentation „Zugriffsschlüssel“ im Abschnitt „App-Zugriffsschlüssel“.

Beachte bitte, dass App-Zugriffsschlüssel niemals clientseitig verwendet werden sollen. Sie sollten immer sicher aufbewahrt und auf deinem Server gespeichert werden. Wenn deine App einen Zugriffsschlüssel clientseitig verwenden muss, verwende stattdessen einen Client-Zugriffsschlüssel.

Client-Zugriffsschlüssel

Wenn deine App über einen Nutzeragenten wie ein Mobilgerät oder einen Webbrowser auf den oEmbed-Endpunkt zugreifen muss, muss deine App einen Client-Zugriffsschlüssel verwenden und unterliegt Ratenbegrenzungen für Client-Zugriffsschlüssel.

Um einen Client-Zugriffsschlüssel zu erhalten, melde dich bei deinem App-Dashboard an und navigiere zu Einstellungen > Erweitert > Sicherheit > Client Token.

Im Gegensatz zu App-Zugriffsschlüsseln können Client-Zugriffsschlüssel nicht allein in oEmbed-Endpunktanfragen verwendet werden. Sie müssen mit deiner App-ID kombiniert werden. Hänge dazu deinen Zugriffsschlüssel an das Ende deiner App-ID an, getrennt durch einen Senkrechtstrich (|):

{app-id}|{client-token}

Zum Beispiel:

access_token=1234|5678

Durchsatzratenbegrenzungen

Ratenbegrenzungen hängen von der Art des Zugriffsschlüssels ab, den deine App in der jeweiligen Anfrage enthält.

Ratenbegrenzungen für App-Zugriffschlüssel

Apps, die App-Zugriffsschlüssel verwenden, können innerhalb von 24 Stunden bis zu 5 Millionen Anfragen durchführen.

Ratenbegrenzungen für Client-Zugriffsschlüssel

Ratenbegrenzungen für Client-Zugriffsschlüssel sind erheblich niedriger als Ratenbegrenzungen für App-Zugriffschlüssel. Wir geben die tatsächliche Grenze nicht an, da sie sich je nach deinen App-Aktivitäten ändert. Du kannst jedoch davon ausgehen, dass deine App die Grenze nur dann erreicht, wenn sie sich wie ein Bot verhält und etwa Tausende von Anfragen im Batch sendet oder Tausende von Anfragen pro Agent oder App-Nutzer sendet.

Abrufen des HTML-Einbettungscodes

Um den HTML-Einbettungscode eines Instagram-Beitrags abzurufen, sende eine Anfrage an:

GET /instagram_oembed?url={url}&access_token={access-token}

Ersetze {url} durch die URL des Instagram-Beitrags, den du abfragen möchtest, und {access-token} durch deinen App- oder Client-Zugriffsschlüssel (oder übergib ihn in einem HTTP-Header an uns). Wenn du einen Client-Zugriffsschlüssel verwendest, denke daran, ihn unter Verwendung eines Senkrechtstrichs mit deiner App-ID zu kombinieren. Ansonsten schlägt die Anfrage fehl.

Ist die Anfrage erfolgreich, antwortet die API mit einem JSON-Objekt, das den HTML-Einbettungscode des Beitrags und zusätzliche Daten enthält. Der HTML-Einbettungscode wird der Eigenschaft html zugewiesen.

In der Referenz zu oEmbed von Instagram findest du eine Liste der Abfrage-String-Parameter, die du einschließen kannst, um die Abfrage zu erweitern. Du kannst auch den Abfrage-String-Parameter fields einschließen, um anzugeben, welche Felder zurückgegeben werden sollen. Wird keine Angabe gemacht, sind in der Antwort alle Standardfelder enthalten.

Beispielanfrage

curl -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."

Beispielantwort

Einige Werte sind zur besseren Lesbarkeit mit Auslassungszeichen (...) abgeschnitten.

{
  "version": "1.0",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/",
  "type": "rich",
  "width": 658,
  "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...",
  "thumbnail_width": 640,
  "thumbnail_height": 640
}

URL-Formate

Der Abfrage-String-Parameter url akzeptiert die folgenden URL-Formate:

https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/https://www.instagram.com/{username}/guide/{slug}/{guide_id}

Embed-JS-Code

Der HTML-Einbettungscode enthält eine Referenz zur JavaScript-Bibliothek embed.js von Instagram. Wenn die Bibliothek geladen wird, scannt sie die Seite nach dem Beitrags-HTML-Code und generiert den vollständig gerenderten Beitrag. Wenn du die Bibliothek separat laden möchtest, schließe den Abfrage-String-Parameter omitscript=true in deine Abfrage ein. Um den HTML-Einbettungscode manuell zu initialisieren, rufe die Funktion instgrm.Embeds.process() auf, nachdem die Bibliothek geladen wurde.

Beitragsgröße

Der eingebettete Beitrag ist responsiv und wird an die Größe des Containers angepasst. Das bedeutet, dass die Höhe je nach Containerbreite und Länge der Bildunterschrift variiert. Du kannst die maximale Breite festlegen, indem du den Abfrage-String-Parameter maxwidth in deine Abfrage einschließt.

Abrufen von Miniaturbildern

Wir empfehlen dir, nach Möglichkeit den gesamten HTML-Einbettungscode des Beitrags zu rendern. Wenn dir das nicht möglich ist, kannst du die URL des Miniaturbilds eines Beitrags abrufen und stattdessen dieses rendern. Wenn du das tust, musst du aber neben dem Bild eine klare Attribution angeben. Dazu zählen eine Attribution des ursprünglichen Autors und von Instagram sowie ein Link zum Instagram-Beitrag, den du abfragst.

Um die URL des Miniaturbilds und die Attributionsinformationen eines Beitrags abzurufen, sende eine Anfrage an:

GET /instagram_oembed
  ?url={url}
  &maxwidth={maxwidth}
  &fields=thumbnail_url,author_name,provider_name,provider_url
  &access_token={access-token}

Ersetze {url} durch die URL des Instagram-Beitrags, den du abfragen möchtest, {maxwidth} durch die maximale Größe des Miniaturbilds, das du rendern möchtest, und {access-token} durch deinen App- oder Client-Zugriffsschlüssel.

Beispielanfrage

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."

Beispielantwort

Einige Werte sind zur besseren Lesbarkeit mit Auslassungszeichen (...) abgeschnitten.

{
  "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/"
}

Übergeben von Zugriffsschlüsseln in einem Header

Wenn du deinen Zugriffsschlüssel nicht in den Abfrage-String deiner Anfrage einschließen möchtest, kannst du ihn stattdessen über einen Authorization-HTTP-Header an uns übergeben.

Authorization: Bearer {access-token}

Zum Beispiel:

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN" \
  --header "Authorization: Bearer 96481..."