xAI (Grok)

View Source

Access Grok models with real-time web search and reasoning capabilities.

Configuration

XAI_API_KEY=xai-...

Provider Options

Passed via :provider_options keyword:

max_completion_tokens

  • Type: Integer
  • Purpose: Preferred over max_tokens for Grok-4 models
  • Note: ReqLLM auto-translates max_tokens for models requiring it
  • Example: provider_options: [max_completion_tokens: 2000]

search_parameters

  • Type: Map
  • Purpose: Enable Live Search with real-time web access
  • Keys:
    • mode: "auto" (default), "always", or "never"
    • max_sources: Maximum sources to cite (integer)
    • date_range: "recent", "week", "month", "year"
    • citations: Include citations (boolean)
  • Example:
    provider_options: [
  search_parameters: %{
    mode: "auto",
    max_sources: 5,
    date_range: "recent",
    citations: true
  }
]
  • Note: Live Search incurs additional costs per source

parallel_tool_calls

  • Type: Boolean
  • Default: true
  • Purpose: Allow parallel function calls
  • Example: provider_options: [parallel_tool_calls: true]

stream_options

  • Type: Map
  • Purpose: Configure streaming behavior
  • Example: provider_options: [stream_options: %{include_usage: true}]

xai_structured_output_mode

  • Type: :auto | :json_schema | :tool_strict

  • Default: :auto
  • Purpose: Control structured output strategy
  • :auto: Automatic selection based on model
  • :json_schema: Native response_format (grok-2-1212+)
  • :tool_strict: Strict tool calling fallback
  • Example: provider_options: [xai_structured_output_mode: :json_schema]

response_format

  • Type: Map
  • Purpose: Custom response format configuration
  • Example:
    provider_options: [
  response_format: %{
    type: "json_schema",
    json_schema: %{...}
  }
]

Model-Specific Notes

Grok-4 Models

  • Do NOT support stop, presence_penalty, or frequency_penalty
  • Use max_completion_tokens instead of max_tokens
  • Support native structured outputs

Grok-3-mini Models

  • Support reasoning_effort parameter ("low", "medium", "high")
  • Efficient for cost-sensitive applications

Grok-2 Models (1212+)

  • Support native structured outputs
  • Vision support (grok-2-vision-1212)

Structured Output Schema Constraints

xAI's native structured outputs have limitations (auto-sanitized by ReqLLM):

Not Supported:

  • minLength/maxLength for strings
  • minItems/maxItems/minContains/maxContains for arrays
  • pattern constraints
  • allOf (must be flattened)

Supported:

  • anyOf
  • additionalProperties: false (enforced on root)

Resources