--- title: "チャットAPI" description: "あなたのマインドとチャット完了やマルチターン会話を通じて対話します。" --- # チャットAPI あなたのマインドにメッセージを送り、AI生成の応答を受け取ります。チャットAPIは、ステートレスな完了とステートフルなマルチターン会話の両方をサポートし、自動的に履歴を管理します。 ## ステートフルチャット（推奨） サーバーが履歴、コンテキスト圧縮、ロールアップサマリーを自動的に管理する永続的な会話を作成します。各リクエストで完全なメッセージ履歴を送信する必要はありません。 ### チャットの作成 マインドにリンクされた新しいステートフル会話を作成します。 **エンドポイント:** `POST /api/v1/chats` **ヘッダー:** ```text Authorization: Bearer minds_your_api_key Content-Type: application/json ``` **リクエストボディ:** ```json { "name": "My Conversation", "sparkId": "your-mind-id" } ```
パラメータ 型 必須 説明
name string いいえ チャットの表示名（デフォルト: "APIチャット"）
sparkId string いいえ チャットするマインド。省略した場合は後でマインドを割り当てます。
description string いいえ オプションの説明
**レスポンス (201):** ```json { "data": { "id": "601af953-3837-49c1-a31e-4fdbfa82ac04", "name": "My Conversation", "description": null, "createdAt": "2026-04-04T12:45:24.078Z", "sparks": [ { "id": "4774888e-0a03-40d7-979b-39b47c4c049c", "name": "Ada Lovelace", "discipline": "mathematician and computer scientist" } ] } } ``` ### メッセージを送信 既存のチャットにメッセージを送信します。サーバーは自動的に会話履歴、コンテキストウィンドウの圧縮、ロールアップサマリーを処理します。 **エンドポイント:** `POST /api/v1/chats/{chatId}/messages` **ヘッダー:** ```text Authorization: Bearer minds_your_api_key Content-Type: application/json ``` **リクエストボディ:** ```json { "content": "What are the latest advancements in solar panel technology?" } ```
パラメータ 型 必須 説明
content string はい メッセージテキスト（代わりに message を使用）
model string いいえ このメッセージのAIモデルをオーバーライドします。 provider と一緒に送信する必要があります。
provider string いいえ モデルオーバーライドのためのAIプロバイダー: openai , anthropic , または google 。 model と一緒に送信する必要があります。
endUserName string|null いいえ このリクエストにおける実際のエンドユーザーの任意の表示名。省略、 null 、または空の場合、Mindsは中立的に呼びかけ、APIキーまたはアカウント所有者から名前を推測しません。別名: userDisplayName , userName 。
ステートフルチャットモデルの選択は、この順序で行われます: リクエストごとのオーバーライド、次にチームの設定された優先プロバイダー、最後に製品のデフォルト。このエンドポイントでは、部分的なオーバーライドは`400 Bad Request`で拒否されます; `model`と`provider`の両方を送信するか、両方を省略してください。 **レスポンス:** ```json { "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency...", "messageId": "cmnkbsddh00033v01ptk9t4et" } ```
フィールド 型 説明
content string マインドの応答
messageId string 保存されたメッセージのユニークID
### マルチターンの例 ステートフルチャットでは、毎回新しいメッセージを送信するだけです。サーバーはすべてを記憶します： ```bash # Step 1: Create a chat CHAT=$(curl -s -X POST "https://getminds.ai/api/v1/chats" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "Research Session", "sparkId": "your-mind-id" }') CHAT_ID=$(echo $CHAT | jq -r '.data.id') # Step 2: Send messages (server manages history automatically) curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "content": "What are the top marketing trends?" }' # Step 3: Follow up (the mind remembers the previous exchange) curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "content": "Which of those would work best on a small budget?" }' ``` **内部の動作:** - すべてのメッセージはデータベースに保存されます - 最後の8メッセージが完全なコンテキストで送信されます - 古いメッセージはロールアップLLMサマリーに圧縮されます - 会話は数週間または数ヶ月にわたってコンテキスト制限に達することなく続けられます --- ## ステートレス完了 単一リクエスト用、または会話履歴を自分で管理したい場合に使用します。 ### メッセージを送信 マインドにメッセージを送り、応答を受け取ります。 **エンドポイント:** `POST /api/v1/minds/{mindId}/completion` **ヘッダー:** ```text Authorization: Bearer minds_your_api_key Content-Type: application/json ``` ### リクエストボディ ```json { "messages": [ { "role": "user", "content": "What are the latest advancements in solar panel technology?" } ] } ``` ### パラメータ
パラメータ 型 必須 説明
messages array いいえ メッセージオブジェクトの配列（ user , assistant , または tool ）。フィールドを完全に省略するか、空の配列を送信して挨拶のブートストラップをトリガーします（下の 初期メッセージ を参照）。
messages[].role string はい "user" , "assistant" , または "tool" のいずれか
messages[].content string はい メッセージテキスト。 user メッセージの場合は空でない文字列である必要があります（空白は 400 で拒否されます）。 tool ロールの場合は省略し、 tool_call_id + content を使用します。
model string いいえ このリクエストで使用するAIモデルをオーバーライドします。詳細は モデルオーバーライド を参照してください。
provider string いいえ モデルオーバーライドのためのAIプロバイダー: openai , anthropic , または google 。可能な場合はモデル名から自動検出されます。
endUserName string|null いいえ このリクエストにおける実際のエンドユーザーの任意の表示名。省略、 null 、または空の場合、Mindsは中立的に呼びかけ、APIキーまたはアカウント所有者から名前を推測しません。別名: userDisplayName , userName 。
language string いいえ 応答言語のヒント。サポートされている言語: en , de , es , fr , zh , tr , ar , ja , ko 。強いペルソナ（例: 固定された母国語を持つ公人のクローン）は、ペルソナの言語で応答し続ける場合があります。
generateImage boolean いいえ true の場合、文脈に応じて応答でAI画像生成を有効にします
response_format object いいえ 構造化された出力をリクエストします。詳細は 構造化出力 を参照してください。
tools array いいえ ユーザー定義のツール定義の配列。詳細は ツール呼び出し を参照してください。
tool_choice string|object いいえ ツール呼び出しの動作を制御します。詳細は ツール選択モード を参照してください。
parallel_tool_calls boolean いいえ 各ターンで複数のツール呼び出しを許可します（デフォルト: true ）。
### レスポンス ```json { "messageId": "msg_550e840029b141d4a716446655440000", "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency, bifacial panels that capture light from both sides, and integrated storage systems...", "metadata": { "ragCitations": [ { "id": "abc123", "displaySource": "Mind knowledge", "similarity": 0.89 } ] } } ```
フィールド 型 説明
messageId string トラッキング用のユニークなメッセージ識別子
content string マインドの応答テキスト（構造化出力を使用している場合はJSON文字列）
parsed object 解析されたJSONオブジェクト（ response_format を使用している場合のみ存在）
tool_calls array ツール呼び出しリクエストの配列（ユーザー定義のツールが呼び出された場合のみ存在）。各ツールには: id , name , arguments があります
metadata object オプションのメタデータ（引用、画像）
metadata.ragCitations array 応答で使用された知識ソースとウェブ検索結果
## 単一メッセージの例 単一の質問をする： ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "What are the top 3 marketing trends for 2025?" } ] }' ``` ## マルチターン会話 以前のメッセージを含めて会話のコンテキストを維持します： ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "What are the top marketing trends?" }, { "role": "assistant", "content": "The top trends are AI personalization, short-form video, and community building..." }, { "role": "user", "content": "How can I implement AI personalization on a budget?" } ] }' ``` **マルチターン会話のヒント:** - 各リクエストに完全な会話履歴を含める - 順序が重要: メッセージは時系列であるべき - `user`と`assistant`ロールを交互に使用する - 最後のメッセージは常に`user`からであるべき ## ファイル添付 ファイル、文書、画像、リンクを添付して、Mindsにコンテキストを提供します。Mindsは処理されたコンテンツを会話の一部として受け取ります。 ### ファイルの添付 ユーザーメッセージの`metadata.attachedFiles`配列を介してファイルを追加します： ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "Please review this document and summarize the key points", "metadata": { "attachedFiles": [ { "url": "https://example.com/quarterly-report.pdf", "name": "Q4 2025 Report", "type": "application/pdf" }, { "path": "uploads/meeting-notes.docx", "name": "Strategy Meeting Notes" } ] } } ] }' ``` ### 添付形式 各添付オブジェクトは次のことをサポートします：
フィールド 型 必須 説明
url string いいえ* ファイルへの外部URL（HTTP/HTTPS）
path string いいえ* Supabaseストレージパス（自動署名）
name string いいえ ファイルの表示名
type string いいえ MIMEタイプ（例: application/pdf , image/png ）
description string いいえ オプションの説明
transcription string いいえ 事前に転写された音声/ビデオコンテンツ
**注意:** `url`または`path`のいずれかを提供してください。両方は不可です。 ### サポートされているファイルタイプ **文書:** - PDF (`.pdf`) - テキスト抽出 + スキャンページのOCR - Word (`.docx`) - 完全なテキスト抽出 - テキスト (`.txt`, `.md`) - 直接のテキストコンテンツ - CSV/Excel (`.csv`, `.xlsx`) - テーブル抽出 **画像:** - PNG, JPG, WEBP - OCR + ビジュアル分析 - 画像理解のためのビジョン機能 **外部URL:** - Firecrawlで取得されたウェブページ（JSレンダリング + スクリーンショット） - 自動マークダウン変換 ### 処理 ファイルはマインドに送信される前に自動的に処理されます： 1. **ダウンロード** - URLまたはSupabaseストレージからファイルを取得 2. **抽出** - コンテンツを抽出（PDFからのテキスト、画像からのOCRなど） 3. **注入** - 処理されたコンテンツが会話のコンテキストに追加されます 4. **応答** - マインドはあなたのメッセージとファイルコンテンツの両方を確認します **処理制限:** - タイムアウト: 1ファイルあたり30秒 - ファイルは並行して処理されます - 失敗したファイルには優雅なフォールバックメッセージが表示されます ### 複数ファイルの例 ```json { "messages": [ { "role": "user", "content": "Compare these two proposals and recommend which one to pursue", "metadata": { "attachedFiles": [ { "url": "https://example.com/proposal-a.pdf", "name": "Proposal A - Cloud Migration", "type": "application/pdf" }, { "url": "https://example.com/proposal-b.pdf", "name": "Proposal B - On-Prem Upgrade", "type": "application/pdf" }, { "path": "uploads/budget-analysis.xlsx", "name": "Budget Comparison" } ] } } ] } ``` ### 会話履歴におけるファイル添付 ファイル添付を伴う会話を続ける際は、履歴に添付された元のメッセージを含めてください： ```json { "messages": [ { "role": "user", "content": "Analyze this sales data", "metadata": { "attachedFiles": [ { "url": "https://example.com/sales-q4.csv", "name": "Q4 Sales Data" } ] } }, { "role": "assistant", "content": "Based on the Q4 sales data, I can see that revenue increased by 23% compared to Q3..." }, { "role": "user", "content": "What were the top 3 performing products?" } ] } ``` **注意:** ファイルは最初に添付されたときにのみ処理されます。同じ会話内の後続メッセージは、すでに処理されたコンテンツを参照します。 ### ウェブリンク ウェブページや外部コンテンツには、`url`フィールドを使用します： ```json { "messages": [ { "role": "user", "content": "Summarize the key findings from this research paper", "metadata": { "attachedFiles": [ { "url": "https://arxiv.org/pdf/2103.12345.pdf", "name": "AI Research Paper", "type": "application/pdf" } ] } } ] } ``` **特にウェブページの場合:** - JavaScriptが多用されるサイトはFirecrawlでレンダリングされます - ビジュアルコンテキストのためにスクリーンショットがキャプチャされます - コンテンツはクリーンなマークダウンに変換されます ### エラーハンドリング ファイル処理が失敗した場合: - マインドはファイルが添付されたが処理が失敗したことを示すフォールバックメッセージを受け取ります - 会話は通常通り続きます - タイムアウトエラーは`[Processing timeout - file may be too large]`を表示します - その他のエラーは`[Processing failed - file uploaded but analysis unavailable]`を表示します これにより、マインドは処理が失敗しても試みられた添付について認識します。 ## 初期メッセージ（挨拶） 空のメッセージ配列またはメッセージがない場合、マインドが自己紹介をします： ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [] }' ``` レスポンス: ```json { "content": "Hi! I'm Sarah, a marketing director with 15 years of experience in B2B SaaS. I specialize in growth marketing and data-driven strategies. What can I help you with today?" } ``` ## モデルオーバーライド ステートレス完了リクエストで使用されるAIモデルをオプションでオーバーライドするには、`model`パラメータを渡します。これはベンチマーク、コスト最適化、または異なるモデルの動作をテストするのに便利です。ステートフルチャットとパネルエンドポイントは、より厳格なオーバーライド検証を使用します: `model`と`provider`の両方を一緒に送信してください。 ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "What are your thoughts on sustainable packaging?" } ], "model": "gpt-4o-mini" }' ``` `model`が指定されていない場合、サーバーのデフォルトが使用されます。 ### プロバイダー
プロバイダー 値 例モデル
OpenAI openai gpt-5.6-sol , gpt-5.6-terra , gpt-5.6-luna , gpt-5.4 , gpt-5-mini , gpt-4o , gpt-4o-mini , o3 , o3-pro , o3-mini , o4-mini
Anthropic anthropic claude-fable-5 , claude-opus-5 , claude-sonnet-5 , claude-haiku-4-5-20251001
Google google gemini-3.7-flash , gemini-3.5-flash-lite
プロバイダーによってサポートされている任意のモデル文字列を渡すことができます。プロバイダーは一般的なモデル名のプレフィックスから自動検出されます（`claude-` → Anthropic、`gemini-` → Google、`gpt-`/`o1`/`o3`/`o4` → OpenAI）。 曖昧な名前のモデルについては、`provider`を明示的に指定してください： ```json { "messages": [...], "model": "my-custom-fine-tune", "provider": "openai" } ``` プロバイダーが特定できない場合、APIは`400 Bad Request`エラーを返し、指定するように求めます。 ## 構造化出力 特定のスキーマに一致するJSONレスポンスを保証するために、`response_format`パラメータを使用してリクエストします。これはOpenAIスタイルの構造化出力パターンに従い、会話から構造化データを抽出するのに便利です。 ### JSONスキーマモード モデルにスキーマに一致する有効なJSONを出力させます： ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!" } ], "response_format": { "type": "json_schema", "json_schema": { "name": "sentiment_analysis", "description": "Sentiment analysis result", "schema": { "type": "object", "properties": { "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": ["sentiment", "confidence", "keywords"] } } } }' ``` レスポンス: ```json { "content": "{\"sentiment\": \"positive\", \"confidence\": 0.95, \"keywords\": [\"love\", \"exceeded\", \"expectations\"]}", "parsed": { "sentiment": "positive", "confidence": 0.95, "keywords": ["love", "exceeded", "expectations"] } } ``` ### JSONオブジェクトモード スキーマ検証なしでJSON出力を強制します： ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "List 3 marketing ideas as JSON" } ], "response_format": { "type": "json_object" } }' ``` ### レスポンス形式タイプ
タイプ 説明
text デフォルトのテキスト出力（現在の動作）
json_object スキーマ検証なしで有効なJSON出力を強制
json_schema 提供されたスキーマに一致するJSON出力を強制
### JSONスキーマフィールド
フィールド 型 必須 説明
name string はい スキーマの識別子
description string いいえ スキーマが表す内容の説明
schema object はい JSONスキーマ定義
strict boolean いいえ 厳密なスキーマ遵守を強制します（デフォルト: true ）
### サポートされているスキーマ機能 次のJSONスキーマ機能がサポートされています： - **タイプ**: `string`, `number`, `integer`, `boolean`, `array`, `object`, `null` - **制約**: `enum`, `minimum`, `maximum`, `minLength`, `maxLength`, `minItems`, `maxItems` - **構造**: `properties`, `required`, `items`, `additionalProperties` - **メタデータ**: `description`（モデルをガイドするために使用） ### 注意事項 - ツール（RAG、ウェブ検索など）は構造化出力で機能します , マインドは構造化応答を生成する前に知識ベースを検索できます - `parsed`フィールドには便利な解析されたJSONオブジェクトが含まれ、`content`には生のJSON文字列が含まれます - すべての主要プロバイダー（OpenAI、Anthropic、Google）は構造化出力をサポートしています - 複雑なスキーマの場合、モデルの出力をガイドするために`description`フィールドを追加することを検討してください ## ツール呼び出し マインドが会話中にカスタム関数を呼び出せるようにします。これはOpenAI互換の関数呼び出しパターンに従い、外部ツールやAPIでマインドの機能を拡張できます。 ### 仕組み 1. **ツールを定義**: 名前、説明、JSONスキーマパラメータを持つツール定義を渡します 2. **マインドが決定**: マインドは会話に基づいてツールを呼び出すタイミングを決定します（または`tool_choice`で強制します） 3. **APIがツール呼び出しを返す**: レスポンスには`tool_calls`が含まれ、ツール名と生成された引数が含まれます 4. **ツールを実行**: アプリケーションでツールを実行し、結果を取得します 5. **結果を返送**: 次のメッセージにツール結果を含め、`role: "tool"`を使用します 6. **マインドが応答**: マインドはツール結果を最終応答に組み込みます ### 基本的な例 **ツールを使用したリクエスト:** ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "What is the weather in Berlin?" } ], "tools": [ { "name": "get_weather", "description": "Get current weather for a city", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "City name" }, "units": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "Temperature units" } }, "required": ["city"] } } ] }' ``` **レスポンス:** ```json { "content": "", "tool_calls": [ { "id": "call_abc123", "name": "get_weather", "arguments": { "city": "Berlin", "units": "celsius" } } ] } ``` **ツールを実行し、結果を返送:** ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "What is the weather in Berlin?" }, { "role": "assistant", "content": "", "tool_calls": [ { "id": "call_abc123", "name": "get_weather", "arguments": { "city": "Berlin", "units": "celsius" } } ] }, { "role": "tool", "tool_call_id": "call_abc123", "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}" } ], "tools": [ { "name": "get_weather", "description": "Get current weather for a city", "parameters": { "type": "object", "properties": { "city": { "type": "string" }, "units": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["city"] } } ] }' ``` **最終レスポンス:** ```json { "content": "The current weather in Berlin is 18°C and partly cloudy, with 65% humidity." } ``` ### ツール定義スキーマ 各ツールは次の構造に従う必要があります： ```json { "name": "tool_name", "description": "Clear description of when and how to use this tool", "parameters": { "type": "object", "properties": { "param1": { "type": "string", "description": "What this parameter does" } }, "required": ["param1"] }, "strict": true } ``` **必須フィールド:**
フィールド 型 説明
name string 関数名。ユニークでなければならず、内部ツールと衝突してはなりません。
description string ツールが何をするか、いつ使用するかの明確な説明。これはマインドのツール選択をガイドします。
parameters object 関数引数を定義するJSONスキーマ。
**オプションフィールド:**
フィールド 型 デフォルト 説明
strict boolean true 引数の厳密なスキーマ検証を強制します。
### ツール選択モード `tool_choice`パラメータを使用して、マインドがツールを呼び出すタイミングと方法を制御します：
値 動作
"auto" マインドがツールを呼び出すかどうかを決定します（デフォルト）
"required" マインドは応答する前に少なくとも1つのツールを呼び出す必要があります
"none" このターンのツール呼び出しを無効にします
{"name": "tool_name"} マインドに特定のツールを呼び出すよう強制します
**例:** ```json // Let the mind decide { "messages": [...], "tools": [...], "tool_choice": "auto" } // Force a specific tool { "messages": [...], "tools": [...], "tool_choice": { "name": "search_database" } } // Require at least one tool call { "messages": [...], "tools": [...], "tool_choice": "required" } ``` ### 並行ツール呼び出し デフォルトでは、マインドは効率のために単一ターンで複数のツールを呼び出すことができます： ```json { "content": "", "tool_calls": [ { "id": "call_1", "name": "get_customer", "arguments": { "id": "CUST-001" } }, { "id": "call_2", "name": "get_customer", "arguments": { "id": "CUST-002" } } ] } ``` 並行呼び出しを無効にし、逐次実行を強制するには： ```json { "messages": [...], "tools": [...], "parallel_tool_calls": false } ``` ### ツールメッセージ形式 ツール結果を返送する際は、`tool`ロールを使用します： ```json { "role": "tool", "tool_call_id": "call_abc123", "content": "{\"result\": \"success\", \"data\": {...}}" } ```
フィールド 型 必須 説明
role string はい "tool" でなければなりません
tool_call_id string はい アシスタントの応答におけるツール呼び出しからの id
content string はい ツール実行結果（通常はJSON文字列）
### 内部ツールとユーザー工具 Mindsには自動的に実行されるサーバーサイドの組み込みツールがあります：
内部ツール 目的
GET_SPARK_RAG マインドの知識ベースを検索
WEB_SEARCH ウェブを検索
GENERATE_IMAGE AIで画像を生成
DISPLAY_IMAGE マインドの記憶から画像を表示
DOCUMENT_PROCESSING アップロードされたファイルを分析
ANALYZE_LINK ウェブURLを取得して分析
**主な違い:** - **内部ツール**: サーバーサイドで実行され、結果は`content`と`metadata`に含まれます。`tool_calls`には決して返されません。 - **ユーザー工具**: あなたが実行するために`tool_calls`に返されます。結果は`tool`メッセージとして返送する必要があります。 内部ツールをオーバーライドまたは無効にすることはできません。ユーザー工具は**追加的**であり、マインドの機能を拡張します。 ### 完全なマルチツール例 複数のカスタムツールを持つ法務アシスタントマインド： ```bash curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \ -H "Authorization: Bearer minds_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "Create a new case for Schmidt vs. Mueller and search for similar precedents" } ], "tools": [ { "name": "create_case", "description": "Create a new legal case in the system", "parameters": { "type": "object", "properties": { "title": { "type": "string", "description": "Case title (parties involved)" }, "practice_area": { "type": "string", "enum": ["corporate", "litigation", "employment", "ip"], "description": "Legal practice area" }, "client_id": { "type": "string", "description": "Client identifier" } }, "required": ["title", "practice_area"] } }, { "name": "search_precedents", "description": "Search legal database for similar cases", "parameters": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "Search keywords" }, "practice_area": { "type": "string", "description": "Filter by practice area" }, "max_results": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of results" } }, "required": ["keywords"] } } ], "parallel_tool_calls": true }' ``` **並行ツール呼び出しを伴うレスポンス:** ```json { "content": "", "tool_calls": [ { "id": "call_1", "name": "create_case", "arguments": { "title": "Schmidt vs. Mueller", "practice_area": "litigation" } }, { "id": "call_2", "name": "search_precedents", "arguments": { "keywords": ["Schmidt", "Mueller"], "practice_area": "litigation", "max_results": 10 } } ] } ``` ### ベストプラクティス 1. **明確な説明を書く**: `description`フィールドは重要です。各ツールをいつ、なぜ使用するかを具体的に記述してください。```json ❌ "description": "データベースを検索" ✅ "description": "キーワードと実務分野に基づいて類似のケースを検索するための法的先例データベースを検索" ``` 2. **パラメータの説明を使用**: 各パラメータが何をするかをマインドに理解させます。```json "case_id": { "type": "string", "description": "CASE-YYYY-NNNN形式のユニークなケース識別子" } ``` 3. **制約値のために列挙型を活用**:```json "status": { "type": "string", "enum": ["pending", "active", "closed", "archived"] } ``` 4. **検証制約を設定**:```json "priority": { "type": "integer", "minimum": 1, "maximum": 5, "description": "優先度レベル（1=最低、5=最高）" } ``` 5. **厳密モードを有効にする**: `strict: true`（デフォルト）を維持して、マインドが有効な引数を生成するようにします。 6. **構造化されたツール結果を返す**: ツール結果をJSON形式で使用して、解析を容易にします：```json { "role": "tool", "tool_call_id": "call_123", "content": "{\"success\": true, \"case_id\": \"CASE-2026-001\", \"created_at\": \"2026-03-30T23:00:00Z\"}" } ``` 7. **エラーを優雅に処理する**: ツール結果にエラーの詳細を返します：```json { "role": "tool", "tool_call_id": "call_123", "content": "{\"success\": false, \"error\": \"ケースはすでに存在します\", \"error_code\": \"DUPLICATE_CASE\"}" } ``` ### 制限事項 - **リクエストごとに最大128ツール** - ツール名はユニークでなければならず、内部ツール名と衝突してはなりません - ツール実行はクライアント側で行われます , ツールの実行とセキュリティはあなたの責任です - ツール結果はマインドが応答するために会話履歴に返送される必要があります ### JSONスキーマサポート `parameters`フィールドは標準のJSONスキーマ機能をサポートします： **タイプ:** - `string`, `number`, `integer`, `boolean`, `array`, `object`, `null` **検証:** - `enum` , 特定の値に制限 - `minimum`, `maximum` , 数値の範囲 - `minLength`, `maxLength` , 文字列の長さ - `minItems`, `maxItems` , 配列のサイズ - `pattern` , 正規表現の検証 - `format` , 文字列形式（例: `"date-time"`, `"email"`, `"uri"`） **構造:** - `properties` , オブジェクトプロパティ - `required` , 必須フィールド - `items` , 配列アイテムスキーマ - `additionalProperties` , 追加プロパティの許可/不許可 **高度な検証を伴う例:** ```json { "name": "schedule_meeting", "description": "Schedule a meeting with a client", "parameters": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "date": { "type": "string", "format": "date-time", "description": "Meeting date and time in ISO 8601 format" }, "attendees": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 20 }, "duration_minutes": { "type": "integer", "minimum": 15, "maximum": 480, "description": "Meeting duration (15-480 minutes)" } }, "required": ["title", "date", "attendees"] } } ``` ## 仕組み ### 1. コンテキストの読み込み メッセージを送信すると、マインドは： - システムプロンプトと設定を読み込みます - **関連情報を自動的に知識ベースから検索**します - 会話履歴を考慮します ### 2. 処理 マインドは： - あなたのメッセージをコンテキストで分析します - **取得した知識に基づいて応答を生成**し、引用を含めます - 必要に応じて追加のツール（ウェブ検索、画像生成など）にアクセスします - 自身の個性に沿った応答を形成します ### 3. 応答生成 マインドは： - 専門知識を反映した応答を生成します - 知識ベースやウェブソースを使用する際には**引用を含めます** - オプションのメタデータ（引用、画像など）を含むメッセージを返します ## メタデータ レスポンスには追加のメタデータを含めることができます： ### 画像 マインドが画像を生成または表示する場合： ```json { "content": "Here are some logo concepts...", "metadata": { "images": [ { "id": "img_123", "url": "https://...", "filename": "Logo Concept 1", "description": "Modern minimalist logo with blue gradient", "source": "generated" } ] } } ``` ### 知識引用 マインドが知識ベースやウェブ検索から情報を取得する場合： ```json { "content": "Based on recent research, solar panel efficiency has improved significantly...", "metadata": { "ragCitations": [ { "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949", "displaySource": "Mind knowledge", "similarity": 0.85 }, { "id": "external-web-123", "displaySource": "https://example.com/solar-research", "similarity": 0.92 } ] } } ``` **引用フィールド:** - `id` - ソースのユニーク識別子 - `displaySource` - 人間が読めるソース名またはURL - `similarity` - クエリに対するソースの適合度を示す関連スコア（0-1） Mindsは応答する前に自動的に知識ベースを検索し、特定のソースに基づいて回答を根拠づける際には引用を含めます。 ## アクセス制御 あなたは以下のMindsとチャットできます： - **所有** - あなたが作成したMinds - **アクセス権がある** - チームメンバーによって共有されたMinds - **メンバーである** - あなたが所属するチームワークスペース内のMinds - **公開Minds** - 公開でアクセス可能なMinds 無許可のマインドにアクセスしようとすると、次のようになります： ```json { "statusCode": 403, "statusMessage": "Access denied" } ``` ## レスポンス形式 ### テキストレスポンス ほとんどのレスポンスはプレーンテキストです： ```json { "content": "Based on current trends, I recommend focusing on..." } ``` ### 構造化レスポンス 一部のマインドは構造化されたコンテンツを返す場合があります： ```json { "content": "Here's my analysis:\n\n1. Trend: AI Personalization\n - Impact: High\n - Timeline: 6-12 months\n\n2. Trend: Short-form Video\n - Impact: Very High\n - Timeline: Immediate" } ``` ### メタデータのみの空レスポンス 時にはメタデータのみが返されることがあります（例: 画像生成の場合）： ```json { "content": "", "metadata": { "images": [...] } } ``` ## ベストプラクティス ### 具体的にする ```text ❌ "Tell me about marketing" ✅ "What are the most cost-effective digital marketing channels for a B2B SaaS startup with a $5K monthly budget?" ``` ### コンテキストを提供する ```text ✅ "We're launching a sustainable fashion brand targeting Gen Z. What social media strategy would you recommend?" ``` ### フォローアップを使用する 会話メモリを活用してください： ```text User: "What are the top trends?" Assistant: "The top trends are..." User: "Which of these would work best for a small budget?" Assistant: "For a small budget, I'd focus on..." ``` ### 知識を参照する アップロードした知識を参照してください： ```text ✅ "Based on our brand guidelines, what tone should we use for this campaign?" ``` ## エラーレスポンス ### 400 Bad Request スパークIDが欠落または無効です： ```json { "statusCode": 400, "statusMessage": "Mind ID is required" } ``` サポートされていないプロバイダー： ```json { "statusCode": 400, "statusMessage": "Unsupported provider: 'invalid'. Supported providers: openai, anthropic, google." } ``` プロバイダーなしの曖昧なモデル名： ```json { "statusCode": 400, "statusMessage": "Cannot auto-detect provider for model 'my-model'. Please specify a 'provider' parameter (openai, anthropic, or google)." } ``` ### 401 Unauthorized 無効なAPIキー。 ### 403 Forbidden スパークへのアクセスが拒否されました： ```json { "statusCode": 403, "statusMessage": "Access denied" } ``` ### 404 Not Found スパークが存在しません： ```json { "statusCode": 404, "statusMessage": "Mind not found" } ``` ## 使用ノート - v1 APIは認証済みアカウントごとの設定可能な制限（既定で1分あたり300リクエスト）を適用します - `RateLimit-Limit`と`RateLimit-Remaining`を読み、`429`後は`Retry-After`に従ってください - 生成処理は負荷が高いため、並列completion数を制限してください ## 次のステップ - [レイテンシとパフォーマンス](/docs/api/latency)を理解する - [エラーとレート制限](/docs/api/errors)について学ぶ - 最初の[マインド](/docs/api/minds)を作成する - 応答を向上させるために[知識](/docs/api/knowledge)をアップロードする - [API概要](/docs/api/overview)を読む