Penerbitan Konten

Anda dapat menggunakan Instagram Graph API untuk menerbitkan gambar, video, reel tunggal (yakni postingan media tunggal), atau postingan yang berisi banyak gambar dan video (postingan carousel) di akun Profesional Instagram.

Mulai 1 Juli 2023, semua video kabar tunggal yang diterbitkan melalui API Penerbitan Konten Instagram akan dibagikan sebagai reel.

Persyaratan

Token Akses

Semua permintaan harus menyertakan token akses Pengguna milik pengguna aplikasi.

Izin

Penerbitan bergantung pada kombinasi dari izin berikut. Kombinasi yang tepat bergantung pada endpoint yang digunakan aplikasi Anda. Baca referensi endpoint kami untuk menentukan izin apa yang diperlukan setiap endpoint.

Jika aplikasi Anda akan digunakan oleh pengguna aplikasi yang tidak memiliki peran di aplikasi Anda atau peran di Bisnis yang telah mengeklaim aplikasi, Anda harus meminta persetujuan untuk setiap izin melalui Tinjauan Aplikasi sebelum pengguna nonperan dapat memberikannya ke aplikasi Anda.

Server Publik

Kami melakukan cURL media yang digunakan dalam upaya penerbitan sehingga media harus di-hosting di server yang dapat diakses publik pada saat upaya tersebut.

Otorisasi Penerbitan Halaman

Akun Profesional Instagram yang terhubung ke Halaman yang mewajibkan Otorisasi Penerbitan Halaman (PPA) tidak dapat diterbitkan hingga PPA selesai.

Ada kemungkinan bahwa pengguna aplikasi dapat melakukan Tugas di Halaman yang awalnya tidak memerlukan PPA, tetapi kemudian membutuhkannya. Dalam skenario ini, pengguna aplikasi tidak akan dapat menerbitkan konten ke akun Profesional Instagram mereka sampai menyelesaikan PPA. Karena tidak ada cara bagi Anda untuk menentukan apakah Halaman pengguna aplikasi memerlukan PPA, kami rekomendasikan Anda menyarankan pengguna aplikasi untuk menyelesaikan PPA terlebih dahulu.

Batasan

  • JPEG adalah satu-satunya format gambar yang didukung. Format JPEG yang diperluas seperti MPO dan JPS tidak didukung.
  • Tanda belanja tidak didukung.
  • Tanda konten bermerek tidak didukung.
  • Filter tidak didukung.
  • Menerbitkan ke Instagram TV tidak didukung.

Untuk batasan tambahan, lihat referensi masing-masing endpoint.

Batas Laju

Akun Instagram dibatasi hingga 50 postingan yang diterbitkan API dalam periode bergerak 24 jam. Carousel dihitung sebagai satu postingan tunggal. Batas ini diterapkan pada endpoint POST /{ig-user-id}/media_publish saat mencoba untuk menerbitkan kontainer media. Kami rekomendasikan agar aplikasi Anda juga menerapkan batas laju penerbitan, terutama jika aplikasi Anda mengizinkan pengguna aplikasi untuk menjadwalkan postingan untuk diterbitkan di masa mendatang.

Untuk memeriksa penggunaan batas laju akun Profesional Instagram saat ini, kuerilah endpoint GET /{ig-user-id}/content_publishing_limit.

Endpoint

API terdiri dari endpoint berikut. Baca setiap dokumen referensi endpoint untuk persyaratan penggunaan.

Postingan Media Tunggal

Menerbitkan gambar, video, cerita atau reel tunggal adalah proses dua langkah:

  1. Gunakan endpoint POST /{ig-user-id}/media untuk membuat kontainer dari gambar atau video yang di-hosting di server publik Anda.
  2. Gunakan endpoint POST /{ig-user-id}/media_publish untuk menerbitkan kontainer.

Langkah 1 dari 2: Buat Kontainer

Seandainya Anda memiliki gambar di...

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

... yang ingin Anda terbitkan dengan tagar "#BronzFonz" sebagai keterangannya. Kirim permintaan ke endpoint POST /{ig-user-id}/media:

Contoh Permintaan

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

Ini memberikan ID kontainer gambar.

Contoh Tanggapan

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

