콘텐츠 게시

Instagram 그래프 API를 사용하여 Instagram 프로페셔널 계정에 단일 이미지, 동영상, 릴스(즉, 단일 미디어 게시물)를 게시하거나, 여러 이미지와 동영상을 포함하는 게시물(슬라이드 게시물)을 게시할 수 있습니다.

2023년 7월 1일부터 Instagram 콘텐츠 게시 API를 통해 게시된 모든 단일 피드 동영상은 릴스로 공유됩니다.

요구 사항

액세스 토큰

모든 요청에는 앱 사용자의 사용자 액세스 토큰을 포함해야 합니다.

권한

게시는 다음과 같은 권한을 조합해서 사용합니다. 정확한 조합은 앱에서 사용하는 엔드포인트에 따라 다릅니다. 각 엔드포인트에 어떤 권한이 필요한지 확인하려면 엔드포인트 참고 자료를 참조하세요.

앱에서 또는 앱을 요청한 비즈니스에서 역할이 부여되지 않은 앱 사용자가 앱을 사용할 경우 앱 검수를 통해 각 권한에 대한 승인을 요청해야 역할이 없는 앱 사용자가 앱에 권한을 부여할 수 있습니다.

공용 서버

Facebook에서는 게시 시도 시 사용한 미디어에 대해 cURL을 실행하여 해당 시도 시점에 미디어를 공개적으로 액세스 가능한 서버에서 호스팅되도록 합니다.

페이지 게시 인증

페이지 게시 인증(PPA)이 필요한 페이지에 연결된 Instagram 프로페셔널 계정에는 PPA를 완료할 때까지 게시할 수 없습니다.

앱 사용자는 처음에 PPA가 필요하지 않지만 나중에 필요한 페이지에서 작업을 수행할 수 있습니다. 이 시나리오에서는 PPA를 완료할 때까지 앱 사용자가 Instagram 프로페셔널 계정에 콘텐츠를 게시할 수 없습니다. 앱 사용자의 페이지에 PPA가 필요한지 확인할 수 있는 방법이 없으므로, 앱 사용자에게 미리 PPA를 완료하도록 안내하는 것이 좋습니다.

제한 사항

유일하게 지원되는 이미지 형식은 JPEG입니다. 확장된 JPEG 형식(예: MPO, JPS)은 지원되지 않습니다.
쇼핑 태그는 지원되지 않습니다.
브랜디드 콘텐츠 태그는 지원되지 않습니다.
필터는 지원되지 않습니다.
Instagram TV로의 게시는 지원되지 않습니다.

추가적인 제한 사항은 각 엔드포인트 참고 자료를 참조하세요.

사용 제한

Instagram 계정은 24시간 이내에 API를 통해 게시물을 최대 50개까지 게시할 수 있습니다. 슬라이드는 단일 게시물로 간주됩니다. 이 제한은 미디어 컨테이너를 게시하려고 할 때 POST /{ig-user-id}/media_publish 엔드포인트에 적용됩니다. 앱에서도 게시 사용 제한을 적용하는 것이 좋습니다. 특히 앱에서 앱 사용자가 게시물이 나중에 게시되도록 예약할 수 있는 경우에 권장합니다.

Instagram 프로페셔널 계정의 현재 사용 제한 사용량을 확인하려면 GET /{ig-user-id}/content_publishing_limit 엔드포인트를 쿼리하세요.

엔드포인트

API는 다음과 같은 엔드포인트로 구성됩니다. 사용 요구 사항은 각 엔드포인트의 참고 자료를 참조하세요.

POST /{ig-user-id}/media — 미디어를 업로드하고 미디어 컨테이너를 만듭니다.
POST /{ig-user-id}/media_publish — 미디어 컨테이너를 사용하여 업로드된 미디어를 게시합니다.
GET /{ig-container-id}?fields=status_code — 미디어 컨테이너 게시 자격 요건과 상태를 확인합니다.
GET /{ig-user-id}/content_publishing_limit — 앱 사용자의 현재 게시 사용 제한 사용량을 확인합니다.

