ビデオストック

外部RSSにエピソードが現れる前に動画をアップロードし、変換処理を進められます。RSS取り込み後にGUID、またはタイトル・配信予定日時を使って自動で紐づけます。所有している外部RSS番組が対象です。LISTENホスティング番組には登録できません。

エンドポイント

ベースURL：https://listen.style/api/v1

一覧は確認済みの所有番組が対象です。first（1〜100、既定50）、after、podcast_id、status で指定します。status は uploading・processing・ready・failed・matched・cancelled です。省略時は取消済みを除外します。meta.has_more が真なら meta.next_cursor を次回の after に渡してください。取得途中にも状態は変わるため、一覧全体のスナップショットは保証しません。

登録

アップロードを完了してからリクエストします。

curl -X POST "https://listen.style/api/v1/podcasts/$PODCAST_ID/video-stock" \
  -H "Authorization: Bearer $LISTEN_API_TOKEN" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data '{"expected_title":"第101回","expected_guid":"episode-101","expected_published_at":"2026-10-01T12:00:00+09:00","video_path":"RETURNED_PATH","client_key":"episode-101-video"}'

必須は expected_title（255文字以内）と video_path です。任意で expected_guid（255文字）、expected_published_at、video_thumbnail_path、client_key（空でない128文字以内）を指定します。画像はJPEG・PNG・GIF・WebP、最大10 MiBです。

client_key は番組内で一意の再送用識別子です。同じキーでの再送は、最初に登録した項目の現在の状態を返し、異なる入力で上書きしません。取消後も再利用できません。新しい動画には新しいキーを使ってください。

新規登録時は 201、再送時は 200。data は登録したストックです。変換は非同期なので、登録成功だけでは視聴可能になりません。

レスポンスの項目

単一取得・登録の data、一覧の data[] は次の項目を返します。

id、podcast_id、client_key、revision、expected_title、expected_guid、expected_published_at、status、failure_reason、matched_episode_id、youtube_sync_detached、matched_at、created_at、updated_at。

未設定の任意項目・未紐づけのIDや日時は null です。変換失敗時は failure_reason を確認してください。

修正・取消・紐づけ

PATCHは登録時と同じ編集項目（client_key を除く）を受け付けます。省略は保持、GUID・予定日時・サムネイルの null は解除です。取得した revision を expected_revision に指定することを推奨します。

{"expected_title":"修正したタイトル","expected_guid":null,"expected_revision":2}

DELETEは任意で {"expected_revision":2} をJSON本文に指定します。ファイルは非同期で削除されますが、状態確認と重複防止用の記録を保持します。手動紐づけは {"episode_id":"EPISODE_ID","expected_revision":2} を送ります。同じ番組の公開済みで動画のないエピソードに限ります。

応答の data は outcome、現在の item、youtube_action_required を含みます。

変換中もタイトル等は変更できますが、動画・サムネイル差し替えは完了後に行ってください。タイトル等の変更だけでは再変換しません。紐づいた後はエピソードの管理画面から変更してください。

YouTube送信中は取消・メディア差し替えを受け付けません。これらのAPIはYouTube上の動画を変更・削除しません。youtube_action_required が真なら別途YouTube側を確認してください。修正でYouTube連携を切り離したストックは、紐づけ時にもYouTube情報を自動更新しません。

制限・関連機能

ウェブでは、番組の「ビデオストック」で未紐づけの動画の「詳細を編集」を開くと、配信予定タイトル・GUID・配信予定日時を修正できます。日時はアカウントのタイムゾーンで表示・入力します。動画の再アップロードは不要で、変換中でもこれらの情報を編集できます。保存時に変換済み動画の紐づけを再確認します。編集中に状態や内容が変わった場合は上書きせず、開き直して確認するよう案内します。YouTube上の情報は変更しません。

登録は利用者ごとに1時間30件、同時変換待ち・処理中は3件までです。登録回数制限は 429（Retry-After 付き）、利用枠・同時処理数・形式・重複GUID等の条件を満たさない場合は 422 です。修正・取消・手動紐づけは既存APIと共通で1分120回までですが、REST共通の1分60リクエスト制限も適用されます。

利用枠、Webhook、RSS再取得もあわせて利用できます。Web画面では番組の「ビデオストック」から「全番組のビデオストック」を開けます。