> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

> POST /ai/askエンドポイントを使用して、Boxに保存されている1つ以上のファイルについて質問します。

# Box AIに質問する

export const MultiRelatedLinks = ({sections = []}) => {
  if (!sections || sections.length === 0) {
    return null;
  }
  return <div className="space-y-8">
      {sections.map((section, index) => <RelatedLinks key={index} title={section.title} items={section.items} />)}
    </div>;
};

export const RelatedLinks = ({title, items = []}) => {
  const getBadgeClass = badge => {
    if (!badge) return "badge-default";
    const badgeType = badge.toLowerCase().replace(/\s+/g, "-");
    return `badge-${badge === "ガイド" ? "guide" : badgeType}`;
  };
  if (!items || items.length === 0) {
    return null;
  }
  return <div className="my-8">
      {}
      <h3 className="text-sm font-bold uppercase tracking-wider mb-4">{title}</h3>

      {}
      <div className="flex flex-col gap-3">
        {items.map((item, index) => <a key={index} href={item.href} className="py-2 px-3 rounded related_link hover:bg-[#f2f2f2] dark:hover:bg-[#111827] flex items-center gap-3 group no-underline hover:no-underline border-b-0">
            {}
            <span className={`px-2 py-1 rounded-full text-xs font-semibold uppercase tracking-wide flex-shrink-0 ${getBadgeClass(item.badge)}`}>
              {item.badge}
            </span>

            {}
            <span className="text-base">{item.label}</span>
          </a>)}
      </div>
    </div>;
};

export const Link = ({href, children, className, ...props}) => {
  const localizedHref = localizeLink(href);
  return <a href={localizedHref} className={className} {...props}>
      {children}
    </a>;
};

<Note>
  Box AI APIは、Business以上をご利用のすべてのお客様が利用できます。
</Note>

Box AI APIを使用すると、指定した1ファイルまたは一連のファイルについて質問し、そのコンテンツに基づいた応答を得ることができます。たとえば、Boxでドキュメントを表示している場合に、Box AIに対して、コンテンツの要約を求めることができます。

このほか、<Link href="/guides/hubs-api/index">Box Hub</Link>に質問することもできます。項目としてHubを渡した場合、Box AIはHub内のインデックスが作成されたコンテンツを検索し、厳選されたドキュメントに基づいた回答を返します。詳細については、<Link href="#ask-questions-about-a-hub">Hubについて質問する</Link>を参照してください。

## 開始する前に

Platformアプリを作成して認証するには、<Link href="/guides/box-ai/ai-tutorials/prerequisites">Box AIの使い方</Link>に記載されている手順に従っていることを確認してください。

## リクエストの送信