단일 미디어 게시물

단일 이미지, 동영상, 스토리 또는 릴스를 게시하는 절차는 2단계로 구성됩니다.

POST /{ig-user-id}/media 엔드포인트를 사용하여 공개 서버에서 호스팅되는 이미지 또는 동영상에서 컨테이너를 만듭니다.
POST /{ig-user-id}/media_publish 엔드포인트를 사용하여 컨테이너를 게시합니다.

1/2단계: 컨테이너 만들기

다음과 같은 주소의 이미지가 있다고 가정합니다.

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

'#BronzFonz' 해시태그를 캡션으로 넣어서 게시하려고 합니다. POST /{ig-user-id}/media 엔드포인트로 요청을 보냅니다.

요청 샘플

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

그러면 이미지의 컨테이너 ID가 반환됩니다.

응답 샘플

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

2/2단계: 컨테이너 게시

POST /{ig-user-id}/media_publish 엔드포인트를 사용하여 이전 단계에서 반환된 컨테이너 ID를 게시합니다.

요청 샘플

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

응답 샘플

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

슬라이드 게시물

단일 게시물(슬라이드 게시물)에 이미지, 동영상 또는 그 두 가지의 조합을 최대 10개까지 게시할 수 있습니다. 슬라이드 게시는 3단계 절차로 구성됩니다.

POST /{ig-user-id}/media 엔드포인트를 사용하여 슬라이드에 표시할 각 이미지와 동영상에 대해 개별적인 항목 컨테이너를 만듭니다.
다시 POST /{ig-user-id}/media 엔드포인트를 사용하여 항목에 대해 단일 슬라이드 컨테이너를 만듭니다.
POST /{ig-user-id}/media_publish 엔드포인트를 사용하여 슬라이드 컨테이너를 게시합니다.

슬라이드 게시물은 계정의 사용 제한에서 단일 게시물로 간주됩니다.

제한 사항

슬라이드는 홍보할 수 없습니다.
슬라이드는 이미지, 동영상 또는 그 두 가지의 조합을 최대 10개로 제한합니다.
모든 슬라이드 이미지는 슬라이드의 첫 이미지를 기준으로 자릅니다. 기본 가로세로비는 1:1입니다.

1/3단계: 항목 컨테이너 만들기

POST /{ig-user-id}/media 엔드포인트를 사용하여 슬라이드에 표시할 이미지나 동영상에 대한 항목 컨테이너를 만듭니다. 슬라이드에는 이미지, 동영상 또는 그 두 가지의 조합을 모두 합쳐 최대 10개까지 포함할 수 있습니다.

POST /{ig-user-id}/media

매개변수

다음 매개변수는 필수입니다. 지원되는 매개변수를 더 보려면 POST /{ig-user-id}/media 엔드포인트 참고 자료를 참조하세요.

is_carousel_item — true로 설정합니다. 슬라이드에 표시할 이미지 또는 동영상을 나타냅니다.
image_url — (이미지 전용) 이미지에 대한 경로입니다. 전달된 URL을 사용하여 이미지에 cURL을 실행하므로 이미지가 공용 서버에 있어야 합니다.
media_type — (동영상 전용) VIDEO로 설정합니다. 미디어가 동영상임을 나타냅니다.
video_url — (동영상 전용) 동영상에 대한 경로입니다. 전달된 URL을 사용하여 동영상에 cURL을 실행하므로 동영상이 공용 서버에 있어야 합니다.

작업이 성공할 경우 API는 슬라이드 컨테이너를 만들 때 사용할 수 있는 항목 컨테이너 ID를 반환합니다.

슬라이드에 표시할 각 이미지 또는 동영상에 대해 이 절차를 반복합니다.

요청 샘플

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..."

응답 샘플

{
  "id": "17899506308402767"
}

2/3단계: 슬라이드 컨테이너 만들기

POST /{ig-user-id}/media 엔드포인트를 사용하여 슬라이드 컨테이너를 만듭니다.

