メディア API

準備完了メディアを新しい順に最大1000件ずつ一覧表示。folder は特定のメディアフォルダー直下のファイル（ID指定）、root はライブラリルート直下のみ。正しいフォルダーIDでなければ何も返さない。next_cursor は最後の行の位置で、続きがあれば after として同じフィルターで次ページに渡す。最後のページは null。

プロンプトから静止画を1枚生成し、準備済みのプライベートなプロジェクトメディアとして保存し、その使用量を課金します。Prefer: respond-async の有無にかかわらず、POST は直ちに 202 で Operation を返します。API の前にあるプロキシはバイトを 100 s 送信しないリクエストを破棄し、高品質の静止画にはそれより長くかかる場合があるためです。

Operation が succeeded になり、その result が {media_id, usage: {quality, credits, usd}}（MediaGenerationUsage） になるまで、または failed になり、その error が問題を示すまで、GET /api/operations/{id} をポーリングします。ベンダーの作業前に決定された拒否（payment_required、reseller_generation_limit、rate_limited、not_ready、invalid_request）でも、POST には引き続き応答します。

画像バイト、b64_json、オブジェクトキー、署名付きURL、ベンダーURL、ベンダーコスト、ベンダートークン、展開モデル名は決して含みません。プロンプトは顧客のバイトであり、エコーされません。

プロンプトが画像ベンダーに届く前に、サーバーは固定されたフレーミング要件を追加します：アートワークはフレームの端から端まで満たす必要があり、テレビ、モニター、スクリーン、ディスプレイ、ベゼル、フレーム、ボーダー、マウント、スタンド、壁、部屋、デバイスのモックアップ、ドロップシャドウ、設置されたサインの写真は描写できません。呼び出し元のプロンプトにサインの設置場所や表示デバイスを説明する文言がある場合、それは主題ではなく配置メタデータとして扱われます。

デザイン内部の装飾ルールと境界線は引き続き利用できます。呼び出し元のプロンプトは書き換えも削除もされず、そのまま保存されます。Idempotency-Key は同じ Operation を再生し、課金される2回目の試行は決して行いません。クライアントは生成されたバイトを PUT したりコミットしたりしません。

保存されたレンディションはロスのある WebP（品質 90）で、正確なアスペクトサイズかつ短辺が 1080 px です（16:9 は 1920x1080、9:16 は 1080x1920、1:1 は 1080x1080、4:3 は 1440x1080、3:4 は 1080x1440、3:2 は 1620x1080、2:3 は 1080x1620）。ベンダーキャンバスは中央クロップされ、そのサイズにリサンプルされます。

ファイル名は世代ごとに特徴的で、generated-16x9-1a2b3c4d.webpのように、サフィックスはメディアIDから取られます。GET /api/media/{id}/content.でバイトを取得します。Own-gen-then-uploadは有効なままです。

Standard では、イントロフロア（2027-01-01 までマイナス1,000,000クレジット、その後ゼロ）後に、静止画のベンダーコストの2倍を全クレジットで切り上げてカバーできない残高は payment_required を返します（SCREENRIG__ENVIRONMENT=development は除く）。また、ベンダーコール前の入場には、そのフロアを品質ごとの最低値だけ上回る残高が必要です：低品質は200クレジット、中品質は800、高品質は2000。

それ以外のプランは、残高を理由に拒否されることはありません。

リセラー経由で請求される組織は、そのリセラーに委任された顧客に対して、その月の画像生成の上限（リセラーが審査待ちの間は定価で $100、審査後は $1,000。UTC の月単位で集計）が請求済みになると、reseller_generation_limit (402) で拒否されます。ただし、組織自身のクレジットでその画像をまかなえる場合を除きます。すでに受け付けた生成は完了します。

選択したベンダーの設定が空の場合は not_ready を返します。プロジェクトのベアラーのみ。組織あたり同時に進行できる生成は 1 件で、それを超える並列実行は rate_limited になります。

プロジェクト内のすべてのメディアフォルダーを名前順に最大1000件リストします。フォルダーはメディアライブラリを整理し、playlist selector by:folderは1つのフォルダー内のファイルを直接再生します。フォルダーのparent_idはライブラリルートでnullです。

