Sample - Box Platform API
POST/ai/text_gen

Generate text with Box AI

Generates text with a supported large language model using a prompt and file context. Supply prompt and exactly one file in items, and optionally provide dialogue history or an AI agent configuration. The file's text representation is limited to the first 2 MB when its source representation exceeds that size.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

4 body fields

Optional AI text-generation request containing a prompt, one file item, and optional conversation or agent configuration. prompt and items are required.

promptstringrequired
The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.
itemsarray<object>required
The items to be processed by the LLM, often files. The array can include **exactly one** element. **Note**: Box AI handles documents with text representations up to 2MB in size. If the file size exceeds 2MB, the first 2MB of text representation will be processed.
dialogue_historyarray<DialogueHistory>optional
The history of prompts and answers previously passed to the LLM. This parameter provides the additional context to the LLM when generating the response.
ai_agentobjectoptional
The AI agent configuration to use for generating text.

3 status codes
200Returns the generated answer with its creation timestamp, completion reason, and information about the models and processors used.
answerstringrequired
The answer provided by the LLM.
created_atstringrequired
The ISO date formatted timestamp of when the answer to the prompt was created.
completion_reasonstringoptional
The reason the response finishes.
ai_agent_infoobjectoptional
The information on the models and processors used in the request.
500Returned when an unexpected server error occurs.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

prompt and items are required. prompt must not exceed 10,000 characters, and items must contain exactly one unique item with id and type set to file; a 500 is returned for an unexpected server error.