POST /{ig-user-id}/media

매개변수

다음 매개변수는 필수입니다. 지원되는 매개변수를 더 보려면 POST /{ig-user-id}/media 엔드포인트 참고 자료를 참조하세요.

media_type — CAROUSEL로 설정합니다. 컨테이너의 용도가 슬라이드임을 나타냅니다.
children — 게시된 슬라이드에 표시해야 하는 각 이미지와 동영상의 컨테이너 ID(최대 10개)로 구성된 배열입니다. 슬라이드에는 이미지, 동영상 또는 그 두 가지의 조합을 모두 합쳐 최대 10개까지 포함할 수 있습니다.

요청 샘플

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..."

응답 샘플

{
  "id": "18000748627392977"
}

3/3단계: 슬라이드 컨테이너 게시

POST /{ig-user-id}/media_publish 엔드포인트를 사용하여 슬라이드 컨테이너(슬라이드 게시물)를 게시합니다. 계정은 24시간 이내에 게시물을 최대 50개까지 게시할 수 있습니다. 슬라이드를 게시할 경우 이는 단일 게시물로 간주됩니다.

POST /{ig-user-id}/media_publish

매개변수

다음 매개변수는 필수입니다.

creation_id — 슬라이드 컨테이너 ID입니다.

작업이 성공하면 API는 슬라이드 사진첩 IG 미디어 ID를 반환합니다.

요청 샘플

curl -i -X POST \

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

응답 샘플

{
  "id": "90010778390276"
}

릴스 게시물

릴스는 특정 사양을 충족하고 Facebook 알고리즘에서 선택되는 경우 Instagram 앱의 릴스 탭에 표시할 수 있는 짧은 동영상입니다. 릴스를 게시하려면 단일 미디어 게시물을 게시하는 단계를 따르고 media_type=REELS 매개변수를 따르고 video_url 매개변수를 사용하는 동영상 경로를 포함하세요.

릴스를 게시할 때 media_type=REELS를 설정하더라도 이는 새로운 미디어 유형에 해당하지 않습니다. 릴스를 게시하고 해당 media_type 필드를 요청하는 경우 이 값은 VIDEO로 반환됩니다. 게시된 동영상이 릴스로 지정되었는지 확인하려면 대신 media_product_type 필드를 요청하세요.

GitHub 코드 샘플(insta_reels_publishing_api_sample)을 사용하여 Instagram에 릴스를 게시하는 방법을 알아볼 수 있습니다.

개발자들에게 더 많은 편의를 제공하기 위해 Meta에서는 Postman API 플랫폼에 Instagram 릴스에 대한 그래프 API 호출 세트 전체를 공개했습니다. 자세한 내용은 Facebook 릴스 및 Instagram 릴스용 Postman 컬렉션을 참조하세요.

릴스에 대한 자세한 내용은 릴스 개발자 문서를 참조하세요.

스토리 게시물

지금은 비즈니스 계정만 콘텐츠 게시 API를 사용하여 스토리를 게시할 수 있습니다.

스토리는 Instagram에 IG 스토리로 게시되는 동영상과 이미지입니다. 스토리를 게시하려면 단일 미디어 게시물을 게시하는 것과 동일한 단계를 따르고 media_type=STORIES 매개변수와 image_url 또는 video_url 매개변수를 사용하는 이미지/동영상 경로를 포함하세요.

참고: 스토리를 게시할 때 media_type=STORIES를 설정하더라도 이는 새로운 미디어 유형에 해당하지 않습니다. 스토리를 게시하고 해당 media_type 필드를 요청하는 경우 이 값은 IMAGE/VIDEO로 반환됩니다. 게시된 이미지/동영상이 스토리로 지정되었는지 확인하려면 대신 media_product_type 필드를 요청하세요.

공동 작업자 태그

