청크 단위 미디어 업로드

청크 업로드를 사용해 동영상 및 대용량 미디어 파일 업로드하기

이 가이드는 청크 업로드 워크플로를 사용해 동영상 및 대용량 미디어 파일을 업로드하는 방법을 단계별로 안내합니다.

동영상 또는 대용량 미디어를 업로드하려면 다음 단계를 수행해야 합니다.

1. INIT — 업로드를 초기화하고 media_id를 가져옵니다.
2. APPEND — 파일의 각 청크를 업로드합니다.
3. FINALIZE — 업로드를 완료합니다.
4. STATUS — (필요한 경우) 처리가 완료될 때까지 기다립니다.

전체 Python 예제는 이 샘플 코드를 참고하세요.

---

​

1단계: 업로드 초기화 (INIT)

업로드 세션을 시작하여 media_id를 발급받습니다:

cURL

shellscript

curl -X POST "https://api.x.com/2/media/upload" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "command=INIT" \
  -F "media_type=video/mp4" \
  -F "total_bytes=1048576" \
  -F "media_category=amplify_video"

응답:

{
  "data": {
    "id": "1880028106020515840",
    "media_key": "13_1880028106020515840",
    "expires_after_secs": 1295999
  }
}

---

​

2단계: 청크 업로드하기 (APPEND)

파일의 각 청크를 업로드합니다. 예를 들어, 3MB 파일을 3개의 청크로 나눕니다:

cURL

shellscript

curl -X POST "https://api.x.com/2/media/upload" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "command=APPEND" \
  -F "media_id=1880028106020515840" \
  -F "segment_index=0" \
  -F "media=@/path/to/chunk1.mp4"

청크 방식의 장점:

• 느린 네트워크 환경에서도 안정성이 향상됩니다.
• 업로드를 일시 중지했다가 다시 이어서 진행할 수 있습니다.
• 실패한 청크만 개별적으로 다시 시도할 수 있습니다.

---

​

3단계: 업로드 최종화 (FINALIZE)

모든 청크를 전송한 후 업로드를 완료합니다:

cURL

shellscript

curl -X POST "https://api.x.com/2/media/upload" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "command=FINALIZE" \
  -F "media_id=1880028106020515840"

응답:

{
  "data": {
    "id": "1880028106020515840",
    "media_key": "13_1880028106020515840",
    "size": 1048576,
    "expires_after_secs": 86400,
    "processing_info": {
      "state": "pending",
      "check_after_secs": 1
    }
  }
}

processing_info가 반환되면 4단계로 이동해 처리가 완료될 때까지 기다리세요. 반환되지 않은 경우 미디어를 바로 사용할 수 있습니다.

---

​

4단계: 상태 확인 (STATUS)

processing_info가 반환되었다면, 처리가 완료될 때까지 폴링하세요:

cURL

shellscript

curl "https://api.x.com/2/media/upload?command=STATUS&media_id=1880028106020515840" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

처리 상태: pending → in_progress → succeeded 또는 failed

---

​

5단계: 미디어가 포함된 게시물 생성

처리가 완료되면 미디어가 포함된 게시물을 생성합니다:

cURL

shellscript

curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Check out this video!",
    "media": {
      "media_ids": ["1880028106020515840"]
    }
  }'

---

​

미디어 카테고리

Category	Description
tweet_image	게시물용 이미지
tweet_gif	게시물용 애니메이션 GIF
tweet_video	게시물용 비디오
amplify_video	Amplify 비디오

---

​

다음 단계

모범 사례

파일 제한 사항 및 요구 사항

포스트 생성

미디어가 포함된 포스트 만들기

API 참조 문서

엔드포인트 전체 문서