Box AI

Technical reference for Box AI request handling, input limits, model behavior, and the agent override system.

This section contains developer guides for working with Box AI. For a summary of API capabilities, quick starts, and reference links, see the Box AI API page.

The below guides cover what you need to know before you start writing code: how Box AI processes requests, what limits apply to different endpoints, how to control model behavior through agent overrides, and where to find the specific tutorial for your use case.

How requests are processed

When you send a request to a Box AI endpoint, Box handles the model infrastructure for you. Your request flows through the following stages:

• File retrieval: Box reads the file content from the items array you provide. If you include the optional content parameter, that text is used as the primary input instead of the file’s stored content. For POST /ai/ask, an items entry can also be a Box Hub ("type": "hubs"), in which case Box searches the hub’s indexed content instead of a single file. See Ask questions about a hub.
• Representation generation: For text-based files, Box converts the document into a text representation. For images, Box applies OCR automatically on supported endpoints.
• Model routing: Box routes the request to the default model for that endpoint and mode. You can override this with the ai_agent parameter.
• Response generation: The LLM processes your prompt against the file content and returns a result. Box handles token windowing for long documents (splitting content into chunks with embeddings for long_text configurations).

Box AI does not support multi-modal requests. If you send both images and text in the same request, only the text is processed.

Input limits

The limits below apply across Box AI endpoints. Exceeding these limits does not produce an error in most cases; Box truncates to the limit and processes what it can.

Text and prompt limits

Constraint	Limit
Prompt length	10,000 characters
Single file text representation (single_item_qa)	2 MB of text. Content beyond 2 MB is truncated.
Multiple files (multiple_item_qa)	Up to 25 files
Items array for text_gen	Exactly 1 file
Items array for extract and extract_structured	Exactly 1 file

Image limits

Constraint	Limit
Resolution	1024 x 1024 pixels
Maximum images or pages per request	5. If more are provided, only the first 5 are processed.

OCR and file format support

OCR is not available on all endpoints.

Endpoint	OCR	Supported file formats
POST /ai/text_gen	No	Text-based files
POST /ai/extract	No	Text-based files
POST /ai/extract_structured	Yes (automatic)	PDF, TIFF, PNG, JPEG

Language support

Box AI works in English, Japanese, French, Spanish, and many other languages. However, the underlying models are primarily trained on English, so prompts in other languages may return lower quality results.

The extract_structured endpoint has explicit multilingual support for:

• English, Japanese, Chinese, Korean
• Cyrillic-based languages (Russian, Ukrainian, Bulgarian, Serbian)

Switch the language to Japanese to get better results for this language.

The ai_agent override system

The following Box AI endpoints accept an optional ai_agent parameter that lets you override the default model configuration: POST /ai/ask, POST /ai/text_gen, POST /ai/extract, and POST /ai/extract_structured. This is how you control which LLM runs, how it behaves, and what instructions it receives.

When to use overrides

• Pinning a model version: Box updates default models regularly. If your downstream process depends on consistent output, pin to a specific model to avoid unexpected changes.
• Switching models: Different models produce different results. You can switch to any model in the to optimize for your use case.
• Customizing prompts: The prompt_template and system_message parameters let you steer the LLM’s behavior without changing your application code.
• Tuning creativity: Adjust temperature and other llm_endpoint_params to control how deterministic or creative the output is.

How it works

1. Get the default configuration

   Call with the mode you want (ask, text_gen, extract, or extract_structured) to retrieve the current defaults.

2. Modify the configuration

   Change the fields you need: model, prompt_template, system_message, llm_endpoint_params, or num_tokens_for_completion. Leave other fields unchanged.

3. Pass it back in your request

   Include the modified configuration as the ai_agent parameter in your POST request. Box uses your overrides for that request only.

Configuration structure by endpoint

The ai_agent object structure varies by endpoint because each handles content differently:

Endpoint	Agent type	Configuration keys
POST /ai/ask	ai_agent_ask	basic_text, basic_text_multi, long_text, long_text_multi
POST /ai/text_gen	ai_agent_text_gen	basic_gen
POST /ai/extract	ai_agent_extract	basic_text, long_text
POST /ai/extract_structured	ai_agent_extract_structured	basic_text, long_text

The ask endpoint has four configuration keys because it handles both single-item and multi-item modes, and both short and long documents. When using multiple_item_qa mode, the _multi variants apply.

For long_text configurations, Box splits the content into chunks using an embeddings model. You can configure the embeddings model and chunking strategy as part of the override.

LLM parameter differences by provider

The llm_endpoint_params options depend on the model provider:

Provider	Param type	Key difference
	openai_params	Use temperature or top_p, not both
	google_params	temperature works with top_p and top_k together
	aws_params	Same as Google: temperature works alongside top_p and top_k

For detailed override examples, see the guide and the .

Model versioning

Box guarantees each AI agent configuration snapshot for at least 12 months, with a 6-month transition window when a new version is released. Default model changes are posted in the . To avoid disruption, pin your agent configuration to a specific model version using overrides.

For full details, see .

Box AI for UI Elements

The integration embeds question-answering directly into Content Preview within your application. This lets end users interact with Box AI without leaving your UI.

User Activity Reports

User Activity Reports track Box AI interactions. Box admins can filter for the following action types:

Action type	Description
AI query	The user queried Box AI and received a response
Failed AI query	The user queried Box AI but did not receive a response

Guides in this section

Tutorials

Step-by-step guides for each endpoint: ask, text generation, extraction, and model overrides.

Model overrides

Override default models, prompts, and LLM parameters. Includes the default configuration reference and versioning policy.

Supported models

Full list of core and customer-enabled models with capability tiers, compliance badges, and API names.

Quick starts

Get up and running in minutes with Python SDK walkthroughs for summarization and extraction.

See Box AI in action

These end-to-end tutorials show how to combine Box AI with other platform capabilities to build production-ready automations.

Invoice intake automation

Use Box AI Extract and metadata to automate accounts payable - extract vendors, totals, and dates from every invoice.

Sales RFP answer bank

Build an AI-powered knowledge base with Box Hubs and let sales reps query approved proposals in natural language.