> 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/api-integration/endpoint-behaviors/conversation-outputs-api.md).
# 對話產出清單 API
取得某個對話中 AI 產出的文件、圖片、影片與簡報清單。
對話產出清單 API 會列出某個對話中 AI 產出的檔案，例如文件、圖片、影片與 HTML 簡報。組織啟用檔案庫後，清單從檔案庫讀取；未啟用時改讀對話的程式執行工作區。整合端可以用這支 API 呈現「這段對話做出了哪些檔案」。
API 回應的欄位名稱為 camelCase。登入及共通請求方式請參考[快速上手](/tech/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>
```
API Key 綁定一位成員，服務會以該成員所屬的組織判斷權限。若以登入 token 呼叫，請另外帶 `X-Organization-Id` 指定組織，否則服務找不到成員身分，會回應 HTTP 404。
能不能讀取取決於對話可見範圍，規則與讀取對話詳情相同：
* 組織擁有者可讀取組織內的對話。
* 一般成員可讀取其群組可查看的對話，以及指派給自己、自己是聯絡人或自己發起的對話。
* 成員具備 `maigpt_access` 權限時，另可讀取組織 MaiGPT 平台的所有對話，不需要群組分配。
對話可見權限的整體說明見[對話可見權限與即時事件](/tech/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/`，這個舊端點不做身分驗證，只從工作區讀取檔案，且不會把檔案寫入檔案庫。
## 與下載的關係
清單不含下載網址。`source` 為 `file_library` 的項目，`id` 就是檔案庫檔案 ID，可呼叫檔案庫的下載端點取得網址：
```
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`；檔案已被刪除或簽章網址無法產生時回應 HTTP 404 `{"detail": "File not found or expired"}`。
### 工作區項目與訊息中的 `outputs/` 路徑
`source` 為 `container` 的項目沒有 `id`，下載要走程式執行工作區的端點，以檔名指定：
```
GET /api/code-execution-environments/{conversationId}/download_output/?filename=chart.png
```
回應是檔案本體（`Content-Type: application/octet-stream`，`Content-Disposition` 帶檔名），不是 JSON。這支端點不驗證身分，只依對話 ID 判斷，並以來源 IP 限流；工作區容器已停止時改從快照讀取，工作區也找不到時再回頭找檔案庫。
AI 回覆文字裡出現的 `outputs/report.docx` 這類路徑，是檔案在工作區 `/workspace/outputs/` 下的相對路徑，不是可直接開啟的網址：取檔名部分（`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/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.