Skip to main content

xAI (Grok)

The xai provider supports xAI's Grok models through an API interface compatible with OpenAI's format, including text, vision, image generation, video generation, and voice workflows.

Setup​

To use xAI's API, set the XAI_API_KEY environment variable or specify via apiKey in the configuration file.

export XAI_API_KEY=your_api_key_here

When xAI is the selected fallback provider family, Promptfoo can use xAI defaults for grading, suggestions, synthesis, and web search. These automatic defaults currently use grok-4.3 on the global endpoint; select grok-4.7, grok-4.6, or grok-4.5 explicitly where they are available. xAI does not currently expose a public embeddings or moderation API, so those defaults fall back to OpenAI when xAI is selected. Explicit provider IDs in your config still take precedence.

Supported Models​

The xAI provider includes support for the following model formats. xAI recommends grok-4.7 for coding, agentic tasks, and knowledge work; consult the public model catalog for current availability.

Legacy xAI model aliases

xAI periodically retires older model slugs and keeps them working through redirects. As of the May 15, 2026 (12:00 PM PT) retirement, requests to the grok-4-1-fast, grok-4-fast, grok-4-0709, and grok-3 families redirect to grok-4.3 and use Grok 4.3 pricing. Requests to grok-code-fast-1 route to grok-build-0.1, while grok-imagine-image-pro routes to grok-imagine-image-quality. For new configs, use a current canonical model ID directly.

Regional model availability

xAI documents Grok 4.7 on its global and US regional endpoints, and announced Grok 4.5 availability in the EU API Console. Check your account before depending on Grok 4.7 in another region; grok-4.3 remains Promptfoo's automatic fallback.

Grok 4.7 Models​

  • xai:grok-4.7 - Chat Completions; 500K context, text and image input, text output
  • xai:responses:grok-4.7 - Responses API, including server-side tools and encrypted reasoning

Use the exact grok-4.7 model ID. Grok 4.7 Fast is available in Cursor and Grok Build, but not on the public xAI API.

Grok 4.6 Models​

  • xai:grok-4.6 - Previous flagship reasoning model for coding, agentic tasks, and knowledge work (500K context, text and image input)

xAI does not publish any aliases for this model, so target the exact grok-4.6 id. There is no grok-4.6-latest.

Grok 4.5 Models​

  • xai:grok-4.5 - Flagship reasoning model for coding, agentic tasks, and knowledge work (500K context, text and image input)
  • xai:grok-4.5-latest - Alias for the Grok 4.5 family
  • xai:grok-build-latest - Alias for the Grok 4.5 family

Grok 4.3 Models​

  • xai:grok-4.3 - General-purpose reasoning model
  • xai:grok-4.3-latest - Alias for the Grok 4.3 family
  • xai:grok-latest - Alias for the Grok 4.3 family

Grok 4.20 Models​

  • xai:grok-4.20-0309-reasoning - Reasoning model
  • xai:grok-4.20 - Alias for the Grok 4.20 reasoning family
  • xai:grok-4.20-reasoning - Alias for the Grok 4.20 reasoning family
  • xai:grok-4.20-reasoning-latest - Alias for the Grok 4.20 reasoning family
  • xai:grok-4.20-0309-non-reasoning - Non-reasoning variant
  • xai:grok-4.20-non-reasoning - Alias for the Grok 4.20 non-reasoning family
  • xai:grok-4.20-non-reasoning-latest - Alias for the Grok 4.20 non-reasoning family
  • xai:grok-4.20-multi-agent-0309 - Multi-agent variant
  • xai:grok-4.20-multi-agent - Alias for the Grok 4.20 multi-agent family
  • xai:grok-4.20-multi-agent-latest - Alias for the Grok 4.20 multi-agent family

Grok 4.1 Fast Models​

These legacy IDs remain recognized for backward compatibility and redirect to Grok 4.3:

  • xai:grok-4-1-fast-reasoning and its -latest aliases - Redirect with low reasoning effort
  • xai:grok-4-1-fast-non-reasoning and its -latest aliases - Redirect with reasoning disabled