ツリーはparent_idから構築します。ファイルのフォルダーはMedia.folder_idです。library=trueを指定すると、代わりに組織のライブラリのフォルダーを一覧します（読み取り専用。by:folderセレクターで指定できます）。

ライブラリのルート（parent_idがnullまたは存在しない）またはparent_id内に1つのメディアフォルダーを作成します。名前はトリムされ、制御文字なしの1～100のUnicode文字を含み、「.」や「..」ではなく、繰り返し可能です。組織は、すべてのプロジェクトを合わせて最大1000フォルダー（quota_exceeded）、最大10階層のネスト（invalid_request）を保持します。media.folder_createdを発行します。

フォルダーの名前を変更（name）するか、中身すべてを別のフォルダー（parent_id、ライブラリルートはnull）に移動します。フォルダーは自身またはその内部のフォルダーに移動できず、移動後もすべてのフォルダーが10階層以内でなければなりません（invalid_request）。変更はフォルダーのリビジョンを進め、media.folder_updatedを発行します。同じ値は操作なしです。

If-Matchはリビジョンをオプションで保護します。

フォルダーを1つ削除します。中身は削除されず、ファイルとフォルダーは削除したフォルダーの親に移動します（フォルダーがなければライブラリのルート）。移動したファイルとフォルダーはリビジョンが進みます。by:folderのプレイリストセレクターは削除したフォルダーを指定すると何も一致しなくなり、再生中のスクリーンは次のセレクター解決時にそのプリミティブを削除します。

media.folder_deleted を出力します。If-Match でリビジョンをオプションで保護します。

ファイル（media_ids）とフォルダー（folder_ids）を1つのフォルダー（folder_id）に、または folder_id が null の場合はライブラリのルートに移動します。最大1000 ID の一括リクエストです。すべての ID は存在する必要があります（not_found）。フォルダーは自身またはその内部のフォルダーに移動できず、移動後はすべてのフォルダーが10階層以内でなければなりません（invalid_request）。

既に宛先にあるアイテムはそのままにし、移動した各ファイルとフォルダーは改訂を進めます。ファイル移動は古いフォルダーと新しいフォルダーのby:folderセレクターの再生内容を変え、各スクリーンの次のセレクター解決から影響します。フォルダー移動はフォルダー自身のファイルを変えません。media.movedを発行します。

Propose 資格情報の移動により、移動された各ファイルは保留となり、メディアレビューがキューに入ります。承認済みプレイリストのセレクターは、その変更がユーザーに承認されるまで、承認時のフォルダーで解決されます（docs/reviews.md）。

現在のプロジェクト所有の準備済み画像またはビデオの読み取り専用プレビュー。ファイル名の順序と正規化されたポリシーを返します。ランダム再生はプレーヤーの各新しいパスでシャッフルされます。カーソルの進行、コンテンツ付与の発行、マニフェストの変更は行いません。1024件を超える一致はinvalid_requestを返します。

メディア項目のタグセットを設定またはクリアします。Propose 資格情報のタグセット変更は項目を保留にし、メディアレビューをキューに入れます。承認済みプレイリストのセレクターは承認時のタグで解決し、変更は人が承認するまで保留されます（docs/reviews.md）。同じタグセットを維持するパッチは適用され、項目は承認済みのままです。

サインインした人はメディアアイテムのタグを設定します。tagsは完全な新セットで、ソート済みです。アイテムの単一タグはタグの1つとしてカウントされ、他のタグで置き換えられるため、保持するには再送信してください。空配列はすべてのタグをクリアし、不正なタグ、重複タグ、32個超はinvalid_requestです。

Manage認証情報下でpatchMediaが行うタグ変更です。ダッシュボードセッションでメディア改訂が1つ進み、media.updatedはセット変更の有無にかかわらず人物をアクターとして持ちます。人物の変更はライブであり、レビューではありません。

人のレビュー待ちのメディア（review_state pending、Propose資格のアップロードまたは変更による）はmedia_pending_review（409）で拒否され、変更はありません：まずレビューで決定してください。タグ編集はエージェントの提案を承認しません。タグによるプレイリストセレクターは次のプレイリストループ更新時に新しいタグを反映します。