Langkah 2 dari 2: Terbitkan Kontainer

Gunakan endpoint POST /{ig-user-id}/media_publish untuk menerbitkan ID kontainer yang diberikan pada langkah sebelumnya.

Contoh Permintaan

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

Contoh Tanggapan

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

Postingan Carousel

Anda dapat menerbitkan hingga 10 gambar, video, atau campuran keduanya dalam satu postingan (satu postingan carousel). Menerbitkan carousel adalah proses tiga langkah:

  1. Gunakan endpoint POST /{ig-user-id}/media untuk membuat kontainer item individual untuk setiap gambar dan video yang akan muncul di carousel.
  2. Gunakan endpoint POST /{ig-user-id}/media lagi untuk membuat kontainer carousel tunggal untuk item.
  3. Gunakan endpoint POST /{ig-user-id}/media_publish untuk menerbitkan kontainer carousel.

Postingan carousel dihitung sebagai satu postingan tunggal terhadap batas laju akun.

Batasan

  • Carousel tidak dapat dipromosikan.
  • Batas carousel adalah 10 gambar, video, atau campuran keduanya.
  • Semua gambar carousel dipotong berdasarkan gambar pertama di carousel, dengan rasio aspek default 1:1.

Langkah 1 dari 3: Buat kontainer item

Gunakan endpoint POST /{ig-user-id}/media untuk membuat kontainer item bagi gambar dan video yang akan tampil di carousel. Carousel dapat berisi hingga total 10 gambar, video, atau campuran keduanya.

POST /{ig-user-id}/media

Parameter

Parameter berikut diperlukan. Buka referensi endpoint POST /{ig-user-id}/media untuk parameter tambahan yang didukung.

  • is_carousel_item — Atur ke true. Menandakan gambar atau video yang akan muncul di carousel.
  • image_url — (hanya gambar) Jalur ke gambar. Kami akan melakukan cURL video Anda menggunakan URL yang diteruskan, jadi foto harus berada di server publik.
  • media_type — (hanya video) Atur ke VIDEO. Menandakan bahwa media adalah video.
  • video_url — (hanya video) Jalur ke video. Kami akan melakukan cURL video Anda menggunakan URL yang diteruskan sehingga harus berada di server publik.

Jika operasi berhasil, API akan memberikan ID kontainer item yang dapat digunakan saat membuat kontainer carousel.

Ulangi proses ini untuk setiap gambar atau video yang akan muncul di carousel.

Contoh Permintaan

curl -i -X POST \

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

Contoh Tanggapan

{
  "id": "17899506308402767"
}

Langkah 2 dari 3: Buat kontainer carousel

Gunakan endpoint POST /{ig-user-id}/media untuk membuat kontainer carousel.

POST /{ig-user-id}/media

Parameter

Parameter berikut diperlukan. Buka referensi endpoint POST /{ig-user-id}/media untuk parameter tambahan yang didukung.

  • media_type — Atur ke CAROUSEL. Menandai bahwa kontainer adalah untuk carousel.
  • children — Array berisi hingga 10 ID kontainer dari setiap gambar dan video yang akan muncul di carousel yang diterbitkan. Carousel dapat berisi hingga total 10 gambar, video, atau campuran keduanya.

Contoh Permintaan

curl -i -X POST \

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

Contoh Tanggapan

{
  "id": "18000748627392977"
}

Langkah 3 dari 3: Terbitkan kontainer carousel

Gunakan endpoint POST /{ig-user-id}/media_publish untuk menerbitkan kontainer carousel (postingan carousel). Akun dibatasi hingga 50 postingan yang diterbitkan API dalam periode 24 jam. Menerbitkan carousel dihitung sebagai postingan tunggal.

POST /{ig-user-id}/media_publish

Parameter

Parameter berikut diperlukan.

  • creation_id — ID kontainer carousel.

Jika operasi berhasil, API akan menampilkan ID Media Instagram album carousel.

Contoh Permintaan

curl -i -X POST \

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

Contoh Tanggapan

{
  "id": "90010778390276"
}

Postingan Reels

