TikTok 영상 발행

TikTok for Business Developers로 연결한 계정과 같은 워크스페이스의 영상을 사용합니다. 요청 하나에 계정 1개·영상 1개·캡션 1개를 지원합니다. 영상은 privacyLevel: "PUBLIC_TO_EVERYONE"으로 전체 공개합니다. 이 절차에서는 사진 발행·인박스 전송·리포스트를 지원하지 않습니다.

모든 요청의 대상 워크스페이스는 API 키가 결정합니다. GET /api/v1/accounts에서 계정 ID를 가져오고 capabilities.publishPosts 또는 capabilities.schedulePosts를 확인하세요.

영상 선택 또는 업로드

미디어 라이브러리에 있는 영상은 목록에서 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 영상 중 지원되는 파일을 반환합니다. limit은 기본 20, 허용 범위 1–100이며 offset은 0–10,000을 받습니다.

새 파일은 업로드 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) 파일을 지원합니다. 파일명은 .mp4 또는 .mov로 끝나야 하며 최대 255자입니다. 디렉터리 경로나 제어 문자를 포함할 수 없습니다. 예약한 파일 크기는 조직의 미디어 저장 공간 한도에 포함됩니다.

300초 안에 uploadUrl로 파일 바이트를 전송하세요. requiredHeaders가 반환한 모든 헤더를 그대로 사용합니다. 스토리지 PUT은 발급받은 URL과 헤더로 호출합니다.

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>"
  }'

양수인 duration(초), 1–32,768 범위의 정수인 width·height(픽셀)를 클라이언트 참고값으로 함께 전달할 수 있습니다. 업로드를 생성한 사용자와 워크스페이스에서 확인하세요. Posteady는 저장된 파일의 크기·콘텐츠 유형·시그니처·객체 버전을 검증하고, 지원되는 MP4·QuickTime의 길이와 크기를 측정한 뒤 영상을 사용할 수 있게 합니다. 확인 응답의 mediaId를 발행에 사용하세요. ID 발급이나 파일 전송만 완료한 상태로는 발행할 수 없습니다.

완료 확인은 예약한 저장 공간을 사용하므로 파일 크기를 다시 더하지 않습니다. 기한이 지난 미확인 업로드는 정리되며 발행에 사용할 수 없습니다.

즉시 발행

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

curl -X POST https://www.posteady.com/api/v1/posts \
  -H "Authorization: Bearer $POSTEADY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIds": ["<tiktok-account-uuid>"],
    "posts": ["제작 현장을 소개합니다"],
    "video": {
      "mediaId": "<confirmed-media-uuid>",
      "requestId": "<request-uuid>",
      "privacyLevel": "PUBLIC_TO_EVERYONE",
      "disableComment": false,
      "disableDuet": false,
      "disableStitch": false,
      "brandOrganicToggle": false,
      "brandContentToggle": false
    }
  }'

불리언 필드 5개는 선택 사항입니다. 자사 브랜드를 홍보하면 brandOrganicToggle, 브랜디드 콘텐츠이면 brandContentToggle을 설정하세요. 요청 전 캡션·전체 공개 여부·이 설정들을 확인하세요. 캡션은 UTF-16 코드 유닛 2,200개까지이며, 이모지 하나가 두 유닛을 사용할 수 있습니다. 계정별 영상 길이 상한은 발행할 때 검사합니다.

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

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

이 응답의 success: true와 summary.succeeded는 작업 접수를 뜻합니다. TikTok에서 영상 발행이 완료됐다는 의미는 아닙니다. 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입니다. native postId와 permalink는 확인되기 전까지 null이며, 실패 시 code·message가 담긴 error가 포함될 수 있습니다.

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

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

예약과 취소

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

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

예약 성공 응답은 HTTP 200이며 results[0].scheduledPostIds·jobId·status를 포함합니다. 발행 상태는 jobId로 확인합니다. TikTok 예약 목록은 다음과 같이 조회합니다.

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

반환된 scheduledPostId로 취소합니다.

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

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

MCP로 사용

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