メディア API（Media API）

メディア API を使用すると、販売者は次のファイルを作成、アップロード、取得できます:

• 画像
• ビデオ
• ドキュメント（GPSR 規制用）

バージョン: v1_beta.4.0

ベースURL: https://apim.ebay.com/commerce/media/v1_beta（または https://api.ebay.com/commerce/media/v1_beta）

認証（OAuth スコープ）

この API のすべてのエンドポイントでは、認可コード付与フロー（Authorization Code Grant）で取得した OAuth 2.0 ユーザートークンが必要です。

リソース一覧

Media API は以下の 3 つのリソースカテゴリで構成されています。

image — 画像

image リソースは、出品に使用する画像の作成と取得を行います。画像はファイルを直接アップロードするか、URL を指定して作成できます。

POST /image/create_image_from_file

createImageFromFile — ファイルから画像を作成します。画像ファイルを multipart/form-data 形式で直接アップロードします。

画像が正常に作成されると、HTTP ステータスコード 201 Created が返されます。レスポンスには画像の URL と有効期限が含まれます。

OAuth スコープ: sell.inventory

レスポンス:

• 201 — 作成済み → ImageResponse
• 400 — リクエスト形式が不正
• 403 — アクセス禁止
• 500 — 内部サーバーエラー

POST /image/create_image_from_url

createImageFromUrl — 指定された URL から画像をダウンロードして作成します。

画像が正常に作成されると、HTTP ステータスコード 201 Created が返されます。

OAuth スコープ: sell.inventory

リクエストボディ: CreateImageFromUrlRequest

レスポンス:

• 201 — 作成済み → ImageResponse
• 400 — リクエスト形式が不正
• 403 — アクセス禁止
• 500 — 内部サーバーエラー

GET /image/{image_id}

getImage — 指定された画像 ID に基づいて画像のメタデータ（URL、有効期限）を取得します。

OAuth スコープ: sell.inventory

レスポンス:

• 200 — 成功 → ImageResponse
• 400 — リクエスト形式が不正
• 403 — アクセス禁止
• 404 — 画像が見つかりません
• 500 — 内部サーバーエラー

video — ビデオ

video リソースは、出品に使用するビデオの作成、メタデータ取得、ファイルアップロードを行います。

ビデオの作成フローは次のとおりです:

1. createVideo でビデオのメタデータ（タイトル、サイズ等）を登録
2. uploadVideo で実際のビデオファイルをアップロード
3. getVideo でステータスを確認（PENDING_UPLOAD → PROCESSING → LIVE / BLOCKED / PROCESSING_FAILED）

POST /video

createVideo — ビデオを作成します。作成するビデオのタイトル、サイズ（バイト単位）、分類を指定します。説明はオプションです。

ビデオが正常に作成されると、HTTP ステータスコード 201 Created が返されます。レスポンスの location ヘッダーにビデオ ID が含まれます。

注: ビデオのフォーマット要件と制限の詳細については、eBay セラーセンターの「動画を出品リストに追加する」を参照してください。

注: 現時点では、ビデオのメタデータを編集する機能およびビデオを削除する機能はありません。

OAuth スコープ: sell.inventory

リクエストボディ: CreateVideoRequest

レスポンス:

• 201 — 作成済み（レスポンスボディなし。location ヘッダーにビデオ ID）
• 400 — リクエスト形式が不正
• 403 — アクセス禁止
• 500 — 内部サーバーエラー

GET /video/{video_id}

getVideo — 指定されたビデオ ID に基づいてビデオのメタデータとコンテンツを取得します。

レスポンスには、ビデオのタイトル、サイズ、分類、説明、ビデオ ID、プレイリスト（ストリーミング URL）、ステータス、ステータスメッセージ（ある場合）、有効期限、サムネイル画像が含まれます。

ビデオのプレイリストには、サポートされているプロトコル（DASH、HLS）に基づいてストリーミングビデオにリンクする URL が含まれています。

ビデオの有効期限は、作成後 30 日後に自動的に設定されます。

OAuth スコープ: sell.inventory

レスポンス:

• 200 — 成功 → Video
• 400 — リクエスト形式が不正
• 403 — アクセス禁止
• 404 — ビデオが見つかりません
• 500 — 内部サーバーエラー

POST /video/{video_id}/upload

uploadVideo — 指定されたビデオ ID にファイルを関連付け、入力ファイルをアップロードします。ファイルがアップロードされると、処理が開始されます。

注: アップロードするビデオのサイズは、createVideo メソッドで設定されたサイズと正確に一致する必要があります。サイズが一致しないと、ビデオは正常にアップロードされません。

ステータスフロー: PENDING_UPLOAD → PROCESSING → LIVE / BLOCKED / PROCESSING_FAILED

このメソッドは再開可能なアップロードをサポートしています。アップロードが中断された場合、Content-Range および Content-Length ヘッダーを使用して特定のバイト位置から再開できます。

この呼び出しには JSON リクエストペイロードはなく、ファイルを application/octet-stream としてアップロードします。

