Video API

Facebook Stories API dari Meta

Dokumen ini menunjukkan kepada Anda cara menggunakan Facebook Stories API untuk menerbitkan Cerita di Halaman Facebook.

Untuk menerbitkan cerita, aplikasi Anda akan melakukan langkah-langkah berikut:

  1. Mengunggah media pengguna aplikasi Anda ke server Meta
  2. Menerbitkan media ke Halaman pengguna aplikasi Anda sebagai Cerita

Sebelum memulai

Panduan ini berasumsi Anda telah membaca Ringkasan Pages API dan menerapkan komponen yang dibutuhkan, dan berhasil menyelesaikan Panduan Memulai.

  • Anda perlu menerapkan Facebook Login atau Facebook Login for Business untuk meminta izin yang diperlukan dari pengguna aplikasi Anda untuk mengakses Halaman Facebook mereka dan untuk menerima token akses Halaman.
  • Pengguna aplikasi Anda harus dapat melakukan tugas CREATE_CONTENT pada Halaman yang diwakili dalam token akses Halaman dan memberi aplikasi Anda izin berikut:
    • pages_manage_posts
    • pages_read_engagement
    • pages_show_list

Jika Anda menggunakan pengguna sistem bisnis dalam permintaan API Anda, izin business_management juga diperlukan.

Persyaratan media

Anda harus menyediakan foto atau video yang sesuai dengan spesifikasi berikut.

Spesifikasi foto

PropertiSpesifikasi

Jenis file

.jpeg, .bmp, .png, .gif, .tiff

Ukuran file

File tidak boleh melebihi 4MB. Untuk file .png, kami rekomendasikan tidak melebihi 1MB atau gambar mungkin tampak berpiksel.

Spesifikasi video

PropertiSpesifikasi

Jenis File

.mp4 (direkomendasikan)

Rasio Aspek

9 x 16

Resolusi

1080 x 1920 pixel (direkomendasikan). Minimal 540 x 960 pixel

Laju Bingkai

24 hingga 60 bingkai per detik

Durasi

3 sampai 90 detik.

Reel yang diterbitkan sebagai cerita di Halaman Facebook tidak boleh melebihi 60 detik.

Pengaturan Video

  • Chroma subsampling: 4:2:0
  • GOP Tertutup (2—5 detik)
  • Kompresi – H.264, H.265 (VP9, AV1 juga didukung)
  • Laju bingkai tetap
  • Pemindaian progresif

Pengaturan Audio

  • Bitrate audio – 128kbs+
  • Saluran – Stereo
  • Codec – AAC Kompleksitas Rendah
  • Laju sampel – 48kHz

Batasan

  • Foto atau video yang diunggah untuk cerita tidak dapat digunakan dalam postingan yang diterbitkan sebelumnya
  • Cerita video tidak boleh melebihi 60 detik
  • Untuk memasukkan cerita yang diarsipkan di permintaan GET Anda guna melihat cerita, Anda harus mengaktifkan arsip cerita Facebook Anda

Praktik terbaik

Saat menguji panggilan API, Anda dapat menyertakan parameter access_token ke token akses Anda. Namun, saat melakukan panggilan aman dari aplikasi Anda, gunakan kelas token akses.

Contoh kode dalam dokumen ini diformat agar mudah dibaca. Ganti nilai yang dicetak tebal dan miring, seperti page_id, dengan nilai Anda.

Cerita video

Untuk menerbitkan cerita video di Halaman Facebook, mulai sesi unggah video dengan server Meta, unggah video ke server Meta, lalu terbitkan cerita video.

Langkah 1: Mulai sesi

Untuk memulai sesi unggah, kirim permintaan POST ke endpoint /page_id/video_stories, dengan page_id adalah ID Halaman Facebook Anda, dengan parameter upload_phase diatur ke start.

Contoh permintaan

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

Setelah berhasil, aplikasi Anda menerima tanggapan JSON dengan ID video dan URL Facebook tempat Anda akan mengunggah video.

Contoh tanggapan

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v25.0/video_id",
}

Langkah 2: Unggah video

Sekarang setelah Anda memulai sesi unggah dan menerima URL pengunggahan, Anda dapat mengunggah video Anda. Anda dapat mengunggah:

Mengunggah file yang di-hosting

Untuk mengunggah file yang di-hosting, kirim permintaan POST ke endpoint upload_url yang Anda terima di langkah inisialisasi dengan parameter berikut:

  • file_url diatur ke URL file video Anda

Pastikan host-nya adalah rupload.facebook.com.

API sekarang akan menolak file yang dihosting di situs yang membatasi akses melalui robots.txt. Developer perlu memastikan bahwa situs hosting mengizinkan agen pengguna “facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)” untuk mengambil file yang dihosting.

File yang dihosting di Meta CDN (contohnya, URL fbcdn) akan ditolak. Sebaliknya, developer dapat menggunakan fitur crossposting untuk menerbitkan video di beberapa halaman tanpa mengunggah video ke setiap halaman. Baca panduan terperinci kami tentang crossposting.

Contoh permintaan
curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

Mengunggah file lokal

