# Grok — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API |
> |---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> xAI models — chat, web/X search, code execution, image generation/editing, and text-to-speech.

**Category:** AI / LLM | **Website:** [x.ai](https://x.ai) | **Docs:** [docs.x.ai](https://docs.x.ai)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/grok/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

> Also available via public x402 on Base (no account needed): [x402/grok.md](https://beta.paywithlocus.com/x402/grok.md)

> Also available via MPP (no account needed): [mpp/grok.md](https://beta.paywithlocus.com/mpp/grok.md)

## Endpoints

### Chat Completions

Generate text with Grok models. OpenAI-compatible format with support for text, vision, and function calling.

**Estimated cost:** Usage-based; the 402 challenge advertises the authorization maximum

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | Metered x402 model ID: 'grok-4.5', 'grok-4.5-latest', 'grok-4.3', 'grok-4.20-0309-reasoning', or 'grok-4.20-0309-non-reasoning'. Multi-agent is excluded because xAI does not support an output-token cap for it. |
| `messages` | array | Yes | Conversation messages. Each: { role: "system"\|"user"\|"assistant", content: "text" } or multimodal: { role: "user", content: [{ type: "text", text: "..." }, { type: "image_url", image_url: { url: "..." } }] } |
| `temperature` | number | No | Sampling temperature (0.0–2.0, default 1.0) |
| `top_p` | number | No | Nucleus sampling threshold (0.0–1.0) |
| `max_tokens` | number | Yes | Maximum output tokens. Required to bound metered x402 authorization. |
| `stop` | string \| string[] | No | Stop sequences |
| `frequency_penalty` | number | No | Frequency penalty (-2.0 to 2.0, default 0) |
| `presence_penalty` | number | No | Presence penalty (-2.0 to 2.0, default 0) |
| `n` | number | No | Number of completions to generate (default 1) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/grok/chat \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<string>","messages":"<array>","temperature":"<number>","top_p":"<number>","max_tokens":"<number>","stop":"<string | string[]>","frequency_penalty":"<number>","presence_penalty":"<number>","n":"<number>"}'
```

### Image Generation

Generate images from text prompts using Grok Imagine models.

**Estimated cost:** $0.02–$0.08 per image

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image to generate |
| `model` | string | Yes | Metered x402 image model ID: 'grok-imagine-image' or 'grok-imagine-image-quality' |
| `n` | number | No | Number of images to generate (default 1) |
| `aspect_ratio` | string | No | Aspect ratio (e.g. '1:1', '16:9', '9:16', '4:3', '3:2', 'auto') |
| `resolution` | string | No | Output resolution: '1k' (default) or '2k' |
| `response_format` | string | No | Response format: 'url' (default) or 'b64_json' |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/grok/image-generate \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"<string>","model":"<string>","n":"<number>","aspect_ratio":"<string>","resolution":"<string>","response_format":"<string>"}'
```

### Image Editing

Edit existing images with natural language. Provide a source image and describe the changes.

**Estimated cost:** $0.02–$0.08 per image

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the edits to apply (e.g. "Add a hat to the person") |
| `image` | object | Yes | Source image: { url: "https://..." } or { url: "data:image/jpeg;base64,..." } |
| `model` | string | Yes | Metered x402 image model ID: 'grok-imagine-image' or 'grok-imagine-image-quality' |
| `n` | number | No | Number of edited images to generate (default 1) |
| `resolution` | string | No | Output resolution: '1k' (default) or '2k' |
| `response_format` | string | No | Response format: 'url' (default) or 'b64_json' |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/grok/image-edit \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"<string>","image":"<object>","model":"<string>","n":"<number>","resolution":"<string>","response_format":"<string>"}'
```

### Chat with Web Search

Generate text with Grok models grounded in live web search results. Uses the xAI Responses API with automatic web search. Requires a grok-4 family model.

**Estimated cost:** Usage-based; the 402 challenge advertises the authorization maximum

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | Metered x402 model ID: 'grok-4.5', 'grok-4.5-latest', 'grok-4.3', 'grok-4.20-0309-reasoning', or 'grok-4.20-0309-non-reasoning'. Multi-agent is excluded because xAI does not support an output-token cap for it. |
| `messages` | array | Yes | Conversation messages. Each: { role: "system"\|"user"\|"assistant", content: "text" } |
| `search_parameters` | object | No | Web search filters: { allowed_domains: string[] (max 5), excluded_domains: string[] (max 5) } |
| `temperature` | number | No | Sampling temperature (0.0–2.0, default 1.0) |
| `max_tokens` | number | Yes | Maximum output tokens per model turn. Required for metered x402. |
| `max_tool_calls` | number | Yes | Maximum server tool calls (1–10). Sets the metered x402 spend bound. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/grok/web-search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<string>","messages":"<array>","search_parameters":"<object>","temperature":"<number>","max_tokens":"<number>","max_tool_calls":"<number>"}'
```

### Chat with X Search

Generate text with Grok models grounded in live X (Twitter) search results. Uses the xAI Responses API with X search. Requires a grok-4 family model.

**Estimated cost:** Usage-based; the 402 challenge advertises the authorization maximum

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | Metered x402 model ID: 'grok-4.5', 'grok-4.5-latest', 'grok-4.3', 'grok-4.20-0309-reasoning', or 'grok-4.20-0309-non-reasoning'. Multi-agent is excluded because xAI does not support an output-token cap for it. |
| `messages` | array | Yes | Conversation messages. Each: { role: "system"\|"user"\|"assistant", content: "text" } |
| `temperature` | number | No | Sampling temperature (0.0–2.0, default 1.0) |
| `max_tokens` | number | Yes | Maximum output tokens per model turn. Required for metered x402. |
| `max_tool_calls` | number | Yes | Maximum server tool calls (1–10). Sets the metered x402 spend bound. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/grok/x-search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<string>","messages":"<array>","temperature":"<number>","max_tokens":"<number>","max_tool_calls":"<number>"}'
```

### Chat with Code Execution

Generate text with Grok models that can write and execute code in a sandboxed environment. Uses the xAI Responses API with code execution. Requires a grok-4 family model.

**Estimated cost:** Usage-based; the 402 challenge advertises the authorization maximum

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | Metered x402 model ID: 'grok-4.5', 'grok-4.5-latest', 'grok-4.3', 'grok-4.20-0309-reasoning', or 'grok-4.20-0309-non-reasoning'. Multi-agent is excluded because xAI does not support an output-token cap for it. |
| `messages` | array | Yes | Conversation messages. Each: { role: "system"\|"user"\|"assistant", content: "text" } |
| `tools` | array | No | Additional tools to enable alongside code execution. |
| `temperature` | number | No | Sampling temperature (0.0–2.0, default 1.0) |
| `max_tokens` | number | Yes | Maximum output tokens per model turn. Required for metered x402. |
| `max_tool_calls` | number | Yes | Maximum server tool calls (1–10). Sets the metered x402 spend bound. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/grok/code-execution \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<string>","messages":"<array>","tools":"<array>","temperature":"<number>","max_tokens":"<number>","max_tool_calls":"<number>"}'
```

### Text-to-Speech

Convert text to spoken audio. Supports multiple voices, speech tags for expressive delivery, and various output formats.

**Estimated cost:** ~$0.005 per 1,000 characters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | Yes | Text to convert to speech (max 15,000 characters). Supports inline speech tags like [pause], [laugh], <whisper>text</whisper>. |
| `language` | string | Yes | BCP-47 language code (e.g. 'en', 'zh', 'fr', 'de', 'ja') or 'auto' for detection |
| `voice_id` | string | No | Voice: 'eve' (energetic, default), 'ara' (warm), 'rex' (confident), 'sal' (smooth), 'leo' (authoritative) |
| `output_format` | object | No | Audio format config: { codec: 'mp3'\|'wav'\|'pcm'\|'mulaw'\|'alaw', sample_rate: 24000, bit_rate: 128000 } |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/grok/tts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<string>","language":"<string>","voice_id":"<string>","output_format":"<object>"}'
```