質問を含むリクエストを送信するには、`POST /2.0/ai/ask`エンドポイントを使用し、必須のパラメータを指定します。

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
       -H "content-type: application/json" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -d '{
           "mode": "single_item_qa",
           "prompt": "What is the value provided by public APIs based on this document?",
           "items": [
              {
              "type": "file",
              "id": "9842787262"
              }
           ],
           "dialogue_history": [
                {
                "prompt": "Make my email about public APIs sound more professional",
                "answer": "Here is the first draft of your professional email about public APIs",
                "created_at": "2013-12-12T10:53:43-08:00"
                }
            ],
            "include_citations": true,
            "ai_agent": {
              "type": "ai_agent_ask",
              "long_text": {
                "model": "openai__gpt_5_mini",
                "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
              },
              "basic_text": {
                "model": "openai__gpt_5_mini",
             }
           }
        }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.ai.createAiAsk({
    mode: 'single_item_qa' as AiAskModeField,
    prompt: 'which direction sun rises',
    items: [
      {
        id: fileToAsk.id,
        type: 'file' as AiItemAskTypeField,
        content: 'Sun rises in the East',
      } satisfies AiItemAsk,
    ],
    aiAgent: aiAskAgentConfig,
  } satisfies AiAsk);
  ```

  ```python Python v10 theme={null}
  client.ai.create_ai_ask(
      CreateAiAskMode.SINGLE_ITEM_QA,
      "which direction sun rises",
      [
          AiItemAsk(
              id=file_to_ask.id,
              type=AiItemAskTypeField.FILE,
              content="Sun rises in the East",
          )
      ],
      ai_agent=ai_ask_agent_config,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Ai.CreateAiAskAsync(requestBody: new AiAsk(mode: AiAskModeField.SingleItemQa, prompt: "which direction sun rises", items: Array.AsReadOnly(new [] {new AiItemAsk(id: fileToAsk.Id, type: AiItemAskTypeField.File) { Content = "Sun rises in the East" }})));
  ```

  ```swift Swift v10 theme={null}
  try await client.ai.createAiAsk(requestBody: AiAsk(mode: AiAskModeField.singleItemQa, prompt: "which direction sun rises", items: [AiItemAsk(id: fileToAsk.id, type: AiItemAskTypeField.file, content: "Sun rises in the East")]))
  ```

  ```java Java v10 theme={null}
  client.getAi().createAiAsk(new AiAsk.Builder(AiAskModeField.SINGLE_ITEM_QA, "which direction sun rises", Arrays.asList(new AiItemAsk.Builder(fileToAsk.getId(), AiItemAskTypeField.FILE).content("Sun rises in the East").build())).aiAgent(aiAskAgentConfig).build())
  ```

  ```java Java v5 theme={null}
  BoxAIResponse response = BoxAI.sendAIRequest(
      api,
      "What is the content of the file?",
      Collections.singletonList("123456", BoxAIItem.Type.FILE),
      BoxAI.Mode.SINGLE_ITEM_QA
  );
  ```

  ```python Python v4 theme={null}
  items = [{
      "id": "1582915952443",
      "type": "file",
      "content": "More information about public APIs"
  }]
  ai_agent = {
      'type': 'ai_agent_ask',
      'basic_text_multi': {
          'model': 'openai__gpt_3_5_turbo'
      }
  }
  answer = client.send_ai_question(
      items=items, 
      prompt="What is this file?",
      mode="single_item_qa",
      ai_agent=ai_agent
  )
  print(answer)
  ```

  ```cs .NET v6 theme={null}
  BoxAIResponse response = await client.BoxAIManager.SendAIQuestionAsync(
      new BoxAIAskRequest
      {
          Prompt = "What is the name of the file?",
          Items = new List<BoxAIAskItem>() { new BoxAIAskItem() { Id = "12345" } },
          Mode = AiAskMode.single_item_qa
      };
  );
  ```

  ```javascript Node v4 theme={null}
  client.ai.ask(
      {
          prompt: 'What is the capital of France?',
          items: [
              {
                  type: 'file',
                  id: '12345'
              }
          ],
          mode: 'single_item_qa'
      })
      .then(response => {
          /* response -> {
              "answer": "Paris",
              "created_at": "2021-10-01T00:00:00Z",
              "completion_reason": "done"
          } */
      });
  ```
</CodeGroup>

### パラメータ

コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。

| パラメータ                         | 説明                                                                                                                                                                                                                                                                  | 使用可能な値                                                          | 例                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`mode`**                    | リクエストの種類。単一のファイルの場合は`single_item_qa`を使用します (`items`配列には要素が1つだけ含まれている必要があります)。複数のファイル (最大25ファイル) の場合は`multiple_item_qa`を使用します。ファイルサイズ、画像、プロンプトの制限に関する詳細については、<Link href="/guides/box-ai/index#input-limits">入力制限</Link>を参照してください。                                    | `single_item_qa`, `multiple_item_qa`                            | `single_item_qa`                                                                                                                                                            |
| **`prompt`**                  | ドキュメントまたはコンテンツに関する質問。最大10,000文字。                                                                                                                                                                                                                                    |                                                                 | `What is this document about?`                                                                                                                                              |
| `dialogue_history.prompt`     | 以前にクライアントによって提供され、大規模言語モデル (LLM) が回答したプロンプト。                                                                                                                                                                                                                        | `Make my email about public APIs sound more professional`       |                                                                                                                                                                             |
| `dialogue_history.answer`     | 以前にLLMから提供された回答。                                                                                                                                                                                                                                                    | `Here is a draft of your professional email about public APIs.` |                                                                                                                                                                             |
| `dialogue_history.created_at` | プロンプトに対する前回の回答が作成された時点のISO日付形式のタイムスタンプ。                                                                                                                                                                                                                             | `2012-12-12T10:53:43-08:00`                                     |                                                                                                                                                                             |
| `include_citations`           | 回答で引用情報を返すかどうかを指定します。                                                                                                                                                                                                                                               | `true`, `false`                                                 | `true`                                                                                                                                                                      |
| **`items.id`**                | 入力データとして指定するファイルまたはHubのID。                                                                                                                                                                                                                                          |                                                                 | `112233445566`                                                                                                                                                              |
| **`items.type`**              | 指定する入力データの種類。単体または複数のファイルの場合には`file`を、Box Hubの場合には`hubs`を、それぞれ使用します。`hubs`を使用する場合には、リクエスト内でその項目が唯一の項目になっている必要があります。                                                                                                                                                 | `file`, `hubs`                                                  | `file`                                                                                                                                                                      |
| `items.content`               | 項目のコンテンツ。通常はテキストレプリゼンテーションです。                                                                                                                                                                                                                                       |                                                                 | `An application programming interface (API) is a way for two or more computer programs or components to communicate with each other. It is a type of software interface...` |
| `ai_agent`                    | デフォルトのモデル構成を上書きします。これにより、モデル、プロンプトテンプレート、システムメッセージ、またはLLMパラメータを変更できます。仕組みについては<Link href="/guides/box-ai/index#the-ai_agent-override-system">上書きシステム</Link>を参照してください。また、使用例については<Link href="/guides/box-ai/ai-agents/ai-agent-overrides">AIモデルの上書き</Link>を参照してください。 |                                                                 |                                                                                                                                                                             |

## ユースケース

## 項目について質問する

この例では、`POST ask/ai` APIを使用して1つ以上の項目について質問する方法を示します。このエンドポイントを使用する際は、指定する項目の数に応じて、忘れずに`mode`パラメータを指定してください。

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "single_item_qa",
    "items": [
        {
            "id": "12345678",
            "type": "file"
        }
    ],
    "prompt": "List the guidelines on creating questions in Box AI for Documents"
}'
```

レスポンスは次のようになります。

```sh theme={null}
{
    "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview.\n2. If questions fall outside the scope of the document, Box AI will inform you that it cannot answer.\n3. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n4. Aim to stay within the scope of the document.\n5. Focus on text-based responses only.",
    "created_at": "2024-11-04T02:30:09.557-08:00",
    "completion_reason": "done"
}
```

## Hubについて質問する

質問に際して個別のファイルを入力データとする代わりに、Box AIに対して特定の<Link href="/guides/hubs-api/index">Box Hub</Link>全体を指定すると、そのHubの厳選されたコンテンツに基づいた回答が得られます。この機能は、ファイルIDを自分で管理しなくとも、承認済みの資料に基づいた回答を自然言語で得ることができるため、RFP回答集、ポリシーライブラリ、製品ドキュメントポータルなどのナレッジベースに有用です。

Hubを対象とするクエリを実行する場合には、`items.type`を`hubs`、`items.id`をHubのIDに、それぞれ設定します。この場合、リクエスト内に入力データとして含める項目は、Hubのみにする必要があります。以下の例では、`single_item_qa`モードを使用しています。これは、<Link href="/guides/tutorials/sales-rfp-answer-bank">営業用RFP回答集のチュートリアル</Link>で紹介したパターンです。

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "single_item_qa",
    "items": [
        {
            "id": "98765432",
            "type": "hubs"
        }
    ],
    "prompt": "What is our standard SLA for enterprise support?"
}'
```

Box AIは、インデックスが作成されているHubコンテンツを検索し、承認済みの資料に基づいて回答を返します。HubはBoxの権限を引き継いでいるため、Box AIはクエリを実行したユーザーがアクセス権限を持つドキュメントのみを参照します。Hubでは、AI機能が有効になっている必要があります (詳細については、<Link href="/guides/hubs-api/hubs/update-hub">Hubの更新</Link>を参照してください)。

Hubのプロビジョニング、Hubへのコンテンツ登録、Box AIを使用したクエリ実行の具体的な手順については、<Link href="/guides/tutorials/sales-rfp-answer-bank">Box HubsとAIを使用した営業用RFP回答集の構築</Link>のチュートリアルを参照してください。

## `content`パラメータを使用して質問する

Box AIへの入力のソースとして`content`パラメータを使用すると、それがプライマリソースとして使用されます。

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "single_item_qa",
    "items": [
        {
            "id": "12345678",
            "type": "file",
            "content": "This is a document about Box AI For documents. It consists of the functionality summary and guidelines on how to work with Box AI. Additionally, it provides a set of best practices for creating questions."
        }
    ],
    "prompt": "List the guidelines on creating questions in Box AI for Documents"
}'
```