Grok Code Fast Models​

  • xai:grok-build-0.1 - Canonical Grok Build coding model (256K context)
  • xai:grok-code-fast-1 - Legacy alias that routes to grok-build-0.1
  • xai:grok-code-fast - Alias for grok-build-0.1
  • xai:grok-code-fast-1-0825 - Versioned alias for grok-build-0.1

Grok-4 Fast Models​

These legacy IDs remain recognized for backward compatibility and redirect to Grok 4.3:

  • xai:grok-4-fast-reasoning and its aliases - Redirect with low reasoning effort
  • xai:grok-4-fast-non-reasoning and its aliases - Redirect with reasoning disabled

Grok-4 Models​

  • xai:grok-4-0709, xai:grok-4, and xai:grok-4-latest - Legacy IDs that redirect to Grok 4.3 with low reasoning effort

Grok-3 Models​

The grok-3, grok-3-beta, grok-3-fast, and related -latest IDs are legacy aliases that redirect to Grok 4.3. Promptfoo also recognizes the older Grok 3 Mini IDs for backward compatibility; verify their availability for your xAI account before relying on them.

Grok-2 and previous Models​

Promptfoo recognizes older grok-2, grok-beta, and vision IDs for existing configs, but they are not in xAI's current public catalog. Use a current model for new configs and verify legacy availability in the xAI Console.

Configuration​

The provider uses OpenAI-compatible configuration options plus Grok-specific options, subject to the model restrictions below. Example usage:

When xAI returns usage.cost_in_usd_ticks, Promptfoo uses that exact billed amount, including cache discounts and request-level pricing adjustments. If ticks are unavailable, Promptfoo falls back to the model's catalog rates and applies the documented 2x premium when the response confirms service_tier: priority. Custom pricing can be set with cost, inputCost, outputCost, and cacheReadCost (all per-token rates); explicit overrides take precedence over reported ticks and are used as final rates without an additional priority multiplier.

providers:
  - id: xai:grok-4.7
    config:
      temperature: 0.7
      reasoning_effort: 'xhigh' # low, medium, high (default), or xhigh
      apiKey: your_api_key_here # Alternative to XAI_API_KEY

Both xai:<model> Chat Completions and xai:responses:<model> support xAI Priority Processing. Set service_tier to priority for higher scheduling priority or default for standard processing; omitting it also uses the default tier. Other OpenAI-compatible tier names are not valid on xAI.

Reasoning Support​

Multiple Grok models support reasoning capabilities:

Grok 4.7 and 4.6: Chat requests can set reasoning_effort to low, medium, high (the default), or xhigh. Responses API requests use reasoning.effort. Reasoning cannot be disabled; Promptfoo rejects none locally.

For Grok 4.7, cap output with max_completion_tokens for Chat Completions or max_output_tokens for Responses. Chat also accepts max_tokens as an alias; use one spelling throughout an eval, including defaults and test cases. Within test options, set a request option directly or under passthrough, not both. Reasoning effort accepts a direct eval variable such as {{ effort }}; see the optional Grok 4.7 providers in the xAI chat example.

Grok 4.5: Chat requests can set reasoning_effort to low, medium, or high (the default); Promptfoo rejects other values locally. Responses API requests use reasoning.effort with the same values.

Grok 4.3: General-purpose reasoning model. Chat requests can set reasoning_effort to none, low, medium, or high; Responses API requests use reasoning.effort.

Grok Code Fast Models: The grok-code-fast-1 family are reasoning models optimized for agentic coding workflows. They support:

  • Function calling and tool usage
  • Web search via search_parameters
  • Fast inference with built-in reasoning

Grok 4.7 Specific Behavior​

