REST API로 YouTube 영상을 업로드·발행·예약하고 처리 상태를 확인하세요.

연결된 YouTube 채널과 같은 워크스페이스의 영상을 사용합니다. 요청 하나에 계정 1개·영상 1개를 지원하며 posts·video·instagram 대신 youtube 객체를 전달합니다. 영상은 공개·일부 공개·비공개 중 하나로 발행합니다. 이 절차에서는 첫 댓글과 리포스트를 지원하지 않습니다.

모든 요청의 대상 워크스페이스는 API 키가 결정합니다. GET /api/v1/accounts에서 계정 ID를 가져오고 capabilities.publishPosts 또는 capabilities.schedulePosts를 확인하세요. 두 값은 연결이 재연동 대상으로 표시되지 않았고 youtube.upload 스코프가 승인된 경우에만 true입니다. false이면 Posteady에서 채널을 다시 연결하세요.

영상 선택 또는 업로드

미디어 라이브러리에 있는 영상은 목록에서 mediaId를 가져와 사용합니다.

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

응답에는 media·total·hasMore가 포함됩니다. 각 영상에는 mediaId·fileName·mimeType·fileSize·url과 확인된 길이·해상도 정보가 있습니다. 워크스페이스 라이브러리에 표시되는 활성 MP4·QuickTime 영상 중 지원되는 파일을 반환합니다.

새 파일은 업로드 URL을 먼저 발급받습니다. 아래 예제는 video.mp4가 정확히 10,485,760바이트라고 가정합니다. fileSize를 실제 파일의 바이트 수로 바꾸세요.

curl -X POST https://www.posteady.com/api/v1/media/uploads \
  -H "Authorization: Bearer $POSTEADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "video.mp4",
    "contentType": "video/mp4",
    "fileSize": 10485760
  }'

응답은 mediaId·fileKey·uploadUrl·expiresInSeconds·requiredHeaders를 반환합니다. 공용 라이브러리는 2 GiB 이하의 MP4(video/mp4)와 QuickTime(video/quicktime) 파일을 받지만, YouTube 요청에 쓸 영상은 최대 500 MB, 12시간이어야 합니다. 이를 넘는 파일은 발행 시 VALIDATION_ERROR로 거부됩니다.

300초 안에 uploadUrl로 파일 바이트를 전송하세요. requiredHeaders가 반환한 모든 헤더를 그대로 사용합니다.

curl --request PUT "<uploadUrl>" \
  --header "Content-Type: video/mp4" \
  --header "Content-Length: 10485760" \
  --upload-file video.mp4

PUT이 성공하면 업로드 생성 후 24시간 안에 반환받은 fileKey로 업로드 완료를 확인합니다.

curl -X POST https://www.posteady.com/api/v1/media/uploads/confirm \
  -H "Authorization: Bearer $POSTEADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileKey": "<fileKey>"
  }'

확인 응답의 mediaId를 발행에 사용하세요. ID 발급이나 파일 전송만 완료한 상태로는 발행할 수 없습니다. 기한이 지난 미확인 업로드는 정리되며 발행에 사용할 수 없습니다.

즉시 발행

이 발행 작업에 사용할 UUID를 한 번 생성해 youtube.requestId에 전달합니다. 같은 요청을 재시도할 때는 이 값을 유지하세요.

curl -X POST https://www.posteady.com/api/v1/posts \
  -H "Authorization: Bearer $POSTEADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIds": ["<youtube-account-uuid>"],
    "youtube": {
      "requestId": "<request-uuid>",
      "mediaId": "<confirmed-media-uuid>",
      "title": "제작 현장을 소개합니다",
      "description": "최신 릴리스를 만든 과정입니다.",
      "privacyStatus": "public",
      "madeForKids": false
    }
  }'

title은 필수이며 1–100자입니다. description은 선택이며 최대 5,000자입니다. privacyStatus는 public·unlisted·private 중 하나여야 합니다. madeForKids는 기본값이 false이며, COPPA 기준의 아동용 영상이면 true로 설정하세요. 같은 요청에 posts·video·instagram을 함께 보내지 마세요.

발행 작업이 접수되면 HTTP 202를 반환합니다.

{
  "results": [
    {
      "accountId": "<youtube-account-uuid>",
      "provider": "youtube",
      "username": "example",
      "success": true,
      "postIds": [],
      "jobId": "<job-uuid>",
      "status": "queued"
    }
  ],
  "summary": { "succeeded": 1, "failed": 0 }
}

