Pular para o conteúdo principal

Responses

Create a response​

POST https://chat.maritaca.ai/api/v1/responses

Sends a question to the model and receives a response. Supports plain text, multi-turn conversations, function calling, structured outputs, and streaming.

Request Body​

model string Required​

Model to use (e.g., sabia-4).

input string or array Required​

What you want to ask the model. Can be a simple text or a list of input items.

Conversation message (object)
  • role (string) Required: Author role: user, assistant, system, or developer.
  • content (string or array) Required: Message content.
function_call (object)

Represents a function call made by the assistant in a previous turn.

  • type (string) Required: Always "function_call".
  • call_id (string) Required: Unique call identifier.
  • name (string) Required: Name of the called function.
  • arguments (string) Required: Arguments as serialized JSON.
function_call_output (object)

Result of a function call to return to the model.

  • type (string) Required: Always "function_call_output".
  • call_id (string) Required: Same call_id as the corresponding call.
  • output (string) Required: Function result (string, usually JSON).
reasoning (object)

Reasoning item returned by a previous response (S5 models), so the model can resume its reasoning. Just pass the item back as it came in output. See Reasoning.

  • type (string) Required: Always "reasoning".
  • id (string): Item identifier (rs_...).
  • encrypted_content (string): Encrypted reasoning, exactly as it came in the response. A modified value, or one from another account, returns 400 (invalid_encrypted_content).
  • content (array): Must be empty ([]). Text here returns 400 (array_above_max_length).
  • summary (array): The summary you received; it can be passed back as is.

reasoning object or null Optional​

Reasoning configuration (S5 models). See Reasoning.

Show properties
  • effort (string): How much the model thinks before answering: none, minimal, low, medium, high, xhigh or max. Default: xhigh. minimal is the same as low; high and max are the same as xhigh; none turns reasoning off.
  • summary (string): Requests a readable summary of the reasoning in the reasoning item: auto (same as detailed), concise or detailed. Default: no summary.
  • context (string): Which turns' reasoning the model sees: all_turns (default, every previous turn passed back) or current_turn (only what was generated after the last user message).

include array or null Optional​

Accepts "reasoning.encrypted_content", for OpenAI compatibility. The reasoning item's encrypted_content is always returned, with or without this parameter.

previous_response_id string or null Optional​

Id of a previous stored response (store: true). The model receives that response's conversation, including its reasoning, and you only send what is new in input. An id that does not exist, has expired or belongs to another account returns 400 (previous_response_not_found).

instructions string or null Optional​

System instructions that define the model's behavior (e.g., "Always respond in Portuguese").

temperature float or null Optional​

Default is 0.7. Controls response randomness (0.0 to 2.0).

top_p float or null Optional​

Default is 0.95. Nucleus sampling — keeps tokens with cumulative probability >= top_p.

max_output_tokens int or null Optional​

Maximum number of tokens in the response.

stop array or null Optional​

Sequences that, when generated, make the model stop generating.

stream bool or null Optional​

Default is false. If true, returns the response via Server-Sent Events in real time.

tools array or null Optional​

List of tools the model can call. Accepts functions and built-in tools, including web_search.

Function format
  • type (string): Always "function".
  • name (string) Required: Function name.
  • description (string): Function description.
  • parameters (object): JSON Schema of the parameters.
  • strict (bool): If true, enables strict schema validation. Default: true.
Web search format
  • type (string) Required: Always "web_search".
  • filters (object): Optional domain filters.
    • allowed_domains (array of strings): Keeps only results from these domains. Maximum 100.
    • blocked_domains (array of strings): Excludes results from these domains. Maximum 100.

When both lists are used, allowed_domains restricts the result set and blocked_domains removes results from that set, taking precedence. Provide domains without a protocol, port, or path. Each domain also includes its subdomains. Web search requires stream: false.

{
  "type": "web_search",
  "filters": {
    "allowed_domains": ["stf.jus.br", "gov.br"]
  }
}

tool_choice string or object or null Optional​

Default is "auto". Controls tool usage:

  • "auto": the model decides whether to use a tool.
  • "none": the model will not use tools.
  • "required": the model must call at least one tool.
  • {"type": "function", "name": "name"}: forces a specific function.

parallel_tool_calls bool or null Optional​

Default is true. Allows the model to make multiple function calls in parallel.

text object or null Optional​

Structured output format configuration.

Show properties
  • format.type (string): "text", "json_schema", or "json_object". Default: "text".
  • format.name (string): Schema name (required when type is "json_schema").
  • format.schema (object): Output JSON Schema (required when type is "json_schema").
  • format.strict (bool): Enables strict mode for schema validation.

metadata object or null Optional​

Key-value pairs for tracking. Maximum 16 pairs, key up to 64 characters, value up to 512 characters.

store bool or null Optional​

Default is true. Keeps the response for 30 days, with the reasoning encrypted, for use with previous_response_id. Use false to store nothing; in that case, pass the output items back on the next call.

Request Example​

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://chat.maritaca.ai/api",
)

response = client.responses.create(
    model="sabia-4",
    input="What is the capital of Brazil?",
)

print(response.output[0].content[0].text)