The xAI release notes list $2/M input, $0.50/M cached input, and $6/M output. At 200K or more input tokens, the rates are $4/M, $1/M, and $12/M respectively. When the API does not return a billed cost, Promptfoo uses these rates, including the 10% premium on xAI's US endpoint; explicit custom rates still take precedence. As with other Grok 4 reasoning models, Promptfoo strips presence_penalty, frequency_penalty, and stop.

The Responses API returns encrypted reasoning even when include is omitted. Promptfoo keeps it in response.raw.output; pass these items back unchanged when managing conversation history yourself.

Grok 4.5 Specific Behavior​

Grok 4.5 is an earlier model for coding, agentic tasks, and knowledge work:

  • 500K context window with text and image input
  • Configurable reasoning: reasoning_effort accepts low, medium, or high (defaults to high); none is rejected
  • Long-context pricing: requests with at least 200K input tokens use the higher catalog rate ($4/M input, $0.60/M cached input, and $12/M output instead of $2/M, $0.30/M, and $6/M); Promptfoo uses the exact billed ticks when xAI returns them
  • Unsupported parameters: presence_penalty, frequency_penalty, and stop are rejected, and Promptfoo strips them automatically
  • Ignored parameters: xAI silently ignores logprobs and top_logprobs on Grok 4.20 and newer models
  • Server-side tools: use xai:responses:grok-4.5 for web search, X search, code execution, and MCP
providers:
  - id: xai:grok-4.5
    config:
      temperature: 0.7
      reasoning_effort: medium
      max_completion_tokens: 4096

Grok 4.3 Specific Behavior​

Grok 4.3 is a general-purpose alternative for text workflows:

  • Responses API recommended: Use xai:responses:grok-4.3 for server-side tools, multi-turn state, and newer xAI capabilities
  • Configurable reasoning: Set reasoning_effort to none, low, medium, or high
  • Unsupported parameters: Same restrictions as other Grok 4-family reasoning models (presence_penalty, frequency_penalty, and stop)
providers:
  - id: xai:grok-4.3
    config:
      temperature: 0.7
      max_completion_tokens: 4096

Grok-3 Models: Promptfoo retains the legacy Grok 3 Mini reasoning-effort contract for backward compatibility. Use Grok 4.3 or Grok 4.7 for new configurations.

Grok 4.1 Fast Specific Behavior​

These retired IDs redirect to Grok 4.3 but retain their legacy request contract. Promptfoo strips reasoning_effort, presence_penalty, frequency_penalty, and stop from these requests. Target Grok 4.3 directly when you need to control reasoning effort.

providers:
  - id: xai:grok-4.3
    config:
      temperature: 0.7
      reasoning_effort: low
      max_completion_tokens: 4096

Grok-4 Fast Specific Behavior​

These retired reasoning and non-reasoning IDs redirect to Grok 4.3 but retain their legacy request contract. Use Grok 4.3 directly for new configurations.

providers:
  - id: xai:grok-4.3
    config:
      temperature: 0.7
      reasoning_effort: low
      max_completion_tokens: 4096

Grok-4 Specific Behavior​

The retired Grok 4 IDs redirect to Grok 4.3 with low reasoning effort while retaining their legacy request contract. Promptfoo strips unsupported sampling and reasoning-effort parameters; use Grok 4.3 directly for new configurations.

providers:
  - id: xai:grok-4.3
    config:
      temperature: 0.7
      reasoning_effort: low
      max_completion_tokens: 4096

Grok Code Fast Specific Behavior​

Grok Code Fast is retired. For grok-code-fast-1, xAI recommends grok-build-0.1 for code workloads; use xai:grok-build-0.1 in Promptfoo configs instead of relying on the retired slug.

providers:
  - id: xai:grok-build-0.1
    config:
      temperature: 0.1 # Lower temperature often preferred for coding tasks
      max_tokens: 4096

Region Support​

You can specify a region to use a region-specific API endpoint:

providers:
  - id: xai:grok-4.3
    config:
      region: eu-west-1 # Will use https://eu-west-1.api.x.ai/v1

