--- title: "Extract metadata (freeform)" method: POST path: "/ai/extract" tags: ["AI"] --- # Extract metadata (freeform) `POST /ai/extract` Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs. In this request, both the prompt and the output can be freeform. Metadata template setup before sending the request is not required. ## Request body - AiExtract — AI metadata freeform extraction request object. - `prompt` string, required — The prompt provided to a Large Language Model (LLM) in the request. The prompt can be up to 10000 characters long and it can be an XML or a JSON schema. - `items` AiItemBase[], required — The items that LLM will process. Currently, you can use files only. - `id` string, required — The ID of the file. - `type` 'file', required — The type of the item. Currently the value can be `file` only. - `content` string — The content of the item, often the text representation. - `ai_agent` union - object — The AI agent to be used for the extraction. - `type` 'ai_agent_id', required — The type of AI agent used to handle queries. - `id` string, required — The ID of an Agent. This can be a numeric ID for custom agents (for example, `14031`) or a unique identifier for pre-built agents (for example, `enhanced_extract_agent` for the [Enhanced Extract Agent](https://developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent)). - object — The AI agent to be used for the extraction. - `type` 'ai_agent_extract', required — The type of AI agent to be used for extraction. - `long_text` AiAgentLongTextTool — AI agent processor used to handle basic text. - `model` string — The model used for the AI agent for basic text. For specific model values, see the [available models list](https://developer.box.com/guides/box-ai/ai-models). - `num_tokens_for_completion` integer — The number of tokens for completion. - `llm_endpoint_params` union — The parameters for the LLM endpoint specific to a model. - object — AI LLM endpoint params OpenAI object. - `type` 'openai_params', required — The type of the AI LLM endpoint params object for OpenAI. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `frequency_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. - `presence_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `stop` string, nullable — Up to 4 sequences where the API will stop generating further tokens. - object — AI LLM endpoint params Google object. - `type` 'google_params', required — The type of the AI LLM endpoint params object for Google. This parameter is **required**. - `temperature` number, nullable — The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection. - `top_p` number, nullable — `Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - object — AI LLM endpoint params AWS object. - `type` 'aws_params', required — The type of the AI LLM endpoint params object for AWS. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - object — AI LLM endpoint params IBM object. - `type` 'ibm_params', required — The type of the AI LLM endpoint params object for IBM. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - `system_message` string — System messages try to help the LLM "understand" its role and what it is supposed to do. - `prompt_template` string — The prompt template contains contextual information of the request and the user prompt. When passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`. `{current_date}` is optional, depending on the use. - `embeddings` object - `model` string — The model used for the AI agent for calculating embeddings. - `strategy` object - `id` string — The strategy used for the AI agent for calculating embeddings. - `num_tokens_per_chunk` integer — The number of tokens per chunk. - `basic_text` AiAgentBasicTextTool — AI agent processor used to handle basic text. - `model` string — The model used for the AI agent for basic text. For specific model values, see the [available models list](https://developer.box.com/guides/box-ai/ai-models). - `num_tokens_for_completion` integer — The number of tokens for completion. - `llm_endpoint_params` union — The parameters for the LLM endpoint specific to a model. - object — AI LLM endpoint params OpenAI object. - `type` 'openai_params', required — The type of the AI LLM endpoint params object for OpenAI. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `frequency_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. - `presence_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `stop` string, nullable — Up to 4 sequences where the API will stop generating further tokens. - object — AI LLM endpoint params Google object. - `type` 'google_params', required — The type of the AI LLM endpoint params object for Google. This parameter is **required**. - `temperature` number, nullable — The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection. - `top_p` number, nullable — `Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - object — AI LLM endpoint params AWS object. - `type` 'aws_params', required — The type of the AI LLM endpoint params object for AWS. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - object — AI LLM endpoint params IBM object. - `type` 'ibm_params', required — The type of the AI LLM endpoint params object for IBM. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - `system_message` string — System messages try to help the LLM "understand" its role and what it is supposed to do. - `prompt_template` string — The prompt template contains contextual information of the request and the user prompt. When passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`. `{current_date}` is optional, depending on the use. - `basic_image` AiAgentBasicTextTool — AI agent processor used to handle basic text. - `model` string — The model used for the AI agent for basic text. For specific model values, see the [available models list](https://developer.box.com/guides/box-ai/ai-models). - `num_tokens_for_completion` integer — The number of tokens for completion. - `llm_endpoint_params` union — The parameters for the LLM endpoint specific to a model. - object — AI LLM endpoint params OpenAI object. - `type` 'openai_params', required — The type of the AI LLM endpoint params object for OpenAI. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `frequency_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. - `presence_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `stop` string, nullable — Up to 4 sequences where the API will stop generating further tokens. - object — AI LLM endpoint params Google object. - `type` 'google_params', required — The type of the AI LLM endpoint params object for Google. This parameter is **required**. - `temperature` number, nullable — The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection. - `top_p` number, nullable — `Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - object — AI LLM endpoint params AWS object. - `type` 'aws_params', required — The type of the AI LLM endpoint params object for AWS. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - object — AI LLM endpoint params IBM object. - `type` 'ibm_params', required — The type of the AI LLM endpoint params object for IBM. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - `system_message` string — System messages try to help the LLM "understand" its role and what it is supposed to do. - `prompt_template` string — The prompt template contains contextual information of the request and the user prompt. When passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`. `{current_date}` is optional, depending on the use. ## Response `200` A response including the answer from the LLM. - AiResponse — AI response. - `answer` string, required — The answer provided by the LLM. - `created_at` string, date-time, required — The ISO date formatted timestamp of when the answer to the prompt was created. - `completion_reason` string — The reason the response finishes. - `ai_agent_info` AiAgentInfo — The information on the models and processors used in the request. - `models` object[] — The models used for the request. - `name` string — The name of the model used for the request. - `provider` string — The provider that owns the model used for the request. - `supported_purpose` string — The supported purpose utilized by the model used for the request. - `processor` string — The processor used for the request. ## Other responses - `500` — An unexpected server error. - `default` — An unexpected error. --- [API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)