이미지, 슬라이드, 릴스에서 공개된 Instagram 사용자를 공동 작업자로 추가할 수 있으며, 이 사용자는 해당 미디어의 공동 작업자가 되기 위한 초대장을 받게 됩니다. 이미지에서 사용자를 태그하려면 위의 단일 미디어 게시물 단계를 따릅니다. 하지만 미디어 컨테이너를 생성할 때는 공동 작업자 매개변수와 해당 미디어의 공동 작업자로 초대하고자 하는 사용자의 Instagram 사용자 이름을 나타내는 문자열의 배열을 포함하세요.

요청 샘플

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

참고

공동 작업자 값은 문자열의 배열이어야 합니다.
전체 공개 Instagram 계정이 있는 사용자만 태그할 수 있습니다.
공동 작업자는 4명 이상 추가할 수 없습니다.
공동 작업자는 스토리 미디어에 추가할 수 없습니다.

위치 태그

검색 문자열과 일치하는 페이지를 검색하려면 페이지 검색 API 를 사용하여 쿼리에 'location' 필드를 포함하세요. 그런 다음, 결과를 파싱하여 물리적 위치에 생성된 페이지를 확인하세요. 이미지 또는 동영상을 게시할 때 페이지 ID를 포함하면 해당 페이지와 연결된 위치가 사진에 태그됩니다.

제한 사항

태깅에 사용할 수 있으려면 페이지에 위도와 경도 위치 데이터가 있어야 합니다.

사용하려는 페이지의 위도와 경도 데이터가 응답에 있는지 확인합니다. 위치 데이터가 없는 페이지를 사용하여 컨테이너를 만들려고 시도하면 코딩된 예외 INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID와 함께 실패합니다.

페이지 ID가 생기면 단일 미디어 또는 슬라이드 항목 컨테이너를 게시할 때 location_id 매개변수에 할당합니다.

제품 태그

단일 미디어 게시물과 슬라이드 게시물을 Instagram Shopping 제품으로 태그할 수 있습니다. 자세한 방법은 제품 태깅 가이드를 참조하세요.

사용자 태그

이미지에 전체 공개 Instagram 사용자를 태그하면 해당 사용자는 태그될 때 알림을 받게 됩니다.

이미지에서 사용자를 태그하려면 위의 단일 미디어 게시물 단계를 따릅니다. 하지만 미디어 컨테이너를 만들 때는 user_tags 매개변수, 이미지에서 Instagram 사용자를 나타내는 개체의 배열, 이미지 자체의 x/y 좌표를 포함합니다.

요청 샘플

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

컨테이너 ID가 반환되면 IG 사용자 미디어 게시 엔드포인트를 사용하여 게시합니다.

참고

user_tags 값은 JSON 형식의 개체 배열이어야 합니다.
전체 공개 Instagram 계정이 있는 사용자만 태그할 수 있습니다.
개체는 각 사용자에 대해 3가지 속성(username, x, y)을 모두 포함해야 합니다.
x와 y 값은 이미지 상단 왼쪽에서 시작하는 float 숫자이면서 0.0~1.0 범위여야 합니다.
사용자 태그는 슬라이드에서 이미지와 함께 사용할 수 있습니다.

문제 해결

동영상의 컨테이너를 만들 수 있지만 POST /{ig-user-id}/media_publish 엔드포인트가 게시된 미디어 ID를 반환하지 않을 경우 GET /{ig-container-id}?fields=status_code 엔드포인트를 쿼리하여 컨테이너의 게시 상태를 가져올 수 있습니다. 이 엔드포인트는 다음 중 하나를 반환합니다.

EXPIRED — 컨테이너가 24시간 이내에 게시되지 않아서 만료되었습니다.
ERROR — 컨테이너가 게시 프로세스를 완료하지 못했습니다.
FINISHED — 컨테이너와 해당 미디어 개체를 게시할 준비가 되었습니다.
IN_PROGRESS — 컨테이너가 아직 게시 절차 중에 있습니다.
PUBLISHED — 컨테이너 미디어 개체가 게시되었습니다.

컨테이너 상태는 1분에 1회, 최대 5분 이내로 쿼리하는 것이 좋습니다.

오류

오류 코드 참고 자료를 참조하세요.