> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/api-integration/endpoint-behaviors/conversation-outputs-api.md).
# 対話の生成物一覧 API
会話内で AI が生成したドキュメント、画像、動画、プレゼンテーションの一覧を取得します。
会話の生成ファイル一覧 API は、会話内で AI が生成したドキュメント、画像、動画、HTML プレゼンテーションなどのファイルを一覧で返します。組織でファイルライブラリが有効になっている場合はファイルライブラリから、無効の場合は会話のコード実行ワークスペースから一覧を取得します。連携側はこの API を使って、「この会話でどのようなファイルが生成されたか」を表示できます。
API レスポンスのフィールド名は camelCase です。ログインと共通のリクエスト方法については、[クイックスタート](/tech/ja/api-integration/quickstart.md)を参照してください。
## エンドポイント
```
GET /api/conversations/{conversationId}/outputs/
GET /api/v1/conversations/{conversationId}/outputs/
```
どちらのプレフィックスも登録されており、動作は同じです。`conversationId` は UUID である必要があり、形式が正しくない場合は HTTP 400 が返されます。エンドポイントについては API ドキュメントの[会話の生成ファイル一覧の取得](https://docs.maiagent.ai/api/api-reference/dui-hua-he-xun-xi#conversations-outputs-retrieve)を参照してください。レスポンスのフィールドについては、このページの[レスポンス形式](#response)を基準にしてください。
## 認証と会話の閲覧権限
この API は認証が必要です。有効な認証情報のないリクエストは拒否されます。API Key で連携する場合は、以下を付けてください。
```
Authorization: Api-Key
```
API Key はメンバーに紐づいており、サービスはそのメンバーが所属する組織に基づいて権限を判断します。ログイントークンで呼び出す場合は、組織を指定するために `X-Organization-Id` も付けてください。付けないとメンバーを特定できず、HTTP 404 が返されます。
取得できるかどうかは会話の公開範囲によって決まり、会話の詳細を取得する場合と同じルールが適用されます。
* 組織のオーナーは、組織内の会話を取得できます。
* 一般メンバーは、所属グループが閲覧できる会話、自分に割り当てられた会話、自分が連絡先である会話、自分が開始した会話を取得できます。
* `maigpt_access` 権限を持つメンバーは、グループへの割り当てがなくても、組織の MaiGPT プラットフォームのすべての会話を取得できます。
会話の閲覧権限の全体的な説明は、[会話の閲覧権限とリアルタイムイベント](/tech/ja/api-integration/endpoint-behaviors/conversation-visibility-events.md)を参照してください。
会話が存在しないか削除済みの場合、別の組織に属する場合、呼び出し元が会話を閲覧できない場合は、いずれも HTTP 404 と `{"detail": "..."}` が返されます。会話の存在は明かされません。
## レスポンス形式
```json
{
"count": 2,
"source": "file_library",
"results": [
{
"id": "3f2b7c1e-8a4d-4e21-9c55-1d2e3f4a5b6c",
"name": "quarterly-report.xlsx",
"fileType": "xlsx",
"size": 48213,
"createdAt": "1790000000000",
"canOpenInLibrary": true,
"libraryFolderId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"source": "file_library"
},
{
"id": null,
"name": "chart.png",
"fileType": "image/png",
"size": 10240,
"createdAt": "1789990000000",
"canOpenInLibrary": false,
"libraryFolderId": null,
"source": "container"
}
]
}
```
一覧はすべての項目を一度に返し、ページ分割は行いません。
| フィールド | 説明 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count` | `results` の項目数です |
| `source`（最上位） | `file_library` はファイルライブラリを主な取得元とすることを、`container` は従来のワークスペースから取得することを示します。判定条件は[ファイルライブラリが有効でない場合の動作](#library-disabled)を参照してください |
| `results[].id` | ファイルライブラリのファイルの UUID です。ワークスペースのファイルでは `null` です |
| `results[].name` | ファイル名です |
| `results[].fileType` | ファイルライブラリのファイルでは拡張子です（ドットを含まず、例えば `pdf`）。ワークスペースのファイルではファイル名から推定した MIME タイプで、推定できない場合は `application/octet-stream` です |
| `results[].size` | ファイルサイズです（バイト単位） |
| `results[].createdAt` | 作成日時を Unix epoch のミリ秒で表した文字列です。更新日時のないワークスペースのファイルでは `null` です |
| `results[].canOpenInLibrary` | ユーザーをファイルライブラリに誘導してファイルを開けるかどうかを示します。最上位の `source` が `file_library` の場合のファイルライブラリ項目で、かつ呼び出し元がこの会話のユーザー本人である場合のみ `true` です。ワークスペースの項目、および[ファイルライブラリが有効でない場合](#library-disabled)に統合される動画や画像では、常に `false` です |
| `results[].libraryFolderId` | ファイルライブラリ内でファイルが属するフォルダーの UUID です。`canOpenInLibrary` が `true` になる条件と同じ条件で提供され、それ以外の場合は `null` です |
| `results[].source` | 個々の項目の取得元です。`file_library` または `container` です |
{% hint style="info" %}
`fileType` の形式は取得元によって異なります。ファイルライブラリの項目は拡張子、ワークスペースの項目は MIME タイプです。連携側でファイルの種類を判断する際は、まず `results[].source` を確認してください。
{% endhint %}
## 並び順
並び順は取得経路によって異なります。
* 最上位の `source` が `file_library` の場合、ファイルライブラリの項目は作成日時の新しい順に並びます。[以前の会話](#legacy-conversations)では、ワークスペースのファイルと統合した後、作成日時の新しい順に並べ直し、作成日時のない項目は最後に配置します。
* 最上位の `source` が `container` で、[以前にファイルライブラリに保存された動画や画像](#library-disabled)が統合される場合も、作成日時の新しい順に並べ直し、作成日時のない項目は最後に配置します。
* 最上位の `source` が `container` で、ファイルライブラリの項目が統合されない場合は、ワークスペースの順序をそのまま使用します。作成日時では並べ替えず、フォルダーを先に配置し、その後は名前順に並びます。
## 除外される中間ファイル
ファイルライブラリから取得する場合、一覧には完成したファイルのみを含め、以下の付随ファイルは含めません。
* プレゼンテーションのプレビューとサムネイル：PPTX のプレビュー、PPTX のサムネイル、HTML プレゼンテーションのプレビュー、サムネイル、スクリーンショット、参照用プレビューです。
* コード実行で生成されたファイルのうち、以下のファイル名に一致するものです（大文字と小文字は区別しません）：`deck.pdf`、または `slide-<数字>` もしくは `page-<数字>` で始まる `.jpg`／`.jpeg`／`.png` ファイルです（`-` は `_` でも可）。例えば `slide_3.png` です。
このフィルターはファイルライブラリの項目にのみ適用されます。ワークスペースから取得したファイルには適用されません。
## ファイルライブラリの利用条件
以下の条件をすべて満たす場合、一覧はファイルライブラリを主な取得元とし、最上位の `source` は `file_library` になります。
1. 会話が属する組織でファイルライブラリが有効になっていることです。組織ではデフォルトで無効です。
2. 呼び出し元のロールが `file_library_access` 権限を持っていることです。組織のオーナーは常にこの条件を満たします。
3. 会話の連絡先がプラットフォームのユーザーに対応していることです。例えば、メンバー自身が MaiGPT で開始した会話が該当します。
### 以前の会話
利用条件を満たす場合に、会話に以前のコード実行ワークスペースが残っていると、ワークスペースのファイルとファイルライブラリのファイルを統合して一覧にします。ファイル名が同じ場合は、ファイルライブラリ側のファイルを残します。
### ファイルライブラリが有効でない場合の動作
いずれかの条件を満たさない場合、最上位の `source` は `container` となり、会話のコード実行ワークスペースから一覧を取得します。会話にワークスペースがない場合、`results` は空の配列です。この会話で以前に動画や画像がファイルライブラリに保存されている場合（例えば組織でファイルライブラリが有効だった期間に生成されたファイル）、これらの項目も一覧に統合されます。その項目の `source` は `file_library`、`canOpenInLibrary` は `false` です。
## 匿名アクセス
この API は匿名リクエストを受け付けません。Web Chat などの会話プラットフォームの匿名訪問者は、既存の `GET /api/code-execution-environments/{conversationId}/outputs/` を引き続き使用します。この従来のエンドポイントは認証を行わず、ワークスペースからのみファイルを取得し、ファイルライブラリへの書き込みは行いません。
## ダウンロードとの関係
一覧にはダウンロード URL は含まれません。`source` が `file_library` の項目では、`id` がファイルライブラリのファイル ID です。ファイルライブラリのダウンロードエンドポイントを呼び出して URL を取得できます。
```
GET /api/file-library/files/{id}/download/
```
```json
{"url": "https://storage.example.com/signed-url"}
```
このエンドポイントでは、組織でファイルライブラリが有効であり、呼び出し元がいずれかのファイルライブラリ権限を持っている必要があります。また、呼び出し元が閲覧できるスペース内のファイルのみを取得でき、見つからない場合は HTTP 404 が返されます。ダウンロードできるかどうかは、これらのファイルライブラリ権限とスペースの閲覧範囲によって決まり、`canOpenInLibrary` とは無関係です。ワークスペースの項目は `id` が `null` のため、この方法ではダウンロードできません。
会話単位のダウンロードエンドポイントもあります。権限はこの一覧と同じで、会話を閲覧できればダウンロードでき、ファイルライブラリ権限は不要です。
```
GET /api/v1/conversations/{conversationId}/outputs/{fileId}/download/
```
```json
{"url": "https://storage.example.com/signed-url", "name": "quarterly-report.xlsx"}
```
`fileId` は、この会話で生成され、`source` が `file_library` である項目の `id` である必要があります。ファイルが削除されている場合や署名付き URL を生成できない場合は、HTTP 404 と `{"detail": "File not found or expired"}` が返されます。
### ワークスペースの項目とメッセージ内の `outputs/` パス
`source` が `container` の項目には `id` がありません。ダウンロードにはコード実行ワークスペースのエンドポイントを使い、ファイル名を指定します。
```
GET /api/code-execution-environments/{conversationId}/download_output/?filename=chart.png
```
レスポンスは JSON ではなくファイル本体です（`Content-Type: application/octet-stream`、`Content-Disposition` にファイル名が含まれます）。このエンドポイントは認証を行わず、会話 ID のみで判断し、送信元 IP に基づいてレート制限を適用します。ワークスペースのコンテナが停止している場合はスナップショットから取得し、ワークスペースにもファイルが見つからない場合はファイルライブラリを検索します。
AI の応答テキストに含まれる `outputs/report.docx` のようなパスは、ワークスペースの `/workspace/outputs/` 配下の相対パスであり、そのまま開ける URL ではありません。ファイル名部分（`report.docx`）を取り出して上記の `filename` に渡すか、先にこのページの一覧エンドポイントを呼び出し、`results[].source` に応じてファイルライブラリまたはワークスペースのダウンロードを選択してください。応答の `contentPayload.items` に生成ファイルを列挙する項目が含まれる場合もありますが、連携側では一覧エンドポイントを基準にしてください。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/tech/ja/api-integration/endpoint-behaviors/conversation-outputs-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.