이 응답의 success: true와 summary.succeeded는 작업 접수를 뜻합니다. YouTube에서 영상 발행이 완료됐다는 의미는 아닙니다. jobId를 저장하고 처리 상태를 확인하세요.

발행 상태 확인

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

응답에는 jobId·scheduledPostId·platform·accountId·username·status·postId·permalink·scheduledAt이 포함됩니다. 즉시 발행 작업의 scheduledAt은 null입니다. postId는 YouTube 영상 ID, permalink는 시청 URL이며 확인되기 전까지 null입니다. 실패 시 code·message가 담긴 error가 포함될 수 있습니다.

상태	의미
`queued`	처리를 시작하기 전 대기 중
`scheduled`	지정한 예약 시각까지 대기 중
`processing`	YouTube 업로드 진행 중
`published`	발행이 확인되어 영상 ID가 있음
`failed`	확인된 오류로 완료하지 못함
`canceled`	전송 전에 작업을 취소함
`unknown`	전송 결과를 확정하지 못함

실패 코드는 ACCOUNT_UNAVAILABLE(채널 재연결 필요)·MEDIA_UNAVAILABLE·PUBLISH_QUOTA_EXCEEDED(채널의 일일 업로드 한도 또는 요청 제한)·PREPARATION_FAILED·PUBLISH_FAILED입니다. unknown 작업에는 PUBLISH_RESULT_UNKNOWN이 포함됩니다.

API 요청이 중간에 끊기면 같은 requestId와 동일한 입력으로 재시도하세요. Posteady는 기존 작업을 반환합니다. 같은 키에 다른 계정·영상·제목·설명·공개 범위·예약 시각 등 변경된 입력을 보내면 **409 REQUEST_CONFLICT**가 반환됩니다.

unknown이면 Posteady가 영상을 자동으로 다시 업로드하지 않습니다. 새 요청을 만들지 결정하기 전에 YouTube Studio에서 업로드 여부를 확인하세요. 이미 업로드된 영상을 새 키로 요청하면 중복 게시될 수 있습니다.

예약과 취소

같은 accountIds·youtube 필드를 POST /api/v1/scheduled-posts로 보내면서 미래 시각의 scheduledAt과 선택 사항인 IANA timezone을 추가하세요.

{
  "accountIds": ["<youtube-account-uuid>"],
  "youtube": {
    "requestId": "<new-request-uuid>",
    "mediaId": "<confirmed-media-uuid>",
    "title": "제작 현장을 소개합니다",
    "privacyStatus": "unlisted"
  },
  "scheduledAt": "<future-time-with-offset>",
  "timezone": "Asia/Seoul"
}

예약이 접수되면 HTTP 202와 함께 results[0].scheduledPostIds·jobId·status: "scheduled"를 반환합니다. 발행 상태는 jobId로 확인합니다. YouTube 예약 목록은 다음과 같이 조회합니다.

curl "https://www.posteady.com/api/v1/scheduled-posts?provider=youtube" \
  -H "Authorization: Bearer $POSTEADY_API_KEY"

반환된 scheduledPostId로 취소합니다.

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

취소 성공 시 { "canceled": 1 }을 반환합니다. 업로드가 이미 시작됐다면 **409 POST_NOT_CANCELLABLE**이 반환됩니다. 예약 취소로 발행된 영상을 삭제하지는 않습니다.

게시물과 지표 조회

GET /api/v1/posts?provider=youtube를 호출합니다. Posteady에 이미 동기화된 데이터를 반환하며 YouTube를 새로 동기화하지 않습니다. 각 영상에는 postId(영상 ID)·title·content(설명, 최대 280자)·mediaType(VIDEO 또는 SHORTS)·metricsUpdatedAt이 포함됩니다. 지표는 views·likes·replies(댓글)를 숫자 또는 null로 제공하며 shares·reposts·quotes·bookmarks는 항상 null입니다. null은 0이 아닌 지표를 알 수 없는 상태로 처리하세요.

MCP로 사용

같은 작업을 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에 같은 youtube 객체를 전달하세요. 미디어 도구는 workspaceId를 받으며, 생략하면 기본 워크스페이스를 사용합니다. 발행·예약은 계정, 발행 상태 조회는 작업 ID로 워크스페이스를 결정하며, 선택 항목인 workspaceId는 해당 리소스와 일치해야 합니다. 파일 바이트는 발급된 업로드 URL에 PUT으로 전송해야 합니다. 할 수 있는 작업을 참고하세요.

YouTube 영상 발행