> 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/api_knowledge.md). # Presigned ファイルアップロード方式 Presigned URL を使って MaiAgent にファイルを2段階でアップロードします。署名付き URL を取得してストレージへ直接送信し、その結果をナレッジベースファイルまたは会話の添付ファイルとして登録します。 現在、MaiAgent では次の2か所でファイルのアップロードが必要です 1. ナレッジベースのドキュメントのアップロード 2. メッセージで使用する添付ファイルのアップロード ## Presigned アップロード方式 MaiAgent は **Presigned アップロード方式**に対応しています。この方式では、サーバーを経由せずに、クライアントからクラウドストレージ（S3 など）へファイルを直接アップロードできます。サーバーは安全で有効期限付きの Presigned URL の生成のみを担当し、クライアントはその URL を使って直接アップロードします。 #### 従来のアップロード方式との違い： 1. **データの流れ** * 従来方式：ファイルはサーバーを経由し、サーバーからクラウドストレージへアップロードされます。 * Presigned 方式：クライアントからクラウドへ直接アップロードするため、サーバーでのファイル処理の負担を避けられます。 2. **パフォーマンスとコスト** * 従来方式では、サーバーのリソース消費が過大になり、データ転送コストが増える可能性があります。 * Presigned 方式では、サーバーの負荷が減り、パフォーマンスが向上し、転送コストを削減できます。 3. **セキュリティ** * Presigned URL には署名と有効期限が含まれ、許可されたユーザーだけが指定期間内にアップロードリクエストを実行できます。 この方式は、大きなファイルや頻繁なアップロードに特に適しており、高いセキュリティを維持しながら効率を向上させます。 #### 署名付きアップロードのフロー図 ```mermaid sequenceDiagram participant Client as Client participant Server as Sever participant S3 as Storage(S3) Note over Client,S3: 署名付きアップロードの流れ Client->>+Server: 1. 署名付き URL をリクエストします Note right of Client: POST /api/v1/upload-presigned-url/
ファイル名、種類、サイズを含めます Server->>Server: 2. リクエストパラメータを検証します Server->>Server: 3. 署名付きパラメータを生成します Note right of Server: 有効期限、権限などを設定します Server-->>-Client: 4. 署名付き URL とパラメータを返します Client->>+S3: 5. 署名付き URL で直接アップロードします Note right of Client: 署名付き URL へ POST します
fields の全フィールドとファイルのバイナリを含めます S3-->>-Client: 6. アップロード完了レスポンス (HTTP 204) opt ナレッジベースの場合：ファイルをナレッジベースに登録します Client->>+Server: 7. fields.key で登録します Note right of Client: POST /api/v1/knowledge-bases/{KB_ID}/files/
body に file = fields.key を含めます Server->>Server: 8. KnowledgeBaseFile を作成し、解析をスケジュールします Server-->>-Client: 9. file record を返します end ``` #### 従来のアップロードのフロー図 従来のアップロードはメッセージの添付ファイルにのみ対応しています。`POST /api/v1/attachments-upload/` に multipart フォームを送信し、`file` フィールドにファイルを指定すると、添付ファイルオブジェクトが返されます。ナレッジベースファイルは Presigned 方式でのみアップロードできます。 ```mermaid sequenceDiagram participant Client as Client participant Server as Server participant S3 as Storage(S3) Note over Client,S3: 従来のアップロードの流れ Client->>+Server: 1. ファイルアップロードリクエスト Note right of Client: POST /api/v1/attachments-upload/
multipart フォームの file フィールドにファイルを指定します Server->>Server: 2. ファイルを検証します
(サイズ、種類、形式) Server->>Server: 3. 一時ファイルを保存します Server->>+S3: 4. ファイルを S3 にアップロードします Note right of Server: AWS SDK を使用します
一時ファイルをアップロードします S3-->>-Server: 5. アップロード成功レスポンス Server->>Server: 6. 一時ファイルを削除します Server-->>-Client: 7. アップロード結果を返します Note left of Server: 添付ファイルオブジェクト（id、file など）を返します ``` *** #### Presigned によるファイルのアップロード 以下では、MaiAgent の API を使った Presigned ファイルアップロードの手順を説明します。**ナレッジベースの場合**は Step 1 → 2 → 3 を実行します。**メッセージの添付ファイルの場合**は Step 1 → 2 の後、[メッセージの添付ファイルの作成](#message-attachments)に従って添付ファイルオブジェクトを取得してから、メッセージに含めます。 #### 1. **Presigned URL の取得** **Endpoint** `POST https://api.maiagent.ai/api/v1/upload-presigned-url/` **説明** クライアントはサーバーにリクエストを送信し、クラウドストレージへファイルを直接アップロードするための Presigned URL を取得します。 **リクエストパラメータ** | パラメータ名 | 型 | 必須 | 説明 | | ----------- | --------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `filename` | `string` | はい | アップロードするファイルの名前 | | `modelName` | `string` | はい |

