Extract metadata from file (freeform)
Extract metadata from file (freeform)
Box AI API allows you to query a document and extract metadata based on a provided prompt. Freeform means that the prompt can include a stringified version of formats such as JSON or XML, or even plain text.
Send a request
To send a request, use the
POST /2.0/ai/extract endpoint.
Make sure you have generated the developer token to authorize your app. See prerequisites for using Box AI for details.
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_3_5_turbo_16k",
"system_message": "You are a helpful travel assistant specialized in budget travel",
"prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
"num_tokens_for_completion": 8400,
"llm_endpoint_params": {
"type": "openai_params",
"temperature": 0,
"top_p": 1,
"frequency_penalty": 1.5,
"presence_penalty": 1.5,
"stop": "<|im_end|>"
},
"embeddings": {
"model": "openai__text_embedding_ada_002",
"strategy": {
"id": "basic",
"num_tokens_per_chunk": 64
}
}
},
"basic_text": {
"model": "azure__openai__gpt_3_5_turbo_16k",
"system_message": "You are a helpful travel assistant specialized in budget travel",
"prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
"num_tokens_for_completion": 8400,
"llm_endpoint_params": {
"type": "openai_params",
"temperature": 0,
"top_p": 1,
"frequency_penalty": 1.5,
"presence_penalty": 1.5,
"stop": "<|im_end|>"
}
}
}
}'await client.ai.createAiExtract({
prompt: 'firstName, lastName, location, yearOfBirth, company',
items: [new AiItemBase({ id: file.id })],
} satisfies AiExtract);client.ai.create_ai_extract(
"firstName, lastName, location, yearOfBirth, company",
[AiItemBase(id=file.id)],
ai_agent=ai_extract_agent_config,
)await client.Ai.CreateAiExtractAsync(requestBody: new AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})));BoxAIResponse response = BoxAI.extractMetadataFreeform(
api,
"firstName, lastName, location, yearOfBirth, company",
Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE))
);Parameters
To make a call, you must pass the following parameters. Mandatory parameters are in bold.
| Parameter | Description | Example |
|---|---|---|
prompt | The request for Box AI to generate or refine the text. The prompt's length cannot exceed 10000 characters. | Create a meeting agenda for a weekly sales meeting. |
items.id | Box file ID of the document. The ID must reference an actual file with an extension. | 1233039227512 |
items.type | The type of the supplied input. | file |
items.content | The content of the item, often the text representation. | This article is about Box AI. |
ai_agent | The AI agent used to override the default agent configuration. This parameter allows you to, for example, replace the default LLM with a custom one using the model parameter, tweak the base prompt to allow for a more customized user experience, or change an LLM parameter, such as temperature, to make the results more or less creative. Before you use the ai_agent parameter, you can get the default configuration using the GET 2.0/ai_agent_default request. For specific use cases, see the AI model overrides tutorial. |
Use case
Let's assume you want to extract the vendor name, invoice number, and a few more details from the following sample invoice:
Create the request
To get the response from Box AI, call POST /2.0/ai/extract endpoint with the following parameters:
promptthat can be a query, or a structured or unstructured list of fields to extract.typeandidof the file to extract the data from.
Create the prompt
Depending on the use case and the level of detail, you can construct various prompts.
Using keywords
The prompt can include a list of keywords that you expect to find in an invoice:
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"
}
]
}'
Using this approach results in a list of keywords provided in the request and their values:
{
"answer": "{\"vendor\": \"Quasar Innovations\", \"total\": \"$1,050\", \"doctype\": \"Invoice\", \"PO\": \"003\"}",
"created_at": "2024-05-31T10:28:51.906-07:00",
"completion_reason": "done"
}
Using key-value pairs
The prompt can be a list of key-value pairs that helps Box AI to come up with the metadata structure:
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"
}
]
}'
The response includes the fields present in the file, along with their values:
{
"answer": "{\"vendor\": \"Quasar Innovations\", \"documentType\": \"Invoice\"}",
"created_at": "2024-05-31T10:15:38.17-07:00",
"completion_reason": "done"
}
Using plain text
You can also use plain text:
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"
}
]
}'
In such a case, the response will be based on the keywords included in the query:
{
"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"
}