This is equivalent to setting base_url="https://eu-west-1.api.x.ai/v1" in the Python client. The same region option is also accepted by the xAI image, video, Responses, and realtime voice providers.

xAI's global endpoint automatically routes requests to models available to your team. Regional endpoints are useful for data-residency requirements, but model availability varies by region and account. The US endpoint (region: us) currently serves only Grok 4.7 and 4.6, at a 10% token-price premium; grok-4.3 and image, video, and voice APIs are unavailable there. Check the xAI Console or the model's documentation before selecting a regional endpoint.

Live Search (Beta)​

warning

xAI's documentation recommends the Responses API for server-side tools. Promptfoo still passes legacy search_parameters through for older configs, but new search configs should use the Agent Tools API.

Legacy configs can still pass a search_parameters object. The mode field controls how search is used:

  • off – Disable search
  • auto – Model decides when to search (default)
  • on – Always perform live search

Additional fields like sources, from_date, to_date, and return_citations may also be provided.

providers:
  - id: xai:grok-3-beta
    config:
      search_parameters:
        mode: auto
        return_citations: true
        sources:
          - type: web

For a full list of options see the xAI documentation.

Agent Tools API (Responses API)​

Use the xai:responses:<model> provider to access xAI's Agent Tools API, which enables autonomous server-side tool execution for web search, X search, code execution, collections search, and remote MCP tools.

providers:
  - id: xai:responses:grok-4.3
    config:
      temperature: 0.7
      max_output_tokens: 4096
      tools:
        - type: web_search
        - type: x_search

Available Agent Tools​

ToolDescription
web_searchSearch the web and browse pages
x_searchSearch X posts, users, and threads
code_execution / code_interpreterExecute Python code in a sandbox
collections_search / file_searchSearch uploaded knowledge bases
mcpConnect to remote MCP servers

Web Search Tool​

tools:
  - type: web_search
    filters:
      allowed_domains:
        - example.com
        - news.com
      # OR excluded_domains (cannot use both)
    enable_image_understanding: true

X Search Tool​

tools:
  - type: x_search
    from_date: '2025-01-01' # ISO8601 format
    to_date: '2025-11-27'
    allowed_x_handles:
      - elonmusk
    enable_image_understanding: true
    enable_video_understanding: true

Code Interpreter Tool​

tools:
  - type: code_interpreter
    container:
      pip_packages:
        - numpy
        - pandas

Complete Example​

providers:
  - id: xai:responses:grok-4.3
    config:
      temperature: 0.7
      tools:
        - type: web_search
          enable_image_understanding: true
        - type: x_search
          from_date: '2025-01-01'
        - type: code_interpreter
          container:
            pip_packages:
              - numpy
      tool_choice: auto # auto, required, or none
      parallel_tool_calls: true

tests:
  - vars:
      question: What's the latest AI news? Search the web and X.
    assert:
      - type: contains
        value: AI

Responses API Configuration​

ParameterTypeDescription
temperaturenumberSampling temperature (0-2)
max_output_tokensnumberMaximum tokens to generate
max_tool_callsnumberMaximum tool calls for one request
top_pnumberNucleus sampling parameter
toolsarrayAgent tools to enable
tool_choicestringTool selection mode: auto, required, none
parallel_tool_callsbooleanAllow parallel tool execution
streambooleanRequest streamed response deltas
instructionsstringSystem-level instructions
previous_response_idstringFor multi-turn conversations
storebooleanStore response for later retrieval
service_tierstringProcessing tier: default or priority
includearrayAdditional response data to return
reasoningobjectReasoning configuration; Grok 4.7 and 4.6 additionally accept xhigh
response_formatobjectJSON schema for structured output
costnumberPer-token input and output cost override
inputCostnumberPer-token input cost override
outputCostnumberPer-token output cost override
cacheReadCostnumberPer-token cached-input cost override

Supported Models​