Reels hanyalah video bentuk pendek yang memenuhi syarat untuk muncul di tab Reels di aplikasi Instagram jika memenuhi spesifikasi tertentu dan dipilih oleh algoritma kami. Untuk menerbitkan reel, ikuti langkah-langkah yang sama untuk menerbitkan postingan media tunggal dan sertakan parameter media_type=REELS bersama dengan jalur ke video menggunakan parameter video_url.

Reels bukan jenis media baru, meskipun Anda mengatur media_type=REELS saat Anda menerbitkan reel. Jika Anda menerbitkan reel, lalu meminta kolom media_type, nilai yang diberikan adalah VIDEO. Untuk menentukan apakah video yang diterbitkan telah ditetapkan sebagai reel, minta kolom media_product_type dari video tersebut.

Anda dapat menggunakan contoh kode di GitHub (insta_reels_publishing_api_sample) untuk mempelajari cara menerbitkan Reel ke Instagram.

Untuk memudahkan developer, Meta telah menerbitkan set lengkap panggilan Graph API untuk Instagram Reels di Platform Postman API. Untuk informasi selengkapnya, lihat Koleksi Postman untuk Facebook Reels dan Instagram Reels.

Untuk informasi selengkapnya tentang Reels, lihat Dokumentasi Developer Reels.

Postingan Cerita

Hanya akun bisnis yang dapat menerbitkan cerita dengan API Penerbitan Konten saat ini.

Cerita adalah video dan gambar yang diposting sebagai Instagram Stories di Instagram. Untuk menerbitkan cerita, ikuti langkah-langkah yang sama untuk menerbitkan postingan media tunggal dan sertakan parameter media_type=STORIES bersama dengan jalur ke gambar/video menggunakan parameter image_url atau video_url.

Catatan: Cerita bukanlah jenis media baru, meskipun Anda menetapkan media_type=STORIES saat menerbitkan cerita. Jika Anda menerbitkan cerita, lalu meminta kolom media_type, nilainya akan diberikan sebagai IMAGE/VIDEO. Untuk mengetahui apakah gambar/video yang diterbitkan ditetapkan sebagai cerita, minta kolom media_product_type dari video tersebut.

Protokol Unggahan yang Dapat Dilanjutkan

Protokol unggahan yang dapat dilanjutkan adalah alur baru untuk penerbitan konten Instagram yang mendukung unggahan video untuk Reel, Cerita Video, dan Produk Carousel Video media_types.

Protokol baru ini mendukung pembuatan media Instagram dari video lokal dan video url yang dihosting publik. Protokol ini memungkinkan Anda melanjutkan operasi pengunggahan file lokal setelah gangguan jaringan atau kegagalan transmisi lainnya, sehingga menghemat waktu dan bandwidth jika terjadi kegagalan jaringan. Protokol ini mempertahankan spesifikasi media yang sama.

Endpoint

  • POST https://graph.facebook.com/{api-version}/{ig-user-id}/media — Inisialisasi kontainer pembuatan video dengan mengatur upload_type=resumable.
  • POST https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id} — Unggah video dari file video lokal atau URL yang dihosting secara lebih andal dengan menggunakan protokol unggahan yang dapat dilanjutkan.
  • POST https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish — Terbitkan media yang diunggah menggunakan kontainer media mereka.
  • GET /{ig-container-id}?fields=status_code — Periksa kelayakan dan status penerbitan kontainer media.