本文に他のメンバーはありません。If-Match はメディアのリビジョンを持ち、必須です（欠如時は invalid_request、古い場合は revision_conflict）。ダッシュボードセッションのみ；エージェントは patchMedia でタグを変更します。listMedia はタグで新しいタグのアイテムを見つけます。

メディアアイテムを再生する動的セレクター（all、tag、folder）が選べる時期を設定するか、availability を null にしてルールを解除します。ルールはスケジュールのものと同じで、from と until（市民時間、分精度、until は含まない）、windows、monthly、dates の発生、except の日付で構成され、セレクターを解決する各スクリーンのタイムゾーンで判定されます。

ルールの範囲外のファイルは、次のプレイリストループの境界で選択から外れ、ルールが再び成立すると戻ります。ウィンドウの端には、Player の次のループから 1 分以内に追従します。プレイリストやマニフェストのリビジョンは変わりません。明示的な id（id または ids によるセレクター）は、動的セレクター以外のすべてと同様に、このルールの対象外です。

オフラインのスクリーンは、再接続するまで最後の選択を保持します。アイテムにすでにあるルールを設定しても何も変わりません。Propose 資格情報では設定できません（insufficient_access）。メディアをいつ再生するかは Manage アクセスを持つ人が決めます。人のレビュー待ちのメディアは media_pending_review で拒否されます。

If-Match はメディアのリビジョンを保持し、必須です。

宣言済み（createMediaUpload）でバイト列の書き込みが済んだアップロードで、準備完了のメディアアイテムのファイルをその場で置き換えます。新しいメディアとしてコミットはしません。

メディアの ID は変わらないため、そのメディアを指定しているプレイリストやスケジュールは、再スケジュールなしで新しいファイルを再生し、それを選ぶフォルダー・タグ・全メディアのセレクターも次の解決時に再生します。置換は同じ種類のファイルでなければなりません（画像には画像、動画には動画、音声には音声）。別の種類は invalid_request になります。

アスペクト比の変更は許可されます。操作の結果には、そのアイテムを使うプレイリストを示す warnings エントリ aspect_ratio_changed が含まれます。アップロードのルールはすべて適用されます（プランの動画バイト数上限、サイズの上限、ストレージ容量）。

使用中のファイルはメディアのバージョン履歴（listMediaVersions）に残り、そのバージョンを削除するまで保存バイト数に加算されます。If-Match を送る場合は、呼び出し元が読み取ったメディアのリビジョンです（古い場合は revision_conflict）。

レスポンスは commitMediaUpload と同様にアップロードのオペレーションです。getOperation をポーリングしてください。成功したオペレーションの結果は {media_id, id, version, warnings} です。使用中のファイルとバイト列が同一の場合は何も置き換えられず、オペレーションは resource_conflict で失敗します。

有効な Propose のもとでは、置換は代わりにレビュー待ちになります。オペレーションは result.status pending_review と result.review_id で成功し、担当者が承認するまでメディアは元のファイルを再生し続け、同じメディアのより新しい置換が待機中の置換に取って代わります。

メディアアイテムのバージョンを新しい順に一覧します。使用中のバージョンが先頭です（current: true）。バージョンとは、そのアイテムが持っていたファイルのことです。number はコンテンツエポックに 1 を足した値で（アップロードが 1、置換・復元・メディア同期による変更のたびに 1 ずつ増加）、バイト列はそのバージョンを削除するまで保持されます。

バージョンのバイト列は GET /api/media/{id}/content?version=N で読み取れます。

過去のバージョンを削除します。そのレコードは消え、バイト数はただちにプロジェクトの保存バイト数から外れ、別のバージョンまたは使用中のバージョンが同じファイルを保持していない限り、オブジェクトは 24 時間後に削除されます。使用中のバージョンは削除できず（resource_conflict）、メディアの置換がレビュー待ちの間は、どのバージョンも削除できません。

削除したバージョンは復元できません。