The Responses API works with current canonical Grok models, including:

  • grok-4.7 (recommended)
  • grok-4.6
  • grok-4.5
  • grok-4.3
  • grok-4.20-0309-reasoning
  • grok-4.20-0309-non-reasoning
  • grok-4.20-multi-agent-0309
  • grok-build-0.1

Retired aliases may still resolve through xAI's documented redirects; use canonical IDs for new configurations.

If you're using Live Search via search_parameters, migrate to the Responses API:

Before (Live Search - deprecated):

providers:
  - id: xai:grok-4.3
    config:
      search_parameters:
        mode: auto
        sources:
          - type: web
          - type: x

After (Responses API):

providers:
  - id: xai:responses:grok-4.3
    config:
      tools:
        - type: web_search
        - type: x_search

Deferred Chat Completions​

Not Yet Supported

xAI offers Deferred Chat Completions for long-running requests that can be retrieved asynchronously via a request_id. This feature is not yet supported in promptfoo. For async workflows, use the xAI Python SDK directly.

Function Calling​

xAI supports standard OpenAI-compatible function calling for client-side tool execution:

providers:
  - id: xai:grok-4.3
    config:
      tools:
        - type: function
          function:
            name: get_weather
            description: Get the current weather for a location
            parameters:
              type: object
              properties:
                location:
                  type: string
                  description: City and state
              required:
                - location

Structured Outputs​

xAI supports structured outputs via JSON schema:

providers:
  - id: xai:grok-4.3
    config:
      response_format:
        type: json_schema
        json_schema:
          name: analysis_result
          strict: true
          schema:
            type: object
            properties:
              summary:
                type: string
              confidence:
                type: number
            required:
              - summary
              - confidence
            additionalProperties: false

You can also load schemas from external files:

config:
  response_format: file://./schemas/analysis-schema.json

Nested file references and variable rendering are supported (see OpenAI documentation for details).

Vision Support​

For models with vision capabilities, you can include images in your prompts using the same format as OpenAI. Create a prompt.yaml file:

prompt.yaml
- role: user
  content:
    - type: image_url
      image_url:
        url: '{{image_url}}'
        detail: 'high'
    - type: text
      text: '{{question}}'

Then reference it in your promptfoo config:

prompts:
  - file://prompt.yaml

providers:
  - id: xai:grok-4.3

tests:
  - vars:
      image_url: 'https://example.com/image.jpg'
      question: "What's in this image?"

Embeddings​

xAI does not currently expose a public embeddings API. Use the OpenAI provider (or another embedding provider) for similarity assertions.

Image Generation​

xAI also supports image generation through Grok Imagine:

providers:
  - xai:image:grok-imagine-image

Current Grok Imagine image model IDs include:

  • xai:image:grok-imagine-image
  • xai:image:grok-imagine-image-2.0
  • xai:image:grok-imagine-image-quality
  • xai:image:grok-imagine-image-pro

grok-imagine-image-2.0 is xAI's latest image model. It prices per quality/resolution tier rather than at a flat per-image rate, and accepts only low, medium, and auto for quality (not high):

qualityresolutionPrice per image
low / auto1k$0.04
low / auto2k$0.06
medium1k$0.06
medium2k$0.08

grok-imagine-image-quality remains available as a quality-oriented alternative. Older image-model aliases may continue to resolve through xAI-managed redirects.

Example configuration for image generation:

promptfooconfig.yaml
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
prompts:
  - 'A {{style}} painting of {{subject}}'

providers:
  - id: xai:image:grok-imagine-image
    config:
      n: 1 # Number of images to generate (1-10)
      response_format: 'url' # 'url' or 'b64_json'
      aspect_ratio: '16:9'
      resolution: '2k'

tests:
  - vars:
      style: 'impressionist'
      subject: 'sunset over mountains'

Image Editing​

Use the same provider with image, images, or mask inputs to call xAI's image-editing endpoint:

