---
title: "Project Media — 完成した画像・動画・PDFの公開"
description: "media/ディレクトリへのファイル配置で成果物をprojectに公開する仕組み。対応形式・上限・canonical URL・WebUIでの見え方と、session添付（--attach）が公開されない境界を示す。"
---

# Project Media — 完成した画像・動画・PDFの公開

Project Mediaは、**完成した**画像・動画・PDFをprojectの資産として公開・再利用するためのserver保存領域である。作業途中のファイル置き場ではない。公開されたメディアはWebUIのMediaタブに並び、安定したURLでtimeline・文書・HTMLから参照できる。

## 公開のしかた

公開方法は2つある。

1. **ファイルを置く（agentの基本経路）**: workspaceの `aachat/projects/<team>/<project>/media/` に完成ファイルを置くと、自動で検出されてserverに公開される。専用のコマンドはない。作業ディレクトリで作ってから、完成品だけを `mv`（rename）で `media/` に移すのが正しい手順である。書きかけのままの直接生成は中途半端な状態で拾われうる
2. **WebUIからアップロード**: MediaタブのアップロードUI（人間のみ）

ファイル配置の検出は次のルールで動く。

- `.tmp` / `.part` / ドットファイル / シンボリックリンク / ディレクトリは公開されない
- ローカルで削除しても公開済みメディアは消えない（unpublishされない）
- 存在したままの同じpathへ同一bytesを上書きしても再公開されない。削除を検出した後の再出現は別のpublicationになりうる

## 対応形式と上限

| 項目 | 値 |
|---|---|
| 対応形式 | 画像（PNG / JPEG / WebP / GIF）、動画（MP4）、PDF |
| 画像1ファイル | 最大20 MiB |
| PDF 1ファイル | 最大50 MiB |
| 動画1ファイル | 最大2 GiB |
| project合計 | 最大20 GiB |

対応外の形式は `media_type_not_supported`、暗号化PDFも拒否される。

## 参照 — canonical URL

公開されたメディアの唯一の安定した参照は canonical URL `https://aachat.io/m/<uuid>` である。

- 画像はMarkdownに `![説明](https://aachat.io/m/<uuid>)` で埋め込める。動画・PDFはリンクとして貼る
- 配信時の署名付きURLやstorageのURLは短命であり、文書・メッセージに保存してはならない。保存するのは常に `/m/<uuid>`
- projectの公開済み一覧は、WebUIのMediaタブ、またはsession内の `chat media <project>` で確認できる

canonical URLは安定した**識別子**であり、public share URLではない。解決には、そのmediaが属するactive projectの認証済みmembershipが必要である。外部公開が必要ならProject HTML等の明示的なshare surfaceを使う。

## Sessionで既存Mediaの内容を読む

一覧やcanonical URLだけでは、Sessionが画像・動画・PDFの実体を読めたことにはなりません。内容を確認するには、対応CLIでローカルへ取得し、成功JSONが示すファイルを読みます。canonical URLを直接fetchするとloginページが返る場合があるため、bytesの取得には使いません。

### 前提を確認する

利用するSessionで次を確認します。

```sh
chat --version
chat media --help
```

helpに`--download <MEDIA_ID>`があるCLIと、Session Media deliveryに対応するAPIが必要です。2026年9月6日に確認したchat 5.7.26のhelpにはdownloadがありませんでした。ソースやガイドに構文があっても、その端末で使えるとは限りません。未対応ならここで止め、利用版とhelpの結果を残して管理者へ対応版を確認します。

対象は同じteamのactiveな通常Projectで、実行中のSessionにそのProjectのcoverageと書込権限（Collaborator/Admin）が必要です。一覧を読めるだけでは取得APIの条件を満たすとは限りません。認証・権限・APIエラーは返されたcodeとhintに従って確認し、権限追加や別Projectの作成で回避しません。

### 一覧から選び、取得したファイルを読む

1. `chat media <team>/<project>`でready一覧を読み、対象の`media.id`とcanonical URLを確認します。必要なら一覧だけに`--q <text>`を付けます。0件や対象の不在は内容を確認できたという意味ではありません。絞り込みやページ送り、対象Project、準備状況を確認します。
2. 以下のplaceholderを実際のProject名と一覧のUUIDへ置き換えて実行します。`<MEDIA_ID>`には正確なcanonical URLも渡せます。`--download`と`--q`・`--last`・`--before`は併用できません。

```sh
chat media <team>/<project> --download <MEDIA_ID>
```

3. 成功JSONの`downloaded.media_id`を対象と照合し、`downloaded.path`が指すローカルファイルを、形式に対応した読取ツールで開きます。JSONには`content_type`と`byte_size`も返ります。保存先は対象Projectの`media/.downloads/<id>.<ext>`ですが、名前からpathを推測せず返却値を使います。取得成功と内容の読取成功は別々に確認します。読取ツールが対応しなければ、内容は未確認として扱います。

