Request body
A list of conversational turns, alternating between the user and the assistant,
or a single instruction string.Please note that there are two different options for the input.
show possible types
show possible types
Text input
A plain instruction string for AI21 Maestro. Equivalent to a single message with the user role.
Input messages
A list of message objects representing a multi-turn conversation alternating between the user and the assistant.
string
A plain instruction string for AI21 Maestro. Equivalent to a single message with the user role.
Input messages
object []
A list of message objects representing a multi-turn conversation alternating between the user and the assistant.
Explicit requirements for the output. The requirements can be in terms of content, style, format, genre, point of view, and various guardrails AI21 Maestro will allocate resources to maintain all requirements throughout the run. At the end of the run, the score for each requirement and the overall score will be returned. Users can specify up to 10 requirements.
Examples of requirements:
Show properties
Show properties
The requirement’s name, which allows users to reference it in their applications later.
The requirement’s description in natural language.
This will influence our result scoring and budget allocation.
The maximum length for each description is 128 words.
Default: false.
If set to
If set to
true
, and the associated requirement is not fully satisfied, the overall requirements_result score will be 0.- “Write up to 3 paragraphs”
- “Output only the answer”
- “Don’t mention a word about the company’s CEO”
- “Use a friendly tone”
Note:Requirements only work if no tools are selected.
Avoid conflicting requirementsConflicts may reduce run quality or prevent fulfillment.
An array of objects.
Show properties
Show properties
Supported values are
file_search
and web_search
.A set of resources used by AI21 Maestro’s tools.
Show properties
Show properties
When provided, this object defines filters that AI21 Maestro will apply whenever it performs a file search.
When provided, this object defines filters that AI21 Maestro will apply whenever it performs a web search.
Show properties
Show properties
Restrict web search to the specified URL prefixes. The following formats are valid:
https://example.com
– limits to URLs that start withwww.example.com
example.com
– limits to URLs that start withwww.example.com
example.com/page
– limits to URLs that start withwww.example.com/page
sub.example.com
– limits to URLs that start with the specified subdomain (e.g.,docs.example.com
,blog.example.com
)
defaults to null.Specify a single model to be used for the run. Choose from the following:First-Party Models
Models hosted and managed by AI21:
Bring‑Your‑Own‑Key (BYOK) third‑party models:
Specify the ID of a third-party model configured on the 3rd-Party Models page.These models require your own API key. AI21 uses your key to authenticate and access the model on your behalf. Supported providers include OpenAI, Anthropic, and Google.
jamba-large
jamba-mini
gpt-4o
– The latest GPT‑4o model, accessed using AI21’s own API keymistral-8x7b
mistral-7b
mistral-small
Bring‑Your‑Own‑Key (BYOK) third‑party models:
Specify the ID of a third-party model configured on the 3rd-Party Models page.These models require your own API key. AI21 uses your key to authenticate and access the model on your behalf. Supported providers include OpenAI, Anthropic, and Google.
Controls how many resources AI21 Maestro allocates to fulfill the requirements. Accepted values:
high
medium
low
low
if not provided.Specify which extra fields should be included in the output. If not provided, none of these fields will be included.
Supported values:
data_sources
— Includes thedata_sources
field in the output.requirements_result
— Includes detailed results for each requirement in therequirements_result
field.
Controls the output language of AI21 Maestro responses.
Response language can be only one of the following: “arabic”, “dutch”, “english”, “french”, “german”, “hebrew”, “italian”, “portuguese”, “spanish”.
If not provided, defaults to English.
Response language can be only one of the following: “arabic”, “dutch”, “english”, “french”, “german”, “hebrew”, “italian”, “portuguese”, “spanish”.
If not provided, defaults to English.