Petunjuk pengodean URL HTML

  • Sebagian parameter didukung dalam format daftar/kamus.
  • Beberapa karakter perlu dienkode ke dalam format yang dapat ditransmisikan melalui Internet. Sebagai contoh: user_tags=[{username:’ig_user_name’}] dienkode ke user_tags=%5B%7Busername:ig_user_name%7D%5D di mana [ dienkode menjadi %5B dan { dienkode menjadi %7B. Untuk konversi selengkapnya, silakan lihat standar Enkode URL HTML.

Langkah 1: Mulai Sesi Unggahan untuk Reels, Cerita Video, atau Produk Carousel

Permintaan Contoh Reels

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=REELS" \
    -d "upload_type=resumable" \
    -d "caption={caption}"\
    -d "collaborators={collaborators-username}"
    -d "cover_url={cover-url}" \
    -d "audio_name={audio-name}" \
    -d "user_tags={user-tags}" \
    -d "location_id={location-id}" \
    -d "thumb_offset={thumb-offset}" \
    -H "Authorization: OAuth {access-token}"

Permintaan Contoh Cerita Video

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=STORIES" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Permintaan Contoh Produk Video Carousel

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=VIDEO" \
    -d "is_carousel_item=true" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Contoh Tanggapan

{
   "id": "{ig-container-id}",
   "uri": "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}"
}

Langkah 2: Unggah Video menggunakan Protokol Unggahan yang Dapat Dilanjutkan

Sebagian besar panggilan Graph API menggunakan hosting graph.facebook.com. Namun, panggilan untuk mengunggah video untuk Reels menggunakan rupload.facebook.com.

Sumber file berikut ini didukung untuk file video yang diunggah:

  • File yang ada di komputer Anda
  • File yang di-hosting di server yang dapat digunakan oleh publik, seperti CDN

Contoh permintaan mengunggah file video lokal

Dengan ig-container-id yang dikembalikan dari panggilan sesi pengunggahan yang dapat dilanjutkan, unggah video tersebut.

  • Pastikan host-nya adalah rupload.facebook.com.
  • Semua media_type memiliki alur yang sama untuk mengunggah video.
  • ig-container-id adalah ID yang dikembalikan dari panggilan sesi pengunggahan yang dapat dilanjutkan.
  • access-token sama dengan yang digunakan pada langkah sebelumnya.
  • offset diatur ke byte pertama yang diunggah, umumnya 0.
  • file_size diatur ke ukuran file Anda dalam byte.
  • Your_file_local_path diatur ke jalur file dari file lokal Anda, misalnya, jika mengunggah file dari, folder Downloads di macOS, jalurnya adalah @Downloads/example.mov.
curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

Contoh permintaan mengunggah video yang di-hosting publik

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "file_url: https://example_hosted_video.com"

Contoh Tanggapan

// Success Response Message
{
  "success":true,
  "message":"Upload successful."
}

// Failure Response Message
{
  "debug_info":{
    "retriable":false,
    "type":"ProcessingFailedError",
    "message":"{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

Langkah 3: (Hanya Carousel) Buat Kontainer Carousel

Anda dapat menggunakan kembali langkah 1 dan 2 untuk membuat beberapa ig-container-ids dengan parameter is_carousel_item yang diatur ke true. Kemudian, buat Kontainer Carousel untuk memasukkan semua produk carousel. Produk carousel dapat dicampur dengan Gambar dan Video.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=CAROUSEL" \
    -d "caption={caption}"\
    -d "collaborators={collaborator-usernames}" \
    -d "location_id={location-id}" \
    -d "product_tags={product-tags}" \
    -d "children=[{ig-container-id},{ig-container-id}...]" \
    -H "Authorization: OAuth {access-token}"

Langkah 4: Terbitkan Media

Untuk Reels dan Cerita Video, {ig-container-id} yang dibuat pada langkah 1 digunakan untuk menerbitkan Video, dan untuk Kontainer Carousel, {ig-container-id} yang dibuat pada langkah 3 digunakan untuk menerbitkan Kontainer Carousel.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish" \
    -d "creation_id={ig-container-id}" \
    -H "Authorization: OAuth {access-token}"

Langkah 5: Dapatkan Status Media

graph.facebook.com menyediakan endpoint GET untuk membaca status unggahan, kolom video_status berisi detail tentang proses pengunggahan lokal.

  • uploading_phase memberitahukan apakah file telah berhasil diunggah, dan berapa byte yang ditransfer.
  • processing_phase berisi detail tentang status pemrosesan video setelah file video diunggah.
// GET status from graph.facebook.com
curl -X GET "https://graph.facebook.com/v19.0/{ig-container-id}?fields=id,status,status_code,video_status" \
    -H "Authorization: OAuth {access-token}"

Contoh Tanggapan dari endpoint graph.facebook.com

// A successfully created ig container
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "complete",
      "bytes_transferred": 37006904
    },
    "processing_phase": {
      "status": "complete"
    }
  }
}

// An interrupted ig container creation, from here you can resume your upload in step 2 with offset=50002. 
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "in_progress",
      "bytes_transferred": 50002
    },
    "processing_phase": {
      "status": "not_started"
    }
  }
}

