The bundled `grok` web-search provider prefers xAI OAuth, then falls back
to `XAI_API_KEY` or a plugin web-search key:

```bash
apus models auth login --provider xai --method oauth
apus config set tools.web.search.provider grok
```

The bundled `xai` plugin registers video generation through the shared
`video_generate` tool.

- Default model: `xai/grok-imagine-video`
- Additional model: `xai/grok-imagine-video-1.5`
- Classic modes: text-to-video, image-to-video, reference-image generation,
  remote video edit, and remote video extension
- Video 1.5 mode: image-to-video only, with exactly one first-frame image
- Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`;
  classic and Video 1.5 image-to-video inherit the source image ratio when
  omitted
- Resolutions: classic `480P`/`720P`; Video 1.5 also supports `1080P`; all
  generation modes default to `480P`
- Duration: 1-15 seconds for generation/image-to-video, 1-10 seconds when
  using classic `reference_image` roles, 2-10 seconds for classic extension
- Reference-image generation: set `imageRoles` to `reference_image` for
  every supplied image; xAI accepts up to 7 such images
- Video edit/extend inherit the input video's aspect ratio and resolution;
  those operations do not accept geometry overrides
- Default operation timeout: 600 seconds unless `video_generate.timeoutMs`
  or `agents.defaults.mediaModels.video.timeoutMs` is set

Local video buffers are not accepted. Use remote `http(s)` URLs for video
edit/extend inputs. Image-to-video accepts local image buffers because
Apus encodes those as data URLs for xAI.

Video 1.5 also recognizes xAI's `grok-imagine-video-1.5-preview` and
`grok-imagine-video-1.5-2026-05-30` identifiers. Apus forwards the
selected identifier unchanged, but applies the same image-only validation.

To use xAI as the default video provider:

```json5
{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "xai/grok-imagine-video",
        },
      },
    },
  },
}
```

See [Video Generation](/tools/video-generation) for shared tool
parameters, provider selection, and failover behavior.

The bundled `xai` plugin registers image generation through the shared
`image_generate` tool.

- Default image model: `xai/grok-imagine-image`
- Additional model: `xai/grok-imagine-image-quality`
- Modes: text-to-image and reference-image edit
- Reference inputs: one `image` or up to three `images`
- Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`,
  `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`
- Resolutions: `1K`, `2K`
- Count: up to 4 images
- Default operation timeout: 600 seconds unless `image_generate.timeoutMs`
  or `agents.defaults.mediaModels.image.timeoutMs` is set

Apus asks xAI for `b64_json` image responses so generated media can be
stored and delivered through the normal channel attachment path. Local
reference images are converted to data URLs; remote `http(s)` references
pass through unchanged.

To use xAI as the default image provider:

```json5
{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "xai/grok-imagine-image",
        },
      },
    },
  },
}
```

xAI also documents `quality`, `mask`, `user`, and an `auto` aspect ratio.
Apus forwards only the shared cross-provider image controls today;
these native-only knobs are not exposed through `image_generate`.

The bundled `xai` plugin registers text-to-speech through the shared `tts`
provider surface.

- Voices: authenticated live catalog from xAI; list it with
  `apus infer tts voices --provider xai`
- Offline fallback voices: `ara`, `eve`, `leo`, `rex`, `sal`
- Default voice: `eve`
- Account custom voice IDs are forwarded even when they are absent from the
  built-in catalog response
- Formats: `mp3`, `wav`, `pcm`, `mulaw`, `alaw`
- Language: BCP-47 code or `auto`
- Speed: provider-native speed override
- Native Opus voice-note format is not supported

To use xAI as the default TTS provider:

```json5
{
  tts: {
    provider: "xai",
    providers: {
      xai: {
        voiceId: "eve",
      },
    },
  },
}
```

Apus uses xAI's batch `/v1/tts` endpoint for buffered synthesis,
authenticated `/v1/tts/voices` catalog discovery, and native
`wss://api.x.ai/v1/tts` for streaming synthesis. Streaming is restricted to
the native `api.x.ai` host, so custom `baseUrl` values are rejected on this
path. It uses the existing language, voice, codec, and speed controls; xAI
defaults apply to sample rate and bit rate. Audio-file synthesis honors all
configured codecs. Voice-note targets use MP3 for streaming and buffered
fallback because xAI's raw codecs do not carry codec/rate metadata. The
stream sends `text.delta` then
`text.done`, receives `audio.delta`, `audio.done`, or `error`, and applies an
idle `timeoutMs` that refreshes for every audio chunk. It is separate from
realtime voice sessions. See xAI's [Streaming TTS API](https://docs.x.ai/developers/rest-api-reference/inference/voice) contract.

The bundled `xai` plugin registers batch speech-to-text through Apus's
media-understanding transcription surface.

- Endpoint: xAI REST `/v1/stt`
- Input path: multipart audio file upload
- Model selection: xAI chooses the transcription model internally; the
  endpoint has no model selector
