会話の生成物一覧 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 Key で連携する場合は、次のヘッダーを指定します。

Authorization: Api-Key <ご自身の API Key>

API Key は 1 人のメンバーに紐付けられ、サービスはそのメンバーが所属する組織に基づいて権限を判定します。ログイントークンで呼び出す場合は、組織を指定する X-Organization-Id も含めてください。指定しないと、サービスはメンバーを特定できず、HTTP 404 を返します。

読み取り可否は会話の閲覧範囲によって決まり、会話の詳細を読み取る場合と同じ規則が適用されます。

• 組織のオーナーは、組織内の会話を読み取れます。

• 一般メンバーは、自分のグループが閲覧できる会話に加え、自分に割り当てられた会話、自分が連絡先になっている会話、自分が開始した会話を読み取れます。

• maigpt_access 権限を持つメンバーは、グループへの割り当てがなくても、組織の MaiGPT プラットフォーム上のすべての会話を読み取れます。

会話の閲覧権限の全体像については、会話の閲覧権限とリアルタイムイベントを参照してください。

会話が存在しないか削除された場合、別の組織に属する場合、または呼び出し元に閲覧権限がない場合は、いずれも {"detail": "..."} とともに HTTP 404 を返します。会話が存在するかどうかは明らかにしません。

レスポンス形式

{
  "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 エポックからのミリ秒を表す文字列。ワークスペース内のファイルに更新日時がない場合は 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 のプレビューとサムネイル、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/

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

このエンドポイントを使用するには、組織のファイルライブラリが有効で、呼び出し元にいずれかのファイルライブラリ権限が必要です。また、呼び出し元に見えるスペース内のファイルのみを検索し、見つからない場合は HTTP 404 を返します。ダウンロードの可否はこれらのファイルライブラリ権限とスペースの閲覧範囲によって決まり、canOpenInLibrary とは関係ありません。ワークスペース内の項目は id が null であるため、この方法ではダウンロードできません。