對話產出清單 API

取得某個對話中 AI 產出的文件、圖片、影片與簡報清單。

對話產出清單 API 會列出某個對話中 AI 產出的檔案，例如文件、圖片、影片與 HTML 簡報。組織啟用檔案庫後，清單從檔案庫讀取；未啟用時改讀對話的程式執行工作區。整合端可以用這支 API 呈現「這段對話做出了哪些檔案」。

API 回應的欄位名稱為 camelCase。登入及共通請求方式請參考快速上手。

端點

GET /api/conversations/{conversationId}/outputs/
GET /api/v1/conversations/{conversationId}/outputs/

兩個前綴都有註冊，行為相同。conversationId 必須是 UUID，格式不正確時回應 HTTP 400。端點見 API 文件列出對話產出檔案，回應欄位以本頁回應格式為準。

認證與對話可見權限

這支 API 需要驗證身分，沒有有效憑證的請求會被拒絕。以 API Key 串接時帶入：

Authorization: Api-Key <您的 API Key>

API Key 綁定一位成員，服務會以該成員所屬的組織判斷權限。若以登入 token 呼叫，請另外帶 X-Organization-Id 指定組織，否則服務找不到成員身分，會回應 HTTP 404。

能不能讀取取決於對話可見範圍，規則與讀取對話詳情相同：

• 組織擁有者可讀取組織內的對話。

• 一般成員可讀取其群組可查看的對話，以及指派給自己、自己是聯絡人或自己發起的對話。

• 成員具備 maigpt_access 權限時，另可讀取組織 MaiGPT 平台的所有對話，不需要群組分配。

對話可見權限的整體說明見對話可見權限與即時事件。

以下情況都回應 HTTP 404 與 {"detail": "..."}，不會透露對話是否存在：對話不存在或已刪除、對話屬於其他組織、或呼叫者看不到這個對話。

回應格式

{
  "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 表示走舊的工作區讀取方式，判斷條件見檔案庫未啟用時的行為
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；工作區項目，以及檔案庫未啟用時合併進來的影片與圖片，一律為 false
results[].libraryFolderId	檔案在檔案庫中的資料夾 UUID；提供條件與 canOpenInLibrary 為 true 的條件相同，其他情況為 null
results[].source	單一項目的來源：file_library 或 container

fileType 的格式依來源而不同：檔案庫項目是副檔名，工作區項目是 MIME 類型。整合端判斷檔案種類時，請先看 results[].source。

排序

排序方式依讀取路徑而不同：

• 最上層 source 為 file_library：檔案庫項目依建立時間由新到舊排列；若是舊對話，與工作區檔案合併後會依建立時間由新到舊重新排序，沒有建立時間的項目排在最後。

• 最上層 source 為 container，且有先前存進檔案庫的影片或圖片合併進來：同樣依建立時間由新到舊重新排序，沒有建立時間的項目排在最後。

• 最上層 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/

{"url": "https://storage.example.com/signed-url"}

這個端點需要組織已啟用檔案庫且呼叫者具備任一檔案庫權限，也只找得到呼叫者可見空間中的檔案；找不到時回應 HTTP 404。能否下載取決於這些檔案庫權限與空間可見性，與 canOpenInLibrary 無關。工作區項目的 id 為 null，無法用這個方式下載。

對話層也有一支下載端點，權限與本清單相同（看得到對話就能下載），不需要檔案庫權限：

GET /api/v1/conversations/{conversationId}/outputs/{fileId}/download/

{"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 中也可能帶有列出產出檔案的項目，整合端以清單端點為準即可。