アップロードするファイルの用途を分類するモジュール名です

ナレッジベースには chatbot-file を指定します

メッセージの添付ファイルには attachment を指定します

| | `fieldName` | `string` | はい | ファイルフィールド名です。ナレッジベース（`chatbot-file`）とメッセージの添付ファイル（`attachment`）の両方に `file` を指定します | | `fileSize` | `integer` | はい | ファイルサイズ（バイト単位）です。実際のバイナリサイズと完全に一致しない場合、Step 2 は S3 に拒否されます | **リクエスト例** ```bash curl --location 'https://api.maiagent.ai/api/v1/upload-presigned-url/' \ --header 'Authorization: Api-Key YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "filename": "document.pdf", "modelName": "chatbot-file", "fieldName": "file", "fileSize": 178329 }' ``` **レスポンス例** ```json { "url": "https://s3.ap-northeast-1.amazonaws.com/whizchat-media-prod-django.playma.app", "fields": { "key": "media/chatbots/chatbot-file/86572e41-16ba-45dd-b049-28c69f77ffb0.pdf", "x-amz-algorithm": "AWS4-HMAC-SHA256", "x-amz-credential": "ASIATIVCN4X5XXXXXXXX/20260522/ap-northeast-1/s3/aws4_request", "x-amz-date": "20260522T020727Z", "x-amz-security-token": "IQoJb3JpZ2luX2VjEEoa...（非常に長い STS token）", "policy": "eyJleHBpcmF0aW9uIjog...（base64 policy）", "x-amz-signature": "617e10d1db034ab351d3735de5c56287ecc926dbfe5b5884d2ce67deed363004" } } ``` {% hint style="warning" %} **Production 環境では AWS STS の一時認証情報を使用します**（`x-amz-credential` は `ASIA` で始まります）。レスポンスの `fields` オブジェクトには **`x-amz-security-token`**\*\* フィールドが含まれます\*\*。Step 2 のアップロードでは、すべての `fields` フィールド（`x-amz-security-token` を含む）を省略せずにそのまま送信してください。不足があると S3 に拒否されます。 Presigned URL の**有効期限は約1時間**です。取得後はできるだけ早く使用してください。 {% endhint %} *** #### 2. **クラウドストレージへのファイルのアップロード** **説明** 上記で取得した `url` と `fields` を使って、クラウドストレージへファイルを直接アップロードします。**`fields` オブジェクトのすべてのフィールドを含める必要があります**（`x-amz-security-token` を含みます）。フィールドの一覧をハードコードせず、動的に組み立てることで、AWS が後からフィールドを追加しても漏れを防げます。 **アップロードが成功すると、S3 は HTTP 204 No Content（空の body）を返します**。 {% hint style="info" %} Azure Blob ストレージを使用する環境では、Step 1 のレスポンスに `method: "PUT"` と `headers` も含まれます。PUT を使ってファイル本体を `url` へ直接送信し、`headers` 内のすべてのヘッダーを付けてください。成功時は HTTP 201 が返されます。この場合、`fields` には `key` のみが含まれ、後続の手順でも `fields.key` を使用します。レスポンスに `method` がない場合は、必ず以下の POST 方式でアップロードしてください。 {% endhint %} **リクエスト例（curl、STS token を含む）** ```bash curl --location 'https://s3.ap-northeast-1.amazonaws.com/whizchat-media-prod-django.playma.app' \ --form 'key="media/chatbots/chatbot-file/86572e41-16ba-45dd-b049-28c69f77ffb0.pdf"' \ --form 'x-amz-algorithm="AWS4-HMAC-SHA256"' \ --form 'x-amz-credential="ASIATIVCN4X5XXXXXXXX/20260522/ap-northeast-1/s3/aws4_request"' \ --form 'x-amz-date="20260522T020727Z"' \ --form 'x-amz-security-token="IQoJb3JpZ2luX2VjEEoa..."' \ --form 'policy="eyJleHBpcmF0aW9uIjog..."' \ --form 'x-amz-signature="617e10d1db034ab351d3735de5c56287ecc926dbfe5b5884d2ce67deed363004"' \ --form 'file=@"/path/to/document.pdf"' ``` **リクエスト例（Python、動的な組み立て、推奨）** ```python import requests # Step 1: Presigned URL を取得します presign = requests.post( 'https://api.maiagent.ai/api/v1/upload-presigned-url/', headers={'Authorization': 'Api-Key YOUR_API_KEY'}, json={ 'modelName': 'chatbot-file', 'fieldName': 'file', 'filename': 'document.pdf', 'fileSize': 178329, }, ).json() # Step 2: fields 全体を渡し、すべてのフィールド（x-amz-security-token を含む）を自動的に含めます with open('/path/to/document.pdf', 'rb') as f: s3_response = requests.post( presign['url'], data=presign['fields'], files={'file': f}, ) assert s3_response.status_code == 204, s3_response.text file_key = presign['fields']['key'] # Step 3 で使用する値です ``` *** #### 3. **ナレッジベースへのファイルの登録（ナレッジベースの場合のみ）** **Endpoint** `POST https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/` **説明** Step 2 が完了すると、ファイルのバイナリは S3 に保存されていますが、**まだナレッジベースには登録されていません**。この API を呼び出してアップロード結果を `KnowledgeBaseFile` として登録すると、システムが解析、チャンク分割、インデックス作成を開始します。 {% hint style="warning" %} **`file` フィールドには Step 1 のレスポンスの `fields.key`（MaiAgent S3 内部の相対パス）を指定する必要があり、任意の外部 URL は指定できません**。外部 URL（パートナーシステムのダウンロードリンクなど）がある場合は、先に `GET` でファイルをダウンロードしてから、Step 1 → 2 → 3 を実行してください。 {% endhint %} **パスパラメータ** | パラメータ名 | 型 | 説明 | | ----------------- | -------- | ---------------------- | | `knowledgeBasePk` | `string` | ナレッジベースの一意の識別子（UUID）です | **リクエストパラメータ** | パラメータ名 | 型 | 必須 | 説明 | | ------------------------------- | -------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `files` | `array` | はい | 作成するファイルの一覧です。一度に複数のファイルをまとめて作成できます | | `files[].filename` | `string` | はい | 元のファイル名です | | `files[].file` | `string` | はい | Step 1 のレスポンスの `fields.key`（相対パスであり、**URL ではありません**）です | | `files[].parser` | `string` | いいえ | 使用するパーサーの UUID を指定します。省略すると、PDF、Word（.docx）、PowerPoint（.pptx）はパーサーが自動検出されます（[Parser 解析ツール](/tech/ja/quickstart/parser.md#auto-detect-and-billing)を参照）。その他の形式には、そのファイルタイプのデフォルトパーサーが使用されます | | `files[].labels` | `array` | いいえ | ファイルのラベル（{id, name} オブジェクトの配列）です | | `files[].rawUserDefineMetadata` | `object` | いいえ | ユーザー定義の metadata です | **リクエスト例** ```bash curl --location 'https://api.maiagent.ai/api/v1/knowledge-bases/86401a64-ad89-4847-a709-f4ccfa0af7b9/files/' \ --header 'Authorization: Api-Key YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "files": [ { "filename": "document.pdf", "file": "media/chatbots/chatbot-file/86572e41-16ba-45dd-b049-28c69f77ffb0.pdf" } ] }' ``` **レスポンス例** ```json [ { "id": "86572e41-16ba-45dd-b049-28c69f77ffb0", "filename": "document.pdf", "file": "https://media.maiagent.ai/media/chatbots/chatbot-file/86572e41-16ba-45dd-b049-28c69f77ffb0.pdf", "fileType": "pdf", "knowledgeBase": { "id": "86401a64-ad89-4847-a709-f4ccfa0af7b9", "name": "私のナレッジベース" }, "size": 178329, "status": "initial", "parser": { "id": "535c5b86-0534-4d0a-abfe-82f3d37e769a", "name": "MaiAgent Parser", "provider": "maiagent", "order": 0, "supportsDiarization": false }, "labels": [], "rawUserDefineMetadata": {}, "createdAt": "1779425272000" } ] ``` **ファイルの状態（`status`）** | 値 | 説明 | | ------------ | --------------------- | | `initial` | 作成直後で、処理を待っています | | `processing` | 解析、チャンク分割、インデックス作成中です | | `done` | 処理が完了し、検索できます | | `failed` | 処理に失敗しました | #### メッセージの添付ファイルの作成（メッセージの添付ファイルの場合のみ） メッセージの添付ファイルでは、Step 1 に `"modelName": "attachment"` と `"fieldName": "file"` を指定します。Step 2 のアップロード後、ファイルを会話の添付ファイルとして登録して、添付ファイルオブジェクトを取得します。 **Endpoint** `POST https://api.maiagent.ai/api/v1/conversations/{conversationId}/attachments/` **リクエストパラメータ** | パラメータ名 | 型 | 必須 | 説明 | | ---------- | -------- | --- | ------------------------------------------------------ | | `file` | `string` | はい | Step 1 のレスポンスの `fields.key` です | | `filename` | `string` | はい | 元のファイル名です | | `type` | `string` | いいえ | `image`（画像）、`audio`（音声）、または `other`（その他のファイル、デフォルト値）です | **リクエスト例** ```bash curl --location 'https://api.maiagent.ai/api/v1/conversations/8e44604a-8278-4c96-96b5-3e5a0548d738/attachments/' \ --header 'Authorization: Api-Key YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "file": "media/chat/attachment/0b6f3c2e-6a51-4f43-9d3f-6e2f1c9a7b10.pdf", "filename": "document.pdf", "type": "other" }' ``` **レスポンス例**（HTTP 201） ```json { "id": "5d1f2a7c-3b8e-4c19-9a62-1e4b7f0c8d35", "type": "other", "filename": "document.pdf", "file": "https://…/document.pdf", "expiresAt": null } ``` メッセージを送信するときは、レスポンスの `id`、`type`、`filename`、`file` を添付ファイル配列に含めます。[会話とメッセージの作成](/tech/ja/api-integration/conversations-and-messages.md)の `attachments`、または [completions](/tech/ja/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu.md) の `message.attachments` を使用してください。会話 ID がまだない場合（completions で新しい会話を開始する場合など）は、上記の従来のアップロード `POST /api/v1/attachments-upload/` で添付ファイルオブジェクトを取得できます。 #### メッセージの添付ファイルの処理方法 添付ファイルオブジェクト自体は「アップロード済みのファイル」にすぎません。どのメッセージに紐付けるか、`type` に何を指定するかによって、モデルの読み取り方が決まります。`POST /conversations/{conversationId}/attachments/` と `POST /attachments-upload/` は同じ種類のオブジェクトを作成します。前者は事前に会話に紐付け、後者はメッセージ送信時に紐付けます。その後の処理はまったく同じです。1つの添付ファイルは1つのメッセージにのみ属します。 | `type` | モデルの読み取り方 | 利用可能になるタイミング | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `image`（`.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.bmp`、`.tiff`） | 解析やインデックス作成をせず、画像として Agent の言語モデルに直接送信します。Agent にはマルチモーダル対応モデルが必要です。非対応の場合は「選択した LLM はマルチモーダルに対応していません」と返答します。1回のリクエストでモデルに送信する画像数はプラットフォームの設定によります（デフォルトは20枚）。上限を超えた画像は送信されません | メッセージの送信時です | | `other`（PDF、Word、PowerPoint、Excel／CSV、HTML、TXT／Markdown） | Agent の回答モードによって異なります。**会話モードなどの非 Agent モード**：アップロード時に、この会話専用のファイルを作成し、ナレッジベースのパーサーで解析、チャンク分割、ベクトル化します。回答時はナレッジベースと一緒に検索します（Agent の検索チャンク数の上限を使用します）。全文を prompt に挿入することはありません。**Agent モード**：自動解析は行いません。回答時に Agent が質問に応じて添付ファイルツールを使用します。`parse_attachment_content` は解析後に分割して読み取り、`read_attachment_full_text` はプレーンテキストファイルの全文を読み取り、`ingest_attachment` はインデックスを作成してから検索します（各ツールは Agent の詳細設定で個別に無効化できます）。Excel／CSV は表形式のテキストに変換します | 非 Agent モード：解析完了後です。`waitForAttachments`（completions、デフォルトは `true`）は解析が完了してから回答を開始します。`false` の場合、その回答では添付ファイルをまだ読み取れない可能性があります。Agent モード：メッセージ送信後、Agent が回答時に処理します。`waitForAttachments` は作用しません | | `audio`（`.wav`、`.mp3`、`.m4a`、`.aac`） | 音声認識パーサーで文字起こしを行い、その後は `other` と同じように処理します | 上記と同じです | ナレッジベースファイルとの違い： | | メッセージの添付ファイル | ナレッジベースファイル | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | 範囲 | 同じ会話の後続メッセージでのみ検索できます。ほかの会話からはアクセスできません | そのナレッジベースを利用するすべての Agent と会話です | | 再利用 | 同じ会話では再アップロードは不要です。新しい会話では再アップロードが必要です | 一度アップロードすると永続的に利用できます | | ラベル、メタデータ、クエリメタデータ | ありません | 利用可能です。ラベルとクエリメタデータで範囲を制限できます | | パーサー | 非 Agent モードでは拡張子に応じたデフォルトパーサーを使用します（会話プラットフォームで OCR が有効な場合は画像認識に対応するパーサーを使用します）。Agent モードでは Agent が `parse_attachment_content` で選択します | アップロード時に指定できます | | 保持期間 | プラットフォームの添付ファイル削除設定に従い、期限切れ時に解析済みコピーも含めて自動削除します。ユーザーマニュアルの [Credits 課金制度](https://docs.maiagent.ai/others/credits#attachment-and-derived-storage)を参照してください | 削除するまで保持します | | 削除 | [会話の添付ファイル管理 API](/tech/ja/api-integration/endpoint-behaviors/conversation-attachments.md)（ファイルライブラリの有効化が必要です）を使用するか、期限切れを待ちます | ナレッジベースファイル API を使用します | | 課金 | 解析とベクトル化はナレッジベースの課金規則に従い、ストレージは「会話の添付ファイルストレージ」に計上します | 解析、ベクトル化、ファイルストレージ、ベクトルストレージに課金します | 複数の会話で同じドキュメント群について繰り返し質問する場合は、添付ファイルではなくナレッジベースへアップロードしてください。添付ファイルは、ユーザーの見積書など、一度だけ処理するファイルに使用してください。 *** ## よくあるエラーと対処方法 **Q：S3 が `The AWS Access Key Id you provided does not exist in our records` を返します** A：Step 2 で `x-amz-security-token` が不足しているか、期限切れの access key / S3 endpoint がハードコードされています。必ず Step 1 で取得した最新の `url` と `fields` を使用し、`fields` オブジェクト全体をそのまま Step 2 に渡してください。 **Q：S3 が `Policy Condition failed` を返します** A：通常は、Step 1 の `fileSize` と実際のバイナリサイズが一致していません。実際のファイルサイズを再計算し、Step 1 を再実行してください。 **Q：Step 3 が 400 を返し、`file` フィールドに問題があると表示されます** A：`file` には Step 1 のレスポンスの `fields.key`（例：`media/chatbots/chatbot-file/xxx.pdf`）を指定してください。Step 3 のレスポンスの full URL や任意の外部 URL は指定できません。 **Q：外部 URL（パートナーシステムのダウンロードリンクなど）をすでに持っています。Step 3 に直接渡せますか？** A：できません。Step 3 の `file` フィールドは MaiAgent 自身の S3 内の相対 key です。まず `GET` で外部 URL からファイルをダウンロードし、その後 Step 1 → 2 → 3 を実行してください。 **Q：Step 3 の後もファイルが `status: processing` のままです** A：解析時間はファイルのサイズと種類によって異なり、大きなファイルでは数分かかる場合があります。`GET /api/v1/knowledge-bases/{KB_ID}/files/{file_id}/` で状態をポーリングできます。`done` になると Agent が検索できます。 --- # 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/api_knowledge.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.