過去のバージョンを、メディアの次のコンテンツエポックにおける新しいバージョンとして使用中に戻します。メディアの ID はそのままでリビジョンが 1 進むため、そのメディアを指定しているプレイリストやスケジュールは、再スケジュールなしでそのファイルを再び再生します。コピー元のバージョンは履歴に残ってバイト列を共有し、新しいバージョンは他と同様に保存バイト数に加算されます。

使用中のバージョンは復元できません（resource_conflict）。If-Match を送る場合は、呼び出し元が読み取ったメディアのリビジョンです。ボディにはメモを含められます。有効な Propose のもとでは、復元はレビューになり（202 pending_review）、担当者が承認するまでメディアは元のファイルのままです。

認証されたプロジェクトが所有する元の不変レンディションをエクスポートします。プロジェクトベアラーは通常の認証APIリクエストクレジットを課金され、完了したレスポンスバイトは project_media_export の送信として記録されます。メディア識別子は決して権限ではありません。別のプロジェクトの識別子は not_found を返します。

API はプライベートストレージからストリームを配信し、オブジェクトキー、ストレージ URL、署名付き GET を公開しません。添付ファイルのファイル名は、メディア識別子に検証済みコンテンツタイプの標準拡張子を付けたものです。コンテンツの読み取りが残高を理由に拒否されることはありません。

ダッシュボードセッションは同じバイトをインラインで表示します：完了したバイトは dashboard_media の送信として記録され、応答はプライベートで no-cache なのでブラウザは1つのコピーを保持し If-None-Match で再検証します。プロジェクトベアラーの応答はプライベートで no-store です。

exportMediaContent と同じプロジェクト所有権、条件、範囲、プライベートストレージルールを適用しますが、保存されたレンディションを開いたり転送したりしません。

Lists the project's media sync accounts, newest first (200 per page; next_cursor continues). Each shows its tenant and client id, its state and its last test; the client secret is never returned, only whether one is set and its last four characters.

読み取りで同期するアカウントを追加します。kind microsoft365 は、プロジェクト独自の Microsoft Entra アプリの認証情報を保存し、同期が SharePoint や OneDrive for Business のフォルダーを読み取れるようにします。config.tenant_id はテナントのディレクトリ ID またはプライマリドメイン (common、organizations、consumers は拒否されます)、config.client_id はアプリのアプリケーション ID、secret はアプリのクライアントシークレットの 1 つの値です。アプリには、管理者の同意のもと、Microsoft Graph のアプリケーション権限 Sites.Selected (各サイトで付与) または Files.Read.All が必要です。

この 3 つの代わりに、config.connection_id でプロジェクトの Microsoft 接続 (createConnection) を、どちらのモードでも指定でき、その接続がサインインしてシークレットを保持します。kind canva は名前だけを受け付けます。アカウントは pending_consent になり、応答には authorize_url (authorize_expires_at まで有効な 1 回限りのリンク) が含まれ、Canva アカウントの所有者が Canva にサインインした状態でそれを開き、screenRIG の Canva 連携を通じて接続します。

この許可はプロジェクトに属するため、その同期は、接続した人がいなくなっても続きます。

Canva 連携のないサーバーは 409 canva_not_configured を返します。kind dropbox は canva と同様に動作します。アカウントは pending_consent になり、authorize_url は 1 回限りのリンクで、Dropbox アカウントの所有者が Dropbox にサインインした状態でこれを開き、読み取り専用のアクセス（files.metadata.read、files.content.read、account_info.read、sharing.read）を許可します。

接続は screenRIG の Dropbox アプリを通じて行われ、config.app_key でお客様自身の Dropbox アプリが指定されている場合は、そのアプリを通じて行われます（PKCE を使うためアプリシークレットは不要です。アプリのリダイレクト URI として https://API_ORIGIN/api/dropbox/callback を登録しておく必要があります）。

screenRIG の Dropbox アプリがないサーバーは、app_key のない dropbox アカウントに 409 dropbox_not_configured を返します。kind google_drive は即座に ready になり、config.service_account_email と共有されたフォルダーを読み取ります。config.service_account_email は screenRIG のサービスアカウントで、secret がお客様自身のサービスアカウントの JSON キーである場合は、そのサービスアカウントです。