- Used wherever inbound audio transcription reads `tools.media.audio`,
  including Discord voice-channel segments and channel audio attachments

To force xAI for inbound audio transcription:

```json5
{
  tools: {
    media: {
      models: [
        {
          type: "provider",
          provider: "xai",
          capabilities: ["audio"],
        },
      ],
      audio: {
        enabled: true,
      },
    },
  },
}
```

Language can be supplied through the shared audio media config or per-call
transcription request. Prompt hints are accepted by the shared Apus
surface, but the xAI REST STT integration forwards only file and language
because those map to the current public xAI endpoint.

Valid empty transcripts are skipped, and Apus tries any configured
fallback. Malformed responses and HTTP failures remain errors.

The bundled `xai` plugin also registers a realtime transcription provider
for live voice-call audio.

- Endpoint: xAI WebSocket `wss://api.x.ai/v1/stt`
- Default encoding: `mulaw`
- Default sample rate: `8000`
- Default endpointing: `800ms`
- Interim transcripts: enabled by default

Voice Call's Twilio media stream sends G.711 mu-law audio frames, so the
xAI provider forwards those frames directly without transcoding:

```json5
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "xai",
            providers: {
              xai: {
                apiKey: "${XAI_API_KEY}",
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}
```

Provider-owned config lives under
`plugins.entries.voice-call.config.streaming.providers.xai`. Supported
keys are `apiKey`, `baseUrl`, `sampleRate`, `encoding` (`pcm`, `mulaw`, or
`alaw`), `interimResults`, `endpointingMs`, and `language`.

This streaming provider is for Voice Call's realtime transcription path.
Discord voice records short segments and uses the batch
`tools.media.audio` transcription path instead.

The bundled `xai` plugin registers Grok Voice Agent realtime sessions for
Talk mode through the shared `registerRealtimeVoiceProvider` contract.

- Endpoint: `wss://api.x.ai/v1/realtime?model=<voice-model>`
- Default model: `grok-voice-latest`
- Default voice: `eve`
- Transport: `gateway-relay` (iOS, Android, and Control UI relay paths)
- Audio: PCM16 24 kHz or G.711 µ-law 8 kHz
- Barge-in: xAI server VAD interrupts the response; Apus clears queued playback
  and truncates unplayed provider history

Configure Talk on the Gateway:

```json5
{
  talk: {
    realtime: {
      provider: "xai",
      mode: "realtime",
      transport: "gateway-relay",
      brain: "agent-consult",
      providers: {
        xai: {
          model: "grok-voice-latest",
          voice: "eve",
          // Opt in only if provider-side session replay is acceptable.
          sessionResumption: false,
        },
      },
    },
  },
  env: { vars: { XAI_API_KEY: "xai-..." } },
}
```

Provider-owned config also resolves from
`plugins.entries.voice-call.config.realtime.providers.xai` when Voice Call
or shared realtime selectors reuse the same provider map. Supported keys are
`apiKey`, `baseUrl`, `model`, `voice`, `vadThreshold`, `silenceDurationMs`,
`prefixPaddingMs`, `reasoningEffort`, and `sessionResumption`.
`reasoningEffort` accepts only `high` or `none`, matching the xAI Voice Agent API.

xAI's server VAD always creates responses and handles audio interruption.
Use `consultRouting: "provider-direct"`; forced transcript routing and disabling
input-audio interruption are not supported by the xAI Voice Agent protocol.

xAI OAuth or `XAI_API_KEY` can authenticate realtime voice. Browser-owned
WebRTC is not part of this provider surface yet; use gateway-relay Talk on
native nodes or the Control UI relay path.

`sessionResumption` defaults to `false`. When set to `true`, Apus asks
xAI to retain enough session state to resume the same conversation after a
reconnect and then reconnects with the returned conversation id. Leave it
disabled when provider-side replay/retention is not acceptable; interrupted
sockets then fail closed instead of silently starting a fresh conversation.

The bundled xAI plugin exposes `x_search` as an Apus tool for
searching X (formerly Twitter) content via Grok.

Config path: `plugins.entries.xai.config.xSearch`

| Key               | Type    | Default                   | Description                                      |
| ----------------- | ------- | ------------------------- | ------------------------------------------------ |
| `enabled`         | boolean | Automatic for xAI models  | Disable, or opt in for a known non-xAI provider |
| `model`           | string  | `grok-4.7`                | Model used for x_search requests                 |
| `baseUrl`         | string  | -                         | xAI Responses base URL override                  |
| `inlineCitations` | boolean | -                         | Include inline citations in results              |
| `maxTurns`        | number  | -                         | Maximum conversation turns                       |
| `timeoutSeconds`  | number  | `30`                      | Request timeout in seconds                       |
| `cacheTtlMinutes` | number  | `15`                      | Cache time-to-live in minutes                    |