取得コピーは読取用です。`.downloads`は自動公開の探索対象外なので、そのまま読み、編集したり`media/`直下へコピー・移動して再公開したりしません。文書・メッセージには元のcanonical URLを保持します。ローカルpathや短命の配信用URLは共有リンクにしません。

### 取得が止まったとき

| 結果 | 次に行うこと |
|---|---|
| `media_unavailable` | 同Projectのready一覧を再確認します。対象がなければProject・ID・準備状況を確認し、readyになってから再取得します。取得できない内容を推測しません。必要なら人間にSessionへのファイル添付を依頼します |
| `media_download_failed` | 返された`reason`を読み、一度再試行します。再失敗したら`chat report`で報告します。成功JSONがない実行を取得済みとは扱いません。以前取得した同名ファイルが残る場合があり、その存在だけでも今回の成功を判断できません |

報告にはProjectとMedia ID、時刻、CLIの版、確認できるdaemon/APIの版、error・reason、pathの状態を添えます。不明な版は不明と記し、認証情報や署名付きURLは含めません。構文は[CLI](/ja/docs/cli)、他の症状の切り分けは[トラブルシューティング](/ja/docs/troubleshooting)を参照してください。

## detail、feedback、削除

Media detailではpreviewとoriginal download、画像寸法やPDF page数などのmetadata、publication historyを確認できる。source sessionがあるmediaは、その成果へfeedbackを返すか、そのmediaを文脈に新しいsessionを始められる。

server上のmedia削除は不可逆操作で、書込権限（Collaborator/Admin）を持つメンバーと、そのProjectをcoverageに持つSessionが行える。

- current Shared DocumentまたはProject HTMLから参照されている場合は削除をblockする。参照を外してから再実行する
- historicalまたは追跡できない参照はwarningになる。削除前に利用先を確認する
- 削除後はcanonical URLも解決不能になり、過去のmessageや外部記録のlinkも壊れる

localの`media/` fileを消してもserver上の公開済みmediaは消えない。削除はMedia detailから、Sessionからは`chat media <project> --delete <MEDIA_ID> --revision <N>`で明示的に行う。

## 公開されない境界 — session添付

`session run` / `session send` の `--attach` で渡したファイルは **Session historyに入るだけで、Project Mediaには公開されない**。依頼の文脈として画像を渡すのが `--attach`、projectの資産として公開するのが `media/` 配置である。この2つを混同しない。

なお、Entityのkindにも `media` という名前があるが（[Company](/ja/docs/company)）、それは会社の媒体・チャネルを表す別概念である。

## 完成したレポートを公開して確認する

active Projectで、coverageと書込権限（Collaborator/Admin）を持つSessionからpublishします。`aachat up`を稼働させ、監視対象の外にある`./output/customer-report.pdf`を完成させてから、Project名を置き換えて移します。
```sh
mkdir -p aachat/projects/acme/customer-research/media
mv ./output/customer-report.pdf aachat/projects/acme/customer-research/media/customer-report.pdf
chat media acme/customer-research
```

検出されたfileはuploadとprocessingを経てreadyになります。**Media**でレポートを探し、preview、metadata、original downloadを確認します。実際のcanonical URLをコピーしてShared Documentへ載せ、filenameからUUIDを作りません。配置やuploadの受付だけではprocessing成功を確認できません。

同じローカルpathへ異なる完成bytesを置くと新しいpublicationになります。publication historyと返されたmedia identityを確認します。既存canonical asset linkは「現在そのローカルpathにあるファイル」を意味しません。存在したまま内容が変わらないfileは重複publishを避けますが、削除と再出現はwatcherの別の状態遷移です。remove-and-replaceをserver削除操作として使いません。

何も現れない場合は、完成fileか、対応形式・quota内か、無視対象やsymlinkでないか、coverageにある正しいProject pathかを確認します。processingやfailedの場合はstatus/errorを読み、sourceや指摘条件を直してから再publishします。文書やHTML buildで参照できない場合はready状態と正確なcanonical参照を確認します。削除がblockされたら現在の文書・HTML依存先を外し、その更新・buildが受理されるのを待ちます。参照を変えずに削除を繰り返しません。

外部readerには、対象の依存先を許可する[MarkdownまたはHTML share](/ja/docs/sharing)を使います。canonical URL自体のmember権限確認は維持されます。

## 関連ページ

- 成果物サーフェスの全体像（docs / media / html / apps） — [Projects](/ja/docs/projects)
- ブラウザで見せる成果物 — [HTML](/ja/docs/html)
- serverに保存されるものの一覧 — [信頼境界](/ja/docs/trust-boundary)

小さいファイルでも画像寸法・animation frame数・PDFページ数・動画時間の上限を超える場合があります。再試行前に[bytes以外の内容上限](/ja/docs/limits)も確認してください。拡張子だけを変えても形式は変わりません。