screenRIG のサービスアカウントと共有されたフォルダーが同期されるのは、検証済みメールアドレスを持つプロジェクトのメンバーがそれを共有したか、所有している場合だけです。screenRIG のサービスアカウントがないサーバーは、キーのない google_drive アカウントに 409 google_drive_not_configured を返します。シークレットは保存時に封印され、返されることも、ログに記録されることもありません。media_sync_account.created を追記します。

同じ Idempotency-Key での同一の再試行は、同じアカウントを返します（Canva または Dropbox の再試行では新しいリンクが発行されます）。

シークレットをマスクしたメディア同期アカウント 1 件。

Changes the name, tenant, client id or secret; an omitted secret keeps the stored one. A change of credentials discards the last test. A Canva account takes only a name; media sync account connect renews its connection. Appends media_sync_account.updated. If-Match guards the revision.

Deletes the account. Refused 409 resource_conflict while a sync reads through it; the detail names those syncs. Deleting a Canva account also revokes its tokens at Canva (a failure to revoke is logged and does not undo the delete). Appends media_sync_account.deleted. If-Match guards the revision.

Signs in with the account's app and reports what Microsoft granted it: whether the credentials work and which Graph application permissions the token carries (Sites.Selected, Files.Read.All and the like). Sites.Selected is reported with a warning, because each site needs a grant for the app.

For a Canva account it reports whether Canva still accepts the connection. It does not judge a site's grant, a folder or a design, or consent beyond what the token carries. The result is stored as last_test. A failed check is ok false in the answer, not a problem.

Canva または Dropbox アカウント向けに、1 回限りの新しい同意リンク（authorize_url、authorize_expires_at まで有効）を作成します。そのアカウントの所有者に送ってください。所有者は Canva または Dropbox にサインインした状態でリンクを開き、アクセスを許可します。以前のリンクはすべて置き換えられます。

接続済みのアカウントは、新しい同意が完了するまで接続されたままなので、この操作は、状態が reconnect_required の接続の更新や、別の Canva または Dropbox アカウントへの切り替えにも使えます。リンクは同意の認証情報です。その人にだけ送ってください。

Canva 連携のないサーバーは 409 canva_not_configured を返します。screenRIG の Dropbox アプリのないサーバーでは、app_key のない Dropbox アカウントに対して 409 dropbox_not_configured を返します。

Lists the Canva designs the connected person can see, most recently changed first (50 per page; continuation continues), optionally those matching query. Each shows its id, title, last change, page count and a view address. An account that is not connected is 409 canva_reconnect_required; a server without the Canva integration is 409 canva_not_configured.

同意リンクでアクセスを許可（または拒否）した後に、Canva がその人を送り先とする場所。