Untuk mengunggah file yang lokal, kirim permintaan POST ke endpoint upload_url yang Anda terima di langkah inisialisasi dengan parameter berikut:

  • offset diatur ke 0
  • file_size diatur ke ukuran total dalam bita video yang sedang diunggah
Contoh permintaan
curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

Setelah berhasil mengunggah, aplikasi Anda akan menerima tanggapan JSON dengan success diatur ke true.

Contoh tanggapan unggahan
{
    "success": true
}

Unggahan terinterupsi

Jika unggahan video terinterupsi, Anda dapat memulai ulang unggahan atau melanjutkan unggahannya.

  • Untuk memulai ulang unggahan, kirim ulang permintaan POST dan atur offset ke 0.
  • Untuk melanjutkan unggahan, kirim ulang permintaan POST dengan offset diatur ke nilai bytes_transfered dari pemeriksaan status.

Dapatkan status unggahan

Untuk memeriksa status video Anda, selama unggahan atau penerbitan, kirim permintaan GET ke endpoint /video_id dengan parameter berikut:

  • fields diatur ke status
Contoh permintaan
curl -X GET "https://graph.facebook.com/v25.0/video_id" \
	-d "fields=status"

Setelah berhasil, aplikasi Anda menerima tanggapan JSON yang berisi:

  • Objek status yang berisi:
    • video_status dengan nilai ready, processing, expired, atau error
    • Objek uploading_phase dengan pasangan kode-nilai berikut:
      • status diatur ke in_progress, not_started, complete, atau error
      • bytes_transfered diatur ke bita yang telah diunggah. Dapat digunakan sebagai nilai offset jika unggahan terinterupsi.
    • Objek processing_phase dengan pasangan kode-nilai berikut:
      • status diatur ke in_progress, not_started, complete, atau error
    • Objek processing_phase dengan pasangan kode-nilai berikut:
      • status diatur ke in_progress, not_started, complete, atau error
      • publish_status diatur ke published atau not_published
      • publish_time diatur ke cap waktu UNIX dari waktu aktual atau waktu penerbitan
Contoh tanggapan
Tanggapan berikut menunjukkan file yang telah berhasil diunggah. 
{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}
Tanggapan berikut menunjukkan kesalahan telah terjadi pada tahap pemrosesan. 
{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

Langkah 3. Terbitkan cerita video

Untuk menerbitkan cerita video ke Halaman Anda, kirim permintaan POST ke endpoint /page_id/video_stories dengan parameter berikut:

  • video_id diatur ke ID video yang Anda unggah
  • upload_phase diatur ke finish

Contoh permintaan

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

Setelah berhasil, aplikasi Anda menerima tanggapan JSON yang berisi pasangan kode-nilai berikut:

  • success diatur ke true
  • post_id diatur ke ID postingan cerita Anda

Contoh tanggapan

{
  "success": true,
  "post_id": 1234
}

Cerita foto

Langkah 1. Unggah foto

Kunjungi Referensi Postingan Halaman untuk mempelajari cara mengunggah foto ke server Meta menggunakan endpoint /page_id/photos. Pastikan untuk menyertakan parameter published dan mengaturnya ke false.

Langkah 2. Terbitkan cerita foto

Untuk menerbitkan cerita foto ke Halaman Anda, kirim permintaan POST ke endpoint /page_id/photo_stories dengan parameter berikut:

  • photo_id diatur ke ID foto yang Anda unggah

Contoh permintaan

curl -X POST "https://graph.facebook.com/v25.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

Setelah berhasil, aplikasi Anda menerima tanggapan JSON yang berisi pasangan kode-nilai berikut:

  • success diatur ke true
  • post_id diatur ke ID postingan cerita Anda

Contoh tanggapan

{
  "success": true,
  "post_id": 1234
}

Mendapatkan cerita

Untuk mendapatkan daftar semua cerita untuk Halaman serta data tentang setiap cerita, kirim permintaan GET ke endpoint /page_id/stories di mana page_id adalah ID Halaman yang ingin Anda lihat.

Contoh permintaan

    
curl -i -X GET "https://graph.facebook.com/v25.0/page_id/stories"

Jika berhasil, aplikasi Anda menerima tanggapan JSON dengan array objek, setiap objeknya berisi informasi tentang cerita yang diterbitkan di Halaman. Setiap objek berisi pasangan kode-nilai berikut:

  • post_id diatur ke ID postingan cerita yang diterbitkan
  • status diatur ke PUBLISHED, ARCHIVED
  • creation_time diatur ke cap waktu UNIX saat cerita diterbitkan
  • media_type diatur ke video atau photo
  • media_id diatur ke ID video atau foto di postingan cerita
  • url diatur ke URL Facebook untuk postingan cerita, seperti https://facebook.com/stories/8283482737484972

Contoh Tanggapan

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

Anda dapat memfilter cerita berdasarkan status, diterbitkan atau diarsipkan, dan tanggal, menggunakan parameter since dan until.

Lihat juga

Pelajari selengkapnya tentang endpoint dan konsep yang dibahas dalam panduan ini.

Panduan yang relevan

Referensi endpoint