このリクエストに対するレスポンスは、ファイルのコンテンツではなく`content`パラメータに基づきます。

```sh theme={null}
{
    "answer": "The document does not provide specific guidelines on working with questions in Box AI for Documents. It only mentions that it includes a set of best practices for creating questions, but the details of those guidelines are not included in the text provided. If you have more information or another document, I can help further!",
    "created_at": "2024-11-04T02:31:51.125-08:00",
    "completion_reason": "done"
}
```

## `citations`パラメータを使用して質問する

`citations`パラメータを`true`に設定すると、レスポンスには、ソースファイルまたはBox AIが回答をまとめるのに使用したファイルからの抜粋が含まれます。

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "multiple_item_qa",
    "include_citations": true,
    "items": [
        {
            "id": "12345678",
            "type": "file"
        }
    ],
    "prompt": "List the guidelines on working with responses in Box AI for Documents"
}'
```

その結果の回答には、ソースファイルとコンテンツの直接引用が含まれます。

```sh theme={null}
{
    "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview, and cannot answer questions outside its scope.\n2. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n3. Examples of better phrasing include asking for a numbered list of key points instead of just \"list key points,\" and requesting a succinct outline of important points rather than a general inquiry about the document's purpose.\n4. Stay within the scope of the document and focus on text-based responses only.",
    "created_at": "2024-11-04T02:35:00.578-08:00",
    "completion_reason": "done",
    "citations": [
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "Guidelines for Box AI questions\nBox AI pulls information only from the document you loaded in preview."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "If you ask any questions outside of the scope of the document, Box AI informs you that it cannot answer the question with the information provided."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "As you ask Box AI to analyze your document, consider these suggestions:\n· Be as specific as possible."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "Box AI for Documents\n\nWhen viewing a document in Box, you can ask Box AI to summarize document content, search key points, and write outline drafts based on your document files."
        }
    ]
}
```

<RelatedLinks
  title="関連するAPI"
  items={[
{ label: translate("Ask question"), href: "/reference/post-ai-ask", badge: "POST" }
]}
/>

<RelatedLinks
  title="関連するガイド"
  items={[
{ label: translate("Get started with Box AI"), href: "/guides/box-ai/ai-tutorials/prerequisites", badge: "GUIDE" },
{ label: translate("Override AI model configuration"), href: "/guides/box-ai/ai-tutorials/default-agent-overrides", badge: "GUIDE" },
{ label: translate("Box Hubs overview"), href: "/guides/hubs-api/index", badge: "GUIDE" },
{ label: translate("Build a sales RFP answer bank with Box Hubs and AI"), href: "/guides/tutorials/sales-rfp-answer-bank", badge: "GUIDE" },
{ label: translate("Generate text with Box AI"), href: "/guides/box-ai/ai-tutorials/generate-text", badge: "GUIDE" },
{ label: translate("Extract metadata from file (freeform)"), href: "/guides/box-ai/ai-tutorials/extract-metadata", badge: "GUIDE" },
{ label: translate("Extract metadata from file (structured)"), href: "/guides/box-ai/ai-tutorials/extract-metadata-structured", badge: "GUIDE" }
]}
/>