It carries no credential: the one-time state in the query finds the Canva account, must be unexpired and is used once, in the same write that stores the connection. screenRIG exchanges the code (PKCE, client authentication with the integration's credentials), reads whose Canva account it is, seals the tokens and appends media_sync_account.connected.

The answer is a short page naming the account and the project it was connected to; an error, an unknown, expired or used state, or a refused code renders the same page with the reason and changes nothing. Answers only on the API host.

同意リンクでアクセスを許可（または拒否）した後、Dropbox がユーザーをリダイレクトする先です。

認証情報は含まれません。クエリ内の 1 回限りの state が Dropbox アカウントを特定し、期限内であることが必要で、接続を保存するのと同じ書き込みで 1 回だけ使用されます。screenRIG はコードを交換し（PKCE。screenRIG の Dropbox アプリまたはアカウント独自の app_key を使用）、どの Dropbox アカウントかを読み取り、トークンを封印して media_sync_account.connected を追記します。

The answer is a short page naming the account and the project it was connected to; an error, an unknown, expired or used state, or a refused code renders the same page with the reason and changes nothing. Answers only on the API host.

Lists the project's media syncs, newest first (200 per page; next_cursor continues), optionally of one account_id or state. Each shows its source folder, the media folder it fills, its cadence, state, next run and the summary of its last run.

provider canva：接続済みの Canva アカウント経由でデザイン（design はその ID または canva.com/design/ID/... アドレス）を読み取り、同期を保存して今すぐ実行対象にします。

Each run asks Canva for the design's last change and, when it moved, exports the pages (pages, default all; format png gives one image per page and mp4 one video) and imports them into the media folder, replacing the bytes of a page already imported under the same media id so the playlists that use it update; a page the design no longer has leaves play like a removed SharePoint file.

Canva が表示しなくなったデザインは、同期を状態 error（実行エラー design_unavailable）で停止させ、メディアはそのまま残します。

アカウントが見られないデザインやページは 409 media_sync_source_refused になります。provider dropbox: url は Dropbox 内のフォルダーのアドレス (https://www.dropbox.com/home/...)、接続済みアカウントが自分の Dropbox に追加した共有フォルダーのリンク、または / で始まるパスです。接続済みの Dropbox アカウントを通じて 1 回だけ読み取られ、同期が保存されて今すぐ実行対象になります。

チームスペース内のフォルダーは、チームのルートから読み取られます。各実行は Dropbox が保存しているフォルダー内の位置から続けられるため、変更だけが読み取られます。

アカウントが開けないフォルダーは 409 media_sync_source_refused、Dropbox が接続を認めなくなったアカウントは 409 dropbox_reconnect_required です。provider google_drive: url は Google Drive 上のフォルダーのアドレス (https://drive.google.com/drive/folders/ID) またはその ID で、アカウントの service_account_email と共有します（閲覧者で十分です）。

実行のたびにフォルダーを一覧し、各ファイルのチェックサムを比較します。Google ドキュメント、スプレッドシート、スライドのファイルは unsupported_type としてスキップされます。アドレスで開けないフォルダーは 409 media_sync_source_refused です。

screenRIG のサービスアカウントを通じる場合、フォルダーは、検証済みメールアドレスを持つプロジェクトのメンバーが共有または所有している必要があります（403 media_sync_sharer_not_member）。実行のたびに再確認され、実行エラー sharer_not_member は同期を状態 error で停止します。provider sharepoint: アカウントを通じてフォルダーのアドレスを読み取り、同期を保存して今すぐ実行対象にします。アドレスは、SharePoint のサイトアドレス (https://TENANT.sharepoint.com/sites/SITE/LIBRARY/FOLDER など) または共有リンクです。アプリがそれを参照できる必要があり、Sites.Selected ではサイトへの付与が、共有リンクでは Files.Read.All が必要です。folder_id はファイルの保存先となるメディアフォルダーです。指定しない場合、同期はソースフォルダーの名前を付けたメディアフォルダーを作成します。

Each run imports the images (png, jpeg, webp, gif), videos (mp4, webm) and audio (mp3) directly in the source folder, replaces the bytes of a file that changed under the same media id so playlists that use it update, and takes a file removed at the source out of play: its media is deleted, or, while screens still hold it, moved to a Removed subfolder and deleted later.

Subfolders are ignored; other files are listed as skipped with the reason. every is the seconds between runs, 300 to 86400, default 900. A folder the provider refuses is 409 media_sync_source_refused and one it cannot reach is 500 media_sync_source_unavailable; nothing is stored. Appends media_sync.created.

最後の実行の概要を含むメディア同期 1 件。

Changes the name, every (seconds between runs), state (active or paused; active also resumes a sync an error stopped) or folder_id. A new folder_id points the sync at another media folder and makes its next run read the whole source again, which puts every synced file there. Appends media_sync.updated. If-Match guards the revision.

同期を停止し、どのソースファイルがどのメディアになったかの対応を忘れます。メディアとそのフォルダーは残ります。media_sync.deleted を追加します。If-Match がリビジョンを保護します。

同期を今すぐ実行対象にして 202 を返します。ワーカーが約 30 秒以内に実行し、GET /api/media-syncs/{id} の応答に last_run が示されます。

エラーで停止した同期は再び実行されます。一時停止中の同期は、再開するまで拒否されます。force=true を指定すると、Canva が変更なしと報告しても Canva 同期はデザインをエクスポートします（SharePoint 同期では拒否されます。変更されたファイルはすべて既にダウンロードされるためです）。