OAuth スコープ: sell.inventory

レスポンス:

• 200 — アップロード成功
• 400 — リクエスト形式が不正
• 403 — アクセス禁止
• 404 — ビデオが見つかりません
• 409 — 競合（ビデオが既にアップロード済み等）
• 411 — Content-Length が必要
• 416 — 範囲が満たされない（Range Not Satisfiable）
• 500 — 内部サーバーエラー

document — ドキュメント

document リソースは、GPSR（一般製品安全規則）などの規制に必要なドキュメントの作成、アップロード、メタデータ取得を行います。サポートされているファイルタイプは .PDF、.JPEG/.JPG、.PNG で、最大ファイルサイズは 10 MB（10,485,760 バイト）です。

注: アニメーションおよび複数ページの PNG ファイルは現在サポートされていません。

ドキュメントの作成フローは次のとおりです:

1. createDocument でドキュメントをステージング（または createDocumentFromUrl で URL から直接作成）
2. uploadDocument でファイルをアップロード（createDocument を使用した場合）
3. getDocument でステータスを確認（documentStatus が ACCEPTED のドキュメントのみリストに追加可能）

重要: レスポンスで返される documentId 値を必ずキャプチャしてください。この値は、document リソース内の他のメソッドを使用するために必要であり、Trading API および Inventory API を使用してドキュメントをリストに関連付けるためにも必要です。

POST /document

createDocument — アップロードするドキュメントをステージングします。アップロードするドキュメントの種類とドキュメントに含まれる言語が必要です。

ドキュメントが正常に作成されると、HTTP ステータスコード 201 Created が返されます。レスポンスペイロードに documentId が含まれ、location ヘッダーでも返されます。

作成されたドキュメントをアップロードするには、このメソッドのレスポンスから返された documentId を uploadDocument メソッドで使用します。

詳細については、ドキュメントの管理を参照してください。

OAuth スコープ: sell.inventory

リクエストボディ: CreateDocumentRequest

レスポンス:

• 201 — 作成済み → CreateDocumentResponse
• 400 — リクエスト形式が不正
• 500 — 内部サーバーエラー

POST /document/create_document_from_url

createDocumentFromUrl — 指定された URL からドキュメントをダウンロードし、ユーザーのアカウントに追加します。ドキュメントの URL、ドキュメントの種類、ドキュメントに含まれる言語が必要です。

ドキュメントが正常に作成されると、HTTP ステータスコード 201 Created が返されます。レスポンスペイロードに documentId が含まれます。

このメソッドを使用してドキュメントを作成した後、getDocument を呼び出して documentStatus が ACCEPTED であることを確認してください。このステータスのドキュメントのみがリストに追加できます。

詳細については、ドキュメントの管理を参照してください。

OAuth スコープ: sell.inventory

リクエストボディ: CreateDocumentFromUrlRequest

レスポンス:

• 201 — 作成済み → CreateDocumentResponse
• 400 — リクエスト形式が不正
• 500 — 内部サーバーエラー

GET /document/{document_id}

getDocument — 指定されたドキュメントの現在のステータスとメタデータを取得します。

createDocument メソッドのレスポンスで返される documentId 値が、このメソッドの必須パスパラメータです。

詳細については、ドキュメントの管理を参照してください。

OAuth スコープ: sell.inventory

レスポンス:

• 200 — 成功 → DocumentResponse
• 400 — リクエスト形式が不正
• 404 — ドキュメントが見つかりません
• 500 — 内部サーバーエラー

POST /document/{document_id}/upload

uploadDocument — 指定されたファイルを指定されたドキュメント ID に関連付け、入力ファイルをアップロードします。ファイルがアップロードされると、処理が開始されます。

サポートされているファイルタイプは .PDF、.JPEG/.JPG、.PNG で、最大ファイルサイズは 10 MB（10,485,760 バイト）です。

注: アニメーションおよび複数ページの PNG ファイルは現在サポートされていません。

注: Content-Type ヘッダーを multipart/form-data に設定する必要があります。

この呼び出しには JSON リクエストペイロードはなく、ファイルを form-data としてアップロードします。例:

file: @"/C:/Users/.../drone_user_warranty.pdf"

アップロードが成功すると、HTTP ステータスコード 200 OK が返されます。

詳細については、ドキュメントの管理を参照してください。

OAuth スコープ: sell.inventory

レスポンス:

• 200 — アップロード成功 → DocumentResponse
• 400 — リクエスト形式が不正
• 404 — ドキュメントが見つかりません
• 500 — 内部サーバーエラー

スキーマ定義

Media API で使用されるリクエスト/レスポンスのデータモデルです（全 15 スキーマ）。

画像関連

CreateImageFromUrlRequest

ImageResponse

Image

ビデオ関連

CreateVideoRequest

Video

Play

Moderation

ドキュメント関連

CreateDocumentRequest

CreateDocumentFromUrlRequest

CreateDocumentResponse

DocumentResponse

DocumentMetadata

共通スキーマ

Error

ErrorParameter

エンドポイント一覧