```json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4.3",
            baseUrl: "https://api.x.ai/v1",
            inlineCitations: true,
          },
        },
      },
    },
  },
}
```

The bundled xAI plugin exposes `code_execution` as an Apus tool for
remote code execution in xAI's sandbox environment.

Config path: `plugins.entries.xai.config.codeExecution`

| Key              | Type    | Default                  | Description                                      |
| ---------------- | ------- | ------------------------ | ------------------------------------------------ |
| `enabled`        | boolean | Automatic for xAI models | Disable, or opt in for a known non-xAI provider |
| `model`          | string  | `grok-4.7`               | Model used for code execution requests           |
| `maxTurns`       | number  | -                        | Maximum conversation turns                       |
| `timeoutSeconds` | number  | `30`                     | Request timeout in seconds                       |

This is remote xAI sandbox execution, not local [`exec`](/tools/exec).

```json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          codeExecution: {
            enabled: true,
            model: "grok-4.3",
          },
        },
      },
    },
  },
}
```

Native `api.x.ai` Responses routes use xAI's server-side
[`/responses/compact`](https://docs.x.ai/developers/advanced-api-usage/context-compaction)
endpoint by default for manual `/compact` and threshold-driven preflight
compaction. The session keeps its Apus transcript unchanged and stores
xAI's opaque checkpoint for the next request. Completion notices report
the provider's before and after token counts.

Disable the endpoint for one model with:

```json5
{
  agents: {
    defaults: {
      models: {
        "xai/grok-4.5": {
          params: { responsesCompactEndpoint: false },
        },
      },
    },
  },
}
```

Other Responses-compatible providers can opt in with
`params.responsesCompactEndpoint: true`; non-Responses routes ignore the
setting. The public OpenAI Responses API also enables this endpoint by
default for budget compaction. Its inline `context_management`
compaction is separately controlled by `responsesServerCompaction`.

Endpoint failures fall back to Apus's client-side summarization.
Provider-confirmed overflow recovery never calls the endpoint because
xAI requires the input to fit the model context window before compaction.
Predicted pressure can try the endpoint before submitting the next turn.

- xAI auth can use an API key, environment variable, plugin config
  fallback, or OAuth with an eligible xAI account. OAuth uses device-code
  verification without a localhost callback. xAI decides which accounts
  can receive OAuth API tokens, and the consent page may show Grok Build
  even though Apus does not require the Grok Build app.
- Apus does not currently expose the xAI multi-agent model family. xAI
  serves these models through the Responses API, but they do not accept
  the client-side or custom tools used by Apus's shared agent loop.
  See the
  [xAI multi-agent limitations](https://docs.x.ai/developers/model-capabilities/text/multi-agent#limitations).
- xAI Realtime voice currently exposes gateway-relay Talk transport only.
  Browser-owned provider WebSocket sessions are not wired in the Control UI
  yet.
- xAI image `quality`, image `mask`, and extra native-only aspect ratios are
  not exposed until the shared `image_generate` tool has corresponding
  cross-provider controls.

- Apus applies xAI-specific tool-schema and tool-call compatibility
  fixes automatically on the shared runner path.
- Native `https://api.x.ai/v1` Responses requests keep tool images attached
  to their tool results. On compatibility routes (including Grok OAuth),
  image-capable models receive a labeled user image message immediately
  after each consecutive tool-result group. Parallel results stay together,
  and later turns preserve the historical image position for prompt caching.
  Compaction establishes a new history prefix and result numbering.
- Native xAI requests default `tool_stream: true`. Set
  `agents.defaults.models["xai/<model>"].params.tool_stream` to `false`
  to disable it.
- The bundled xAI wrapper strips unsupported contains-count schema bounds
  and unsupported reasoning *effort* payload keys before sending native
  xAI requests. Grok 4.7 and Grok 4.6 support low, medium, high, and xhigh effort
  (default high). Grok 4.5 supports low, medium, and high effort
  (default high). Grok 4.3 supports none, low, medium, and high
  effort (default low). Other reasoning-capable xAI models do not expose a
  configurable effort control, but still request
  `include: ["reasoning.encrypted_content"]` so prior encrypted reasoning
  can be replayed on follow-up turns.
  For those models, Apus's `off` setting omits the effort override;
  it does not turn off the model's native reasoning.
- `web_search`, `x_search`, and `code_execution` are exposed as Apus
  tools. Apus attaches only the specific xAI built-in each tool needs
  to that tool's request instead of attaching every native tool to every
  chat turn.
- Grok `web_search` reads `plugins.entries.xai.config.webSearch.baseUrl`.
  `x_search` reads `plugins.entries.xai.config.xSearch.baseUrl`, then
  falls back to the Grok web-search base URL.
- `x_search` and `code_execution` are owned by the bundled xAI plugin
  rather than hardcoded into the core model runtime.
- `code_execution` is remote xAI sandbox execution, not local
  [`exec`](/tools/exec).