分割メディアアップロード

このガイドでは、チャンクアップロードワークフローを使用して動画や大容量メディアファイルをアップロードする方法を説明します。動画または大容量メディアをアップロードする場合は、次の手順を実行する必要があります。

INIT — アップロードを初期化して media_id を取得する
APPEND — ファイルの各チャンクをアップロードする
FINALIZE — アップロードを完了する
STATUS — (必要に応じて) 処理が完了するまで待機する

完全な Python サンプルコードについては、このサンプルコードを参照してください。

ステップ1: アップロードの初期化 (INIT)

アップロードセッションを開始して media_id を取得します:

cURL

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"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# チャンクアップロードを初期化
response = client.media.init_upload(
    media_type="video/mp4",
    total_bytes=1048576,
    media_category="amplify_video"
)

media_id = response.data.id
print(f"Media ID: {media_id}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// チャンクアップロードを初期化
const response = await client.media.initUpload({
  mediaType: "video/mp4",
  totalBytes: 1048576,
  mediaCategory: "amplify_video",
});

const mediaId = response.data?.id;
console.log(`Media ID: ${mediaId}`);

レスポンス:

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

ステップ 2: チャンクをアップロード (APPEND)

ファイルをチャンクごとにアップロードします。たとえば、3 MB のファイルを 3 つのチャンクに分割します:

cURL

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"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# チャンクをアップロード
chunk_size = 1024 * 1024  # 1 MB のチャンクサイズ

with open("video.mp4", "rb") as f:
    segment_index = 0
    while True:
        chunk = f.read(chunk_size)
        if not chunk:
            break
        
        client.media.append_upload(
            media_id=media_id,
            segment_index=segment_index,
            media=chunk
        )
        segment_index += 1
        print(f"Uploaded chunk {segment_index}")

import { Client } from "@xdevplatform/xdk";
import fs from "fs";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// チャンクをアップロード
const chunkSize = 1024 * 1024; // 1 MB のチャンクサイズ
const fileBuffer = fs.readFileSync("video.mp4");

let segmentIndex = 0;
for (let offset = 0; offset < fileBuffer.length; offset += chunkSize) {
  const chunk = fileBuffer.slice(offset, offset + chunkSize);
  
  await client.media.appendUpload({
    mediaId,
    segmentIndex,
    media: chunk,
  });
  
  console.log(`Uploaded chunk ${segmentIndex + 1}`);
  segmentIndex++;
}

チャンクアップロードの利点:

低速なネットワーク環境でもアップロードの信頼性が向上する
アップロードを一時停止して再開できる
失敗したチャンクだけを個別に再試行できる

ステップ 3: アップロードの完了 (FINALIZE)

すべてのチャンクの送信が完了したら、アップロードを確定します:

cURL

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"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# アップロードを完了
response = client.media.finalize_upload(media_id=media_id)

print(f"Processing state: {response.data.processing_info.state}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// アップロードを完了
const response = await client.media.finalizeUpload({ mediaId });

console.log(`Processing state: ${response.data?.processing_info?.state}`);

レスポンス:

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

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

from xdk import Client
import time

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Wait for processing to complete
while True:
    response = client.media.get_status(media_id=media_id)
    state = response.data.processing_info.state
    
    if state == "succeeded":
        print("Media ready!")
        break
    elif state == "failed":
        print("Processing failed")
        break
    else:
        check_after = response.data.processing_info.check_after_secs
        print(f"Processing... checking again in {check_after}s")
        time.sleep(check_after)

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// Wait for processing to complete
while (true) {
  const response = await client.media.getStatus({ mediaId });
  const state = response.data?.processing_info?.state;
  
  if (state === "succeeded") {
    console.log("Media ready!");
    break;
  } else if (state === "failed") {
    console.log("Processing failed");
    break;
  } else {
    const checkAfter = response.data?.processing_info?.check_after_secs ?? 1;
    console.log(`Processing... checking again in ${checkAfter}s`);
    await new Promise((r) => setTimeout(r, checkAfter * 1000));
  }
}

処理状態: pending → in_progress → succeeded または failed

ステップ 5: メディア付きポストを作成する

処理が完了したら、次にメディア付きポストを作成します:

cURL

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

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# メディア付きポストを作成
response = client.posts.create(
    text="Check out this video!",
    media={"media_ids": [media_id]}
)

print(f"Posted: {response.data.id}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

// メディア付きポストを作成
const response = await client.posts.create({
  text: "Check out this video!",
  media: { mediaIds: [mediaId] },
});

console.log(`Posted: ${response.data?.id}`);

メディアカテゴリ

カテゴリ	説明
`tweet_image`	ポスト用の画像
`tweet_gif`	ポスト用のアニメーション GIF
`tweet_video`	ポスト用の動画
`amplify_video`	Amplify 動画

次のステップ

ベストプラクティス

ファイルに関する制約と要件

ポストを作成

メディア付きのポスト

APIリファレンス

エンドポイントの完全なドキュメント

概要

投稿

ユーザー

ダイレクトメッセージ

いいね

リスト

スペース

コミュニティ

コミュニティノート

トレンド

ニュース

メディア

X のアクティビティ

利用状況

ストリーム接続

コンプライアンス

Enterprise v2

いいねのストリーム

GNIP 2.0

分割メディアアップロード

ステップ1: アップロードの初期化 (INIT)

ステップ 2: チャンクをアップロード (APPEND)

ステップ 3: アップロードの完了 (FINALIZE)

ステップ 4: ステータスを確認する (STATUS)

ステップ 5: メディア付きポストを作成する

メディアカテゴリ

次のステップ

ベストプラクティス

ポストを作成

APIリファレンス