Tanda Kolaborator

Anda dapat menambahkan pengguna Instagram publik dalam gambar, carousel, dan reel sebagai kolaborator dan mereka akan menerima undangan untuk menjadi kolaborator untuk media tertentu. Untuk menandai pengguna dalam gambar, ikuti langkah-langkah Postingan Media Tunggal di atas, tetapi saat membuat kontainer media, sertakan parameter kolaborator dan array string yang menunjukkan nama pengguna Instagram dari pengguna yang ingin Anda undang sebagai kolaborator di media.

Contoh Permintaan

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

Catatan

  • Nilai kolaborator harus berupa array string.
  • Anda hanya dapat menandai pengguna dengan akun Instagram publik.
  • Maksimal 3 kolaborator dapat ditambahkan ke media.
  • Kolaborator tidak dapat ditambahkan ke media Cerita.

Tanda Lokasi

Anda dapat menggunakan Pages Search API , pastikan untuk memasukkan kolom `lokasi` dalam kueri Anda, untuk mencari Halaman yang namanya cocok dengan string pencarian. Kemudian, parsing hasil untuk mengidentifikasi Halaman yang telah dibuat untuk lokasi fisik. Jika Anda menyertakan ID Halaman saat menerbitkan gambar atau video, ID Halaman akan ditandai dengan lokasi yang terkait dengan Halaman tersebut.

Batasan

Agar memenuhi syarat untuk pemberian tanda, Halaman harus memiliki data lokasi garis lintang dan bujur.

Verifikasi bahwa Halaman yang ingin Anda gunakan memiliki data garis lintang dan garis bujur dalam tanggapannya. Mencoba membuat kontainer menggunakan Halaman yang tidak memiliki data lokasi akan gagal dengan pengecualian berkode INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID.

Setelah Anda memiliki ID Halaman, tetapkan ID itu ke parameter location_id saat menerbitkan kontainer item media tunggal atau carousel.

Label Produk

Anda dapat menerbitkan postingan media tunggal dan postingan carousel yang ditandai dengan produk Instagram Shop. Baca panduan Pelabelan Produk untuk mempelajari caranya.

Tanda Pengguna

Anda dapat menandai pengguna Instagram publik di sebuah gambar dan mereka akan menerima notifikasi saat pengguna tersebut ditandai.

Untuk menandai pengguna di sebuah gambar, ikuti langkah Postingan Media Tunggal di atas, tetapi saat membuat kontainer media, sertakan parameter user_tags dan array objek yang menunjukkan pengguna Instagram pada gambar serta koordinat x/y dalam gambar itu sendiri.

Contoh Permintaan

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 } ] 

Ini akan memberikan ID kontainer yang nantinya Anda terbitkan menggunakan endpoint Terbitkan Media Pengguna Instagram.

Catatan

  • Nilai user_tags harus berupa array objek yang diformat dengan JSON.
  • Anda hanya dapat menandai pengguna dengan akun Instagram publik.
  • Objek harus berisi ketiga properti semuanya (username, x, dan y) untuk setiap pengguna.
  • Nilai x dan y harus angka float yang berasal dari kiri atas gambar, dengan rentang 0.01.0.
  • Tanda pengguna dapat digunakan dengan gambar dalam carousel.

Pemecahan Masalah

Jika Anda dapat membuat kontainer untuk video tetapi endpoint POST /{ig-user-id}/media_publish tidak menampilkan ID media yang diterbitkan, Anda bisa mendapatkan status penerbitan kontainer dengan meng-kueri endpoint GET /{ig-container-id}?fields=status_code. Endpoint ini akan menampilkan salah satu dari berikut ini:

  • EXPIRED — Kontainer tidak diterbitkan dalam 24 jam dan telah kedaluwarsa.
  • ERROR — Kontainer gagal menyelesaikan proses penerbitan.
  • FINISHED — Kontainer dan objek medianya siap diterbitkan.
  • IN_PROGRESS — Kontainer masih dalam proses penerbitan.
  • PUBLISHED — Objek media kontainer telah diterbitkan.

Kami merekomendasikan untuk menanyakan status kontainer sekali per menit, tidak lebih dari 5 menit.

Kesalahan

Lihat referensi Kode Kesalahan.