メインコンテンツへスキップ
Box AI APIを使用すると、ドキュメントを照会し、指定したプロンプトに基づいてメタデータを抽出できます。自由形式とは、JSONやXMLなどの形式の文字列化バージョン、またはプレーンテキストをプロンプトに含めることができるという意味です。
メタデータを抽出 (自由形式) エンドポイントはOCRをサポートしていません。英語以外の言語の画像ファイル (TIFF、PNG、JPEG) またはドキュメントからメタデータを抽出するには、メタデータを抽出 (構造化) エンドポイントを使用してください。

​
開始する前に

Platformアプリを作成して認証するには、Box AIの使い方に記載されている手順に従っていることを確認してください。

​
リクエストの送信

リクエストを送信するには、POST /2.0/ai/extractエンドポイントを使用します。 
curl -i -L 'https://api.box.com/2.0/ai/extract' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <ACCESS_TOKEN>' \
     -d '{
        "prompt": "Extract data related to contract conditions",
        "items": [
              {
                  "type": "file",
                  "id": "1497741268097"
              }
        ],
        "ai_agent": {
          "type": "ai_agent_extract",
          "long_text": {
            "model": "azure__openai__gpt_4o_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": "azure__openai__gpt_4o_mini",
          }
        }
      }'

​
パラメータ

コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは太字で示されています。
items配列に含めることができる要素は1つだけです。
パラメータ説明例
promptBox AIに対するテキストの生成またはリファインのリクエスト。プロンプトの長さは10000文字以内にする必要があります。週1回の営業会議のアジェンダを作成してください。
items.idドキュメントのBoxファイルID。IDは、拡張子が付いている実際のファイルを参照する必要があります。1233039227512
items.type指定した入力データのタイプ。file
items.content項目のコンテンツ (多くの場合はテキストレプリゼンテーション)。This article is about Box AI.
ai_agentデフォルトのエージェント構成を上書きするために使用されるAIエージェント。このパラメータを使用すると、たとえば、modelパラメータを使用してデフォルトのLLMをカスタムのLLMに置き換えたり、よりカスタマイズされたユーザーエクスペリエンスを実現できるようにベースとなるpromptを微調整したり、temperatureなどのLLMパラメータを変更して結果の創造性を調整したりすることができます。ai_agentパラメータを使用する前に、GET 2.0/ai_agent_defaultリクエストを使用してデフォルト構成を取得できます。具体的なユースケースについては、AIモデルの上書きに関するチュートリアルを参照してください。

​
ユースケース

この例では、サンプル請求書からメタデータを抽出する方法を示します。

​
リクエストの作成

Box AIから応答を取得するには、以下のパラメータを使用して、POST /2.0/ai/extractエンドポイントを呼び出します。
  • クエリか、抽出するフィールドの構造化リストまたは非構造化リストを指定できるprompt。
  • データの抽出元となるファイルのtypeおよびid。

​
プロンプトの作成

ユースケースや詳細度に応じて、さまざまなプロンプトを作成できます。

​
プレーンテキストを使用する

このエンドポイントでは自由形式のプロンプトが許可されているため、プレーンテキストを使用して情報を取得できます。 
curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
    "prompt": "find the document type (invoice or po), vendor, total, and po number",
    "items": [
        {
            "type": "file",
            "id": "1443721424754"
        }
    ]
}'
その場合、レスポンスは、テキストに含まれているキーワードに基づいて作成されます。 
{
    "answer": "{\"Document Type\": \"Invoice\", \"Vendor\": \"Quasar Innovations\", \"Total\": \"$1,050\", \"PO Number\": \"003\"}",
    "created_at": "2024-05-31T10:30:51.223-07:00",
    "completion_reason": "done"
}

​
特定の用語を使用する

文全体を書かなくても、請求書に含まれることが予想される用語でプロンプトを構成できます。 
curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: <ACCESS_TOKEN>' \
--data '{
    "prompt": "{\"vendor\",\"total\",\"doctype\",\"date\",\"PO\"}",
    "items": [
        {
            "type": "file",
            "id": "1443721424754"
        }
    ]
}'
このアプローチを使用すると、以下のように、リクエストで指定した用語のリストとその値が返されます。 
{
    "answer": "{\"vendor\": \"Quasar Innovations\", \"total\": \"$1,050\", \"doctype\": \"Invoice\", \"PO\": \"003\"}",
    "created_at": "2024-05-31T10:28:51.906-07:00",
    "completion_reason": "done"
}

​
キー/値ペアを使用する

プロンプトには、Box AIがメタデータの構造を認識するのに役立つキー/値ペアのリストを指定することができます。このアプローチでは、fields配列内にキー/値ペアを列挙する必要があります。 
curl --location 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
          "prompt": "{\"fields\":   [{\"key\":\"vendor\",\"displayName\":\"Vendor\",\"type\":\"string\",\"description\":\ "Vendorname\"},{\"key\":\"documentType\",\"displayName\":\"Type\",\"type\":\"string\",\"description\":\"\"}]}",
    "items": [
        {
            "type": "file",
            "id": "1443721424754"
        }
    ]
}'
レスポンスには、以下のように、ファイル内に存在するfieldsとその値が含まれます。 
{
    "answer": "{\"vendor\": \"Quasar Innovations\", \"documentType\": \"Invoice\"}",
    "created_at": "2024-05-31T10:15:38.17-07:00",
    "completion_reason": "done"
}