providers:
  - id: xai:image:grok-imagine-image
    config:
      image:
        url: 'https://example.com/source.png'
      mask:
        url: 'https://example.com/mask.png'
      quality: 'high'

prompts:
  - 'Render this as a pencil sketch with detailed shading'

Pricing​

Promptfoo uses the exact usage.cost_in_usd_ticks value returned by xAI when available. When the API omits usage, Promptfoo falls back to its local Imagine image estimate, including documented output rates and source-image media-input charges on edit requests.

Video Generation​

xAI supports the following Grok Imagine video IDs:

Model IDSupported input modesResolutions
grok-imagine-video-1.5Text, image, and reference images or preset voices480p, 720p, 1080p
grok-imagine-video-1.5-previewAlias for Grok Imagine Video 1.5480p, 720p, 1080p
grok-imagine-video-1.5-2026-05-30Dated alias for Grok Imagine Video 1.5480p, 720p, 1080p
grok-imagine-videoText, image, video editing, and reference-to-video input480p, 720p

Grok Imagine Video 1.5 supports text-to-video, image-to-video, and reference-to-video. Use the legacy grok-imagine-video model for video editing.

promptfooconfig.yaml
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
prompts:
  - 'Generate this scene: {{scene}}'

providers:
  - id: xai:video:grok-imagine-video-1.5
    config:
      duration: 5 # 1-15 seconds
      aspect_ratio: '16:9'
      resolution: '1080p'

tests:
  - vars:
      scene: a red panda playing with yarn
    assert:
      - type: cost
        threshold: 1.5

Configuration Options​

OptionTypeDefaultDescription
durationnumber8Video length in seconds (1-15)
aspect_ratiostring16:9Aspect ratio: 16:9, 4:3, 1:1, 9:16, 3:4, 3:2, 2:3
resolutionstring720p480p or 720p; Grok Imagine Video 1.5 also supports 1080p
reference_imagesarray-Up to 7 images for reference-to-video generation
reference_audiosarray-Up to 3 preset voice_id values (Video 1.5 only)
poll_interval_msnumber10000Polling interval in milliseconds
max_poll_time_msnumber600000Maximum wait time (10 minutes)
cacheNamespacestring-Nonsecret account or tenant label that enables persistent video cache reuse

Set cacheNamespace in the provider config to a label unique to the account or tenant, and change it when switching accounts. Cache entries are also scoped to the API endpoint. Never use API keys, tokens, or credential hashes as the namespace. Without a namespace, or with credential-bearing endpoint or input URLs, Promptfoo generates videos without reusing persistent cache entries.

Image-to-Video​

Animate a static image by providing an image URL:

providers:
  - id: xai:video:grok-imagine-video-1.5
    config:
      image:
        url: 'https://example.com/image.jpg'
      duration: 5

Video Editing​

Edit an existing video with text instructions:

providers:
  - id: xai:video:grok-imagine-video
    config:
      video:
        url: 'https://example.com/source-video.mp4'

prompts:
  - 'Make the colors more vibrant and add slow motion'
note

Video editing skips duration, aspect ratio, and resolution validation since these are determined by the source video.

Reference-to-Video​

Guide generation with up to seven reference images and, on Grok Imagine Video 1.5, up to three preset voices:

providers:
  - id: xai:video:grok-imagine-video-1.5
    config:
      reference_images:
        - url: 'https://example.com/person.jpg'
        - url: 'https://example.com/shirt.jpg'
      reference_audios:
        - voice_id: 'eve'
      duration: 15
      resolution: '720p'

Video 1.5 can combine a starting image with reference_images, preset reference_audios, or both. The prompt is optional when an image or reference_images is supplied; text-only and voice-only requests require a non-empty prompt. Reference-to-video cannot be combined with video editing, and its resolution is capped at 720p. The Video 1.5 family supports durations up to 15 seconds. The legacy grok-imagine-video model is limited to 10 seconds for reference-to-video, rejects starting-image/reference-image combinations, and does not support reference_audios. Preset voice IDs are case-insensitive and generally available. Uploaded audio references are restricted to trusted partners in the United States.

Pricing​

Promptfoo uses the exact usage.cost_in_usd_ticks value returned by xAI when available. For generation requests where the output resolution is known, Promptfoo falls back to the video provider's local duration-based estimate when the API omits usage.

ModelMedia input480p output720p output1080p output
grok-imagine-video-1.5$0.01 per image; preset voices free$0.08/sec$0.14/sec$0.25/sec
grok-imagine-video$0.002/image or $0.01/video second$0.05/sec$0.07/secNot supported

The local fallback includes image-input and output-video charges. For a video edit without API usage data, Promptfoo leaves cost undefined because the edit endpoint ignores the configured resolution and the completed response does not report the actual output resolution.

Voice Agent API​

The xAI Voice Agent API enables real-time voice conversations with Grok models via WebSocket. Use the xai:voice:<model> provider format.

providers:
  - xai:voice:grok-voice-think-fast-2.0

Configuration​

providers:
  - id: xai:voice:grok-voice-think-fast-2.0
    config:
      voice: 'eve' # ara, rex, sal, eve, or leo
      instructions: 'You are a helpful voice assistant.'
      modalities: ['text', 'audio']
      turn_detection:
        type: server_vad
        threshold: 0.85
        silence_duration_ms: 500
        prefix_padding_ms: 333
      websocketTimeout: 60000 # Connection timeout in ms
      tools:
        - type: web_search
        - type: x_search

Available Voices​

Use any lowercase built-in voice ID or custom voice ID. Legacy names such as Ara are converted to lowercase. Set config.reasoning.effort to high (default) or none.

VoiceDescription
araFemale voice
rexMale voice
salMale voice
eveFemale voice
leoMale voice

Use grok-voice-think-fast-2.0 for the current flagship model, or grok-voice-latest to follow xAI's recommended alias. xAI's July 29 release notes say the alias moves from 1.0 to 2.0 on August 5, 2026. Version 2.0 costs $0.08 per audio minute; the previous-generation grok-voice-think-fast-1.0 costs $0.05 per audio minute. Both also charge per text input; see Pricing.

Turn Detection​

Use turn_detection to tune server-side voice activity detection:

OptionTypeDescription
typestringserver_vad for automatic detection
thresholdnumberActivation threshold from 0.1 to 0.9
silence_duration_msnumberSilence required before ending the turn
prefix_padding_msnumberAudio kept before detected speech to avoid clipping

Built-in Tools​

The Voice API includes server-side tools that execute automatically:

ToolDescription
web_searchSearch the web for information
x_searchSearch posts on X (Twitter)
file_searchSearch uploaded files in vector stores
tools:
  - type: web_search
  - type: x_search
    allowed_x_handles:
      - elonmusk
      - xai
  - type: file_search
    vector_store_ids:
      - vs-123
    max_num_results: 10

Custom Function Tools and Assertions​

You can define custom function tools inline or load them from external files:

providers:
  - id: xai:voice:grok-voice-think-fast-2.0
    config:
      # Inline tool definition
      tools:
        - type: function
          name: set_volume
          description: Set the device volume level
          parameters:
            type: object
            properties:
              level:
                type: number
                description: Volume level from 0 to 100
            required:
              - level

      # Or load from external file (YAML or JSON)
      # tools: file://tools.yaml

tests:
  - vars:
      question: 'Set the volume to 50 percent'
    assert:
      # Check that the correct function was called with correct arguments
      - type: javascript
        value: |
          const calls = output.functionCalls || [];
          return calls.some(c => c.name === 'set_volume' && c.arguments?.level === 50);

      # Or use tool-call-f1 for function name matching
      - type: tool-call-f1
        value: ['set_volume']
        threshold: 1.0

External tools file example:

tools.yaml
- type: function
  name: get_weather
  description: Get the current weather for a location
  parameters:
    type: object
    properties:
      location:
        type: string
    required:
      - location

- type: function
  name: set_reminder
  description: Set a reminder for the user
  parameters:
    type: object
    properties:
      message:
        type: string
      time:
        type: string
    required:
      - message
      - time

When function tools are used, the provider output includes a functionCalls array with:

  • name: The function name that was called
  • arguments: The parsed arguments object
  • result: The result returned by your function handler (if provided)

Custom Endpoint Configuration​

You can configure a custom WebSocket endpoint for the Voice API, useful for proxies or regional endpoints:

providers:
  - id: xai:voice:grok-voice-think-fast-2.0
    config:
      # Option 1: Full base URL (transforms https:// to wss://)
      apiBaseUrl: 'https://my-proxy.example.com/v1'

      # Option 2: Host only (builds https://{host}/v1)
      # apiHost: 'my-proxy.example.com'

You can also use the XAI_API_BASE_URL environment variable:

export XAI_API_BASE_URL=https://my-proxy.example.com/v1

URL transformation: The provider automatically converts HTTP URLs to WebSocket URLs (https:// → wss://, http:// → ws://) and appends /realtime to reach the Voice API endpoint.

Complete WebSocket URL Override​

For advanced use cases like local testing, custom proxies, or endpoints requiring query parameters, you can provide a complete WebSocket URL that will be used exactly as specified without any transformation:

providers:
  - id: xai:voice:grok-voice-think-fast-2.0
    config:
      # Use this URL exactly as-is (no transformation applied)
      websocketUrl: 'wss://custom-endpoint.example.com/path?token=xyz&session=abc'

This is useful for:

  • Local development and testing with mock servers
  • Custom proxy configurations
  • Adding authentication tokens or session IDs as URL parameters
  • Using alternative WebSocket gateways or regional endpoints

Audio Configuration​

Configure input/output audio formats:

config:
  audio:
    input:
      format:
        type: audio/pcm
        rate: 24000
    output:
      format:
        type: audio/pcm
        rate: 24000

Supported formats: audio/pcm, audio/pcmu, audio/pcma Supported sample rates: 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz

Complete Example​

promptfooconfig.yaml
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
prompts:
  - file://input.json

providers:
  - id: xai:voice:grok-voice-think-fast-2.0
    config:
      voice: 'eve'
      instructions: 'You are a helpful voice assistant.'
      modalities: ['text', 'audio']
      tools:
        - type: web_search

tests:
  - vars:
      question: 'What are the latest AI developments?'
    assert:
      - type: llm-rubric
        value: Provides information about recent AI news

Voice Pricing​

Grok Voice 2.0 pricing is $0.08 per minute plus $0.004 per text input. The default server_vad mode bills session duration; push-to-talk mode bills input and output audio. Tool results have no text-input charge.

Promptfoo keeps elapsed connection time in metadata.durationMs, but it does not have the complete billing duration. Response cost remains unavailable.

For more information on the available models and API usage, refer to the xAI Speech to Speech documentation.

Examples​

For examples demonstrating text generation, image creation, and web search, see the xai example.

npx promptfoo@latest init --example xai/chat

For real-time voice conversations with Grok, see the xai-voice example.

npx promptfoo@latest init --example xai/voice

See Also​

Troubleshooting​

502 Bad Gateway Errors​

If you encounter 502 Bad Gateway errors when using the xAI provider, this typically indicates:

  • An invalid or missing API key
  • Server issues on x.ai's side

The xAI provider will provide helpful error messages to guide you in resolving these issues.

Solution: Verify your XAI_API_KEY environment variable is set correctly. You can obtain an API key from https://x.ai/.

Controlling Retries​

If you're experiencing timeouts or want to control retry behavior:

  • To disable retries for 5XX errors: PROMPTFOO_RETRY_5XX=false
  • To reduce retry delays: PROMPTFOO_REQUEST_BACKOFF_MS=1000 (in milliseconds)

Reference​

Last updated on by renovate[bot]