> ## Documentation Index
> Fetch the complete documentation index at: https://concentrate.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Parameters Reference

> Reference for every request parameter on the Responses API, including model, input, routing, tools, sampling, streaming, and response format options.

## Overview

This page provides a comprehensive reference for all parameters you can use when creating responses. Parameters are organized by category for easy navigation.

## Required Parameters

### model

<ParamField body="model" type="string" required>
  The AI model to use for generating the response.

  **Format Options:**

  * **Model name only**: `"gpt-5.2"` - Automatic provider routing
  * **Provider-prefixed**: `"openai/gpt-5.2"` - Specific provider
  * **Auto routing**: `"auto"` - Currently selects from a curated pool of models (temporary; see [Auto routing](/docs/api-reference/endpoint/auto-routing))

  **Examples:**

  ```json theme={null}
  {
    "model": "gpt-5.2" // Automatic provider routing
  }
  ```

  ```json theme={null}
  {
    "model": "anthropic/claude-opus-4-5" // Specific provider
  }
  ```

  ```json theme={null}
  {
    "model": "auto", // Auto routing
    "routing": {
      "provider": { "sort": "cost" }
    }
  }
  ```

  See the [Model Fortress](https://concentrate.ai/models) on the app for a full list.
</ParamField>

### input

<ParamField body="input" type="string | array" required>
  The input to send to the model. Can be either a simple string or an array of message/tool objects for conversations.

  **String Format:**

  ```json theme={null}
  {
    "input": "What is the capital of France?"
  }
  ```

  **Conversation Format:**

  ```json theme={null}
  {
    "input": [
      {
        "role": "system",
        "content": "You are a helpful assistant specialized in geography."
      },
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }
  ```

  **Array Item Types:**

  The input array can contain the following types of objects:

  **1. Message Objects**

  Standard conversation messages:

  * `type` (optional): "message" (default)
  * `role` (required): "user", "assistant", "system", or "developer"
  * `content` (required): String or array of content blocks (e.g., `[{ "type": "input_text", "text": "..." }]` or `[{ "type": "input_image", "image_url": "..." }]`). See [Multi-Modal Inputs](/docs/api-reference/endpoint/multi-modal) for image support.
  * `cache_control` (optional): Cache control settings (see [Prompt Caching](#prompt-caching))

  **2. Function Call Objects**

  Used when the model calls a tool and you need to continue the conversation:

  ```json theme={null}
  {
    "type": "function_call",
    "call_id": "call_abc123",
    "name": "get_weather",
    "arguments": "{\"location\": \"San Francisco, CA\"}",
    "status": "completed"
  }
  ```

  Properties:

  * `type` (required): "function\_call"
  * `call_id` (required): Unique identifier for this function call
  * `name` (required): Function name that was called
  * `arguments` (required): JSON string of the function arguments
  * `status` (optional): "completed", "in\_progress", or "incomplete"
  * `cache_control` (optional): Cache control settings

  **3. Function Call Output Objects**

  Used to send the result of a function call back to the model:

  ```json theme={null}
  {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"temperature\": 72, \"conditions\": \"sunny\"}",
    "is_error": false
  }
  ```

  Properties:

  * `type` (required): "function\_call\_output"
  * `call_id` (required): Must match the call\_id from the function\_call
  * `output` (required): String or array containing the function result
  * `is_error` (optional): Boolean indicating if the function execution failed

  **Multi-Turn Tool Calling Example:**

  ```json theme={null}
  {
    "model": "gpt-5.2",
    "input": [
      {
        "role": "user",
        "content": "What's the weather in San Francisco?"
      },
      {
        "type": "function_call",
        "call_id": "call_abc123",
        "name": "get_weather",
        "arguments": "{\"location\": \"San Francisco, CA\"}"
      },
      {
        "type": "function_call_output",
        "call_id": "call_abc123",
        "output": "{\"temperature\": 72, \"conditions\": \"sunny\"}"
      }
    ],
    "tools": [...]
  }
  ```

  See [Tool Calling Guide](/docs/api-reference/endpoint/tool-calling) for complete workflow examples.
</ParamField>

## Output Control Parameters

### text

<ParamField body="text" type="object">
  Configure the format of the model's text output, including structured output.

  **Properties:**

  * `format` (required): Object controlling the output format
    * `type` (required): `"text"` | `"json_schema"` | `"json_object"`
    * `name` (required for json\_schema): Schema name
    * `schema` (required for json\_schema): JSON Schema object
    * `description` (optional): Description of the expected output
    * `strict` (optional): Enable strict schema enforcement

  **Example:**

  ```json theme={null}
  {
    "model": "gpt-5.2",
    "input": "Extract the person's name and age",
    "text": {
      "format": {
        "type": "json_schema",
        "name": "person",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "age": { "type": "integer" }
          },
          "required": ["name", "age"],
          "additionalProperties": false
        }
      }
    }
  }
  ```

  See [Structured Output](/docs/api-reference/endpoint/structured-output) for complete documentation and examples.
</ParamField>

### max\_output\_tokens

<ParamField body="max_output_tokens" type="integer">
  Maximum number of tokens to generate in the response.

  **Important Notes:**

  * If not specified, uses the model's default limit or your credit limit (whichever is lower)
  * Highly recommended to set this to avoid unexpectedly long and expensive responses
  * Different models have different maximum output token limits

  **Examples:**

  ```json theme={null}
  {
    "model": "gpt-5.2",
    "input": "Write a short story",
    "max_output_tokens": 500
  }
  ```

  **Model Limits:**

  | Model             | Max Output Tokens |
  | ----------------- | ----------------- |
  | GPT-5.2           | 16,384            |
  | Claude Opus 4.5   | 16,384            |
  | Claude Sonnet 4.5 | 16,384            |
  | Gemini 2.5 Pro    | 65,536            |
  | o1                | 100,000           |
</ParamField>

## Sampling Parameters

These parameters control the randomness and creativity of model outputs.

### temperature

<ParamField body="temperature" type="number" default={1.0}>
  Controls randomness in the output. Range: 0.0 to 2.0

  **Values:**

  * **0.0 - 0.3**: Very focused and deterministic
    * Use for: Code generation, factual tasks, data extraction
  * **0.4 - 0.7**: Balanced creativity and coherence
    * Use for: General conversation, Q\&A, explanations
  * **0.8 - 1.2**: Creative and varied
    * Use for: Creative writing, brainstorming, storytelling
  * **1.3 - 2.0**: Highly random and experimental
    * Use for: Highly creative tasks, unconventional ideas

  **Examples:**

  ```json theme={null}
  // Factual, deterministic output
  {
    "model": "gpt-5.2",
    "input": "Write a function to sort an array",
    "temperature": 0.2
  }
  ```

  ```json theme={null}
  // Creative writing
  {
    "model": "claude-opus-4-5",
    "input": "Write a short story about a robot",
    "temperature": 0.9
  }
  ```

  <Warning>
    Temperatures above 1.5 can produce incoherent or nonsensical outputs. Use with caution.
  </Warning>
</ParamField>

### top\_p

<ParamField body="top_p" type="number" default={1.0}>
  Nucleus sampling parameter. Range: 0.0 to 1.0

  **How it works:**

  * Controls diversity by limiting token selection to the top probability mass
  * Alternative to temperature for controlling randomness
  * Lower values = more focused, higher values = more diverse

  **Recommended Usage:**

  * **0.1 - 0.3**: Very focused outputs
  * **0.4 - 0.7**: Balanced outputs
  * **0.8 - 1.0**: Diverse outputs

  **Example:**

  ```json theme={null}
  {
    "model": "gpt-5.2",
    "input": "Suggest product names",
    "top_p": 0.9 // More diverse suggestions
  }
  ```

  <Info>
    Generally, only use one of `temperature` or `top_p` at a time, not both. If you specify both, temperature typically takes precedence depending on the model.
  </Info>
</ParamField>

## Streaming

### stream

<ParamField body="stream" type="boolean" default={false}>
  Enable real-time streaming of the response using Server-Sent Events (SSE).

  **When to use:**

  * ✅ Chat interfaces
  * ✅ Long-form content generation
  * ✅ When user experience matters
  * ✅ Progressive display of results

  **When not to use:**

  * ❌ Batch processing
  * ❌ API integrations where full response is needed
  * ❌ Simple programmatic tasks

  **Example:**

  ```json theme={null}
  {
    "model": "gpt-5.2",
    "input": "Write a long essay on AI",
    "stream": true
  }
  ```

  See [Streaming Documentation](/docs/api-reference/endpoint/streaming) for complete implementation details.
</ParamField>

## Advanced Features

### reasoning

<ParamField body="reasoning" type="object">
  Enable and configure reasoning mode for models that support it (e.g., o1, command-a-reasoning).

  **Properties:**

  * `effort` (required): "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" - Amount of reasoning effort to apply

  **Example:**

  ```json theme={null}
  {
    "model": "openai/o1",
    "input": "Solve this complex math problem: ...",
    "reasoning": {
      "effort": "high"
    }
  }
  ```

  <Info>
    Not all models support all reasoning levels. If your requested level isn't
    supported by the model, Concentrate bumps it up, then down, to the closest
    supported level. Reasoning tokens are counted separately in usage statistics
    and may be priced differently than regular output tokens.
  </Info>

  **Effort Levels:**

  * **none**: Disable reasoning on models that allow turning it off
  * **minimal**: Minimal reasoning, fastest responses
  * **low**: Basic reasoning, faster, lower cost
  * **medium**: Balanced reasoning and speed
  * **high**: Deep reasoning, slower, higher cost (more reasoning tokens)
  * **xhigh**: Extended deep reasoning for the hardest tasks
  * **max**: The model's maximum reasoning effort
</ParamField>

### routing

<ParamField body="routing" type="object">
  Routing configuration for provider selection, fallback models, and optimization.

  <Info>
    Auto model selection (`model: "auto"`) is temporarily simplified to a fixed pool of models. See [Auto routing](/docs/api-reference/endpoint/auto-routing) for details.
  </Info>

  **Properties:**

  <ParamField body="routing.provider.sort" type="string" default="performance">
    How providers are sorted and selected:

    **Static Metrics:**

    * `"cost"` — Sort by provider pricing (cheapest first)
    * `"performance"` — Sort by quality (best first, default)

    **Live Metrics (from Redis over the configured interval):**

    *Latency:*

    * `"avg_latency"` — Average response time
    * `"latency"` — Minimum observed response time
    * `"p50_latency"`, `"p90_latency"`, `"p99_latency"` — Percentile latencies
    * `"avg_e2e_latency"`, `"e2e_latency"` — Average / minimum end-to-end latency including overhead

    You can use any percentile from p0 to p100 for both latency and e2e\_latency:

    * Format: `"p75_latency"`, `"p85_latency"`, `"p50_e2e_latency"`, `"p99_e2e_latency"`, etc.

    *Reliability & Volume:*

    * `"uptime"` — Provider availability percentage
    * `"throughput"` — Requests per second
    * `"total_requests"` — Total request volume

    *Token Metrics:*

    * `"input_tokens"`, `"output_tokens"`, `"total_tokens"` — Average token counts
  </ParamField>

  <ParamField body="routing.model.sort" type="string" default="performance">
    Accepts the same metric values as `routing.provider.sort`, for sorting the model pool `model: "auto"` picks from.

    <Info>
      Currently ignored while auto model selection is stubbed to a fixed pool.
    </Info>
  </ParamField>

  <ParamField body="routing.provider.interval" type="string" default="15 minutes">
    Time window for live metric calculation. Ignored for static metrics (`cost`, `performance`).

    **Format:** `"number unit"` or `"number<shorthand>"`

    **Valid Units:**

    * `minutes` or `m` — "15 minutes", "30 minutes", "15m", "30m"
    * `hours` or `h` — "1 hour", "6 hours", "24 hours", "1h", "6h", "24h"
    * `days` or `d` — "7 days", "30 days", "7d", "30d"
    * `weeks` or `w` — "1 week", "4 weeks", "1w", "4w"
    * `years` or `y` — "1 year", "1y"

    <Info>
      Minimum interval is 15 minutes.
    </Info>
  </ParamField>

  <ParamField body="routing.model.fallbacks" type="array">
    Fallback models tried after the primary model's providers are exhausted. Accepts model slugs, `provider/model` format, and `"auto"`.

    ```json theme={null}
    { "routing": { "model": { "fallbacks": ["claude-sonnet-4-20250514", "auto"] } } }
    ```
  </ParamField>

  <ParamField body="routing.provider.fallbacks" type="array">
    Whitelist of providers. When set, only these providers are considered. Omit to allow all.

    ```json theme={null}
    { "routing": { "provider": { "fallbacks": ["openai", "azure"] } } }
    ```
  </ParamField>

  **Complete Examples:**

  ```json theme={null}
  // Optimize for cost with fallback models
  {
    "model": "gpt-4o",
    "input": "Summarize this text",
    "routing": {
      "provider": { "sort": "cost" },
      "model": { "fallbacks": ["gemini-2.5-flash"] }
    }
  }
  ```

  ```json theme={null}
  // Performance-optimized (default behavior)
  {
    "model": "auto",
    "input": "Complex analysis task",
    "routing": {
      "provider": { "sort": "performance", "interval": "1 hour" }
    }
  }
  ```

  ```json theme={null}
  // Low-latency with provider restriction
  {
    "model": "auto",
    "input": "Quick question",
    "routing": {
      "provider": {
        "sort": "p99_latency",
        "interval": "15 minutes",
        "fallbacks": ["openai", "anthropic"]
      }
    }
  }
  ```

  See [Routing Documentation](/docs/api-reference/endpoint/auto-routing) for the full guide.
</ParamField>

## Guardrails (API Key Policy)

Guardrails are configured at the API key level, not in the `/v1/responses` request body.

<Info>
  Configure guardrails in the dashboard UI (Guardrails page) on your API key. No
  additional request parameter is required in `/v1/responses`.
</Info>

See [Guardrails & Redaction](/docs/api-reference/endpoint/guardrails-redaction) for setup and behavior.

## Tool Calling

### tools

<ParamField body="tools" type="array">
  Array of tools the model can call. Each tool is a function definition with a JSON Schema.

  **Tool Definition:**

  * `type` (required): "function" - Type of tool
  * `name` (required): string - Function name (alphanumeric, underscores, dots, hyphens)
  * `description` (optional): string - What the function does
  * `parameters` (required): object - JSON Schema for function parameters
  * `strict` (optional): boolean - Enable strict schema validation (default: true)
  * `cache_control` (optional): object - Cache this tool definition (ephemeral, 5m or 1h TTL)

  **Example:**

  ```json theme={null}
  {
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    ]
  }
  ```

  See [Tool Calling Guide](/docs/api-reference/endpoint/tool-calling) for complete examples.
</ParamField>

### tool\_choice

<ParamField body="tool_choice" type="string | object">
  Control which tools the model uses.

  **Modes:**

  * `"none"` - Don't use any tools
  * `"auto"` - Let model decide (default)
  * `"required"` - Force model to use at least one tool
  * `{ "type": "function", "name": "tool_name" }` - Force specific tool
  * `{ "type": "allowed_tools", "mode": "auto", "tools": [...] }` - Limit to specific tools

  **Examples:**

  ```json theme={null}
  // Auto mode (default)
  { "tool_choice": "auto" }

  // Force specific tool
  {
    "tool_choice": {
      "type": "function",
      "name": "get_weather"
    }
  }

  // Allowed tools
  {
    "tool_choice": {
      "type": "allowed_tools",
      "mode": "required",
      "tools": [
        { "type": "function", "name": "get_weather" },
        { "type": "function", "name": "get_forecast" }
      ]
    }
  }
  ```
</ParamField>

### parallel\_tool\_calls

<ParamField body="parallel_tool_calls" type="boolean">
  Enable the model to call multiple tools in parallel in a single response.

  * `true` - Model can call multiple tools simultaneously (faster for independent operations)
  * `false` - Model calls one tool at a time (default for some providers)

  **When to enable:**

  * Multiple independent tool calls (e.g., get weather for multiple cities)
  * No dependencies between tool calls

  **When to disable:**

  * Sequential operations where order matters
  * Tool calls depend on each other's results
</ParamField>

## Prompt Caching

### cache\_control

<ParamField body="cache_control" type="object">
  Enable prompt caching for specific messages to reduce costs on repeated prefixes.

  <Warning>
    Currently supported by:

    * **Anthropic** provider (Claude models via Anthropic API)
    * **AWS Bedrock** provider (Claude models via AWS Bedrock)

    On OpenAI GPT-5.6 routes, a content block's `cache_control` converts to an
    explicit `prompt_cache_breakpoint` (the block-level TTL does not carry
    over). All other providers ignore `cache_control` settings.
  </Warning>

  **Properties:**

  * `type` (required): "ephemeral" - Type of cache
  * `ttl` (required): "5m" | "1h" - Time-to-live for the cache

  **How it works:**

  * Mark messages that should be cached
  * Subsequent requests with the same prefix will use cached tokens
  * Cached tokens are significantly cheaper than regular input tokens
  * Cache expires after the specified TTL

  **Example:**

  ```json theme={null}
  {
    "model": "anthropic/claude-opus-4-5",
    "input": [
      {
        "role": "system",
        "content": "Very long system prompt with documentation...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "5m"
        }
      },
      {
        "role": "user",
        "content": "Question based on the documentation"
      }
    ]
  }
  ```

  **Cost Savings:**

  * Regular input tokens: Full price
  * Cache write: \~25% more than input tokens (one-time cost)
  * Cache read: \~90% cheaper than input tokens

  **Best Practices:**

  * Only cache substantial prefixes (e.g., over 1000 tokens)
  * Use for repeated system prompts or context
  * Choose TTL based on your usage pattern:
    * `"5m"` for rapid successive requests
    * `"1h"` for regular usage over longer periods
</ParamField>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Create Response" icon="message" href="/docs/api-reference/endpoint/create-response">
    Main endpoint documentation
  </Card>

  <Card title="Auto Routing" icon="route" href="/docs/api-reference/endpoint/auto-routing">
    Intelligent model selection
  </Card>

  <Card title="Streaming" icon="water" href="/docs/api-reference/endpoint/streaming">
    Real-time response streaming
  </Card>

  <Card title="Multi-Modal" icon="image" href="/docs/api-reference/endpoint/multi-modal">
    Send images to vision models
  </Card>

  <Card title="Structured Output" icon="brackets-curly" href="/docs/api-reference/endpoint/structured-output">
    Force JSON responses matching a schema
  </Card>

  <Card title="Prompt Caching" icon="database" href="/docs/api-reference/endpoint/prompt-caching">
    Reduce costs with caching
  </Card>

  <Card title="Guardrails & Redaction" icon="shield" href="/docs/api-reference/endpoint/guardrails-redaction">
    API-key-level redaction controls
  </Card>
</CardGroup>