Instagram 미디어 발행

Instagram 프로페셔널 계정과 같은 워크스페이스에서 완료 확인된 미디어를 사용합니다. 요청 하나는 계정 1개를 대상으로 하며 posts나 video 대신 instagram 객체를 전달합니다.

GET /api/v1/accounts에서 계정 ID를 가져오세요. Instagram 계정의 accountType은 business·creator·unknown 중 하나이며, 해당 capability가 true일 때 조회·발행·예약을 지원합니다.

미디어 선택 또는 업로드

JPEG 이미지는 mediaType=IMAGE, MP4·QuickTime 영상은 mediaType=VIDEO로 조회합니다.

curl "https://www.posteady.com/api/v1/media?mediaType=IMAGE&limit=20&offset=0" \
  -H "Authorization: Bearer $POSTEADY_API_KEY"

기존 호환성을 위해 mediaType을 생략하면 VIDEO입니다. JPEG 이미지를 새로 올리려면 업로드를 예약합니다.

curl -X POST https://www.posteady.com/api/v1/media/uploads \
  -H "Authorization: Bearer $POSTEADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaType": "IMAGE",
    "fileName": "launch.jpg",
    "contentType": "image/jpeg",
    "fileSize": 1048576
  }'

반환된 requiredHeaders를 모두 사용해 300초 안에 uploadUrl로 파일 바이트를 PUT합니다. 이후 생성 후 24시간 안에 반환된 fileKey를 POST /api/v1/media/uploads/confirm으로 보내 완료를 확인합니다. 파일은 Posteady가 예약 크기·MIME·파일 시그니처를 확인하고 동일한 객체를 미디어 라이브러리로 승격할 때까지 비공개 staging에 보관됩니다.

JPEG 이미지는 최대 8 MiB입니다. 공용 라이브러리는 최대 2 GiB의 MP4·QuickTime 영상을 받지만 Instagram 요청에 쓸 영상은 최대 1 GiB, 3초–15분이어야 합니다. Story 영상은 최대 60초입니다. 영상 완료 확인의 duration·width·height는 선택적인 클라이언트 참고값입니다. Posteady는 지원되는 MP4·QuickTime 파일을 서버에서 측정하고 측정값을 저장합니다. Meta는 컨테이너 처리 중 코덱·프레임 레이트·비트레이트·화면비를 최종 검증합니다. 업로드 완료 확인 전에는 발행에 사용할 수 없습니다.

지원 형식

캡션은 유니코드 문자 최대 2,200개, 이미지 altText는 최대 1,000개입니다. 단일 FEED 영상은 거부됩니다. REELS로 발행하거나 2–10개 캐러셀에 포함하세요.

즉시 발행

작업에 사용할 UUID를 한 번 만들고 같은 요청을 재시도할 때 유지합니다.

curl -X POST https://www.posteady.com/api/v1/posts \
  -H "Authorization: Bearer $POSTEADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIds": ["<instagram-account-uuid>"],
    "instagram": {
      "requestId": "<request-uuid>",
      "contentType": "FEED",
      "caption": "새 소식을 전합니다",
      "items": [
        { "mediaId": "<confirmed-image-uuid>", "altText": "책상 위에 놓인 신제품" },
        { "mediaId": "<confirmed-video-uuid>" }
      ]
    }
  }'

작업이 접수되면 HTTP 202를 반환합니다. success: true는 작업 접수를 뜻하며 발행 완료가 아닙니다. results[0].jobId를 저장하고 published가 될 때까지 상태를 확인하세요.

curl "https://www.posteady.com/api/v1/publish-jobs/<job-uuid>" \
  -H "Authorization: Bearer $POSTEADY_API_KEY"

상태는 queued·scheduled·processing·published·failed·canceled·unknown입니다. native postId와 permalink는 확인되기 전까지 null입니다. unknown은 최종 전송 결과를 확정하지 못한 상태입니다. Posteady는 자동으로 다시 전송하지 않으므로 새 키로 요청하기 전에 Instagram에서 발행 여부를 확인하세요.

같은 requestId와 동일한 입력을 보내면 기존 작업을 반환합니다. 계정·형식·캡션·미디어·옵션·예약 시각 중 하나라도 다른 요청에 같은 키를 쓰면 **409 REQUEST_CONFLICT**입니다.

예약과 취소

같은 필드를 POST /api/v1/scheduled-posts로 보내면서 미래 시각의 scheduledAt과 선택 사항인 IANA timezone을 추가합니다.

{
  "accountIds": ["<instagram-account-uuid>"],
  "instagram": {
    "requestId": "<request-uuid>",
    "contentType": "STORIES",
    "items": [{ "mediaId": "<confirmed-image-uuid>" }]
  },
  "scheduledAt": "<future-time-with-offset>",
  "timezone": "Asia/Seoul"
}

예약 목록은 provider=instagram으로 조회합니다. 대기 중인 예약은 다음과 같이 취소합니다.

curl -X DELETE "https://www.posteady.com/api/v1/scheduled-posts/<scheduled-post-uuid>?platform=instagram" \
  -H "Authorization: Bearer $POSTEADY_API_KEY"

발행을 시작하기 전까지만 취소할 수 있습니다. 이후에는 POST_NOT_CANCELLABLE을 반환합니다.

API로 만든 예약이 접수된 뒤에는 내용·미디어·대상 계정이 고정됩니다. Posteady에서는 예약 시각만 바꾸거나 발행 시작 전에 취소할 수 있습니다. 이 제한으로 최초 멱등 요청과 실제 미디어 컨테이너가 일치하게 유지됩니다.

게시물과 지표 조회

GET /api/v1/posts?provider=instagram을 호출합니다. Posteady에 이미 동기화된 데이터를 반환하며 Instagram을 새로 동기화하지 않습니다. 각 게시물에는 mediaType·mediaProductType·metricsUpdatedAt이 포함될 수 있습니다. 노출은 views, 댓글은 replies, 저장은 bookmarks로 매핑하며, 사용할 수 없는 지표는 0 대신 null입니다.

MCP로 사용

같은 작업을 list_accounts·list_media·create_media_upload·confirm_media_upload·publish_post·schedule_post·get_publish_status·list_scheduled_posts·cancel_scheduled_post·list_posts 도구로 수행할 수 있습니다. publish_post·schedule_post에 같은 instagram 객체를 전달하세요. 미디어 도구는 workspaceId를 받으며, 생략하면 기본 워크스페이스를 사용합니다. 발행·예약은 계정, 발행 상태 조회는 작업 ID로 워크스페이스를 결정하며, 선택 항목인 workspaceId는 해당 리소스와 일치해야 합니다. 파일 바이트는 발급된 업로드 URL에 PUT으로 전송해야 합니다. 할 수 있는 작업을 참고하세요.