# Grok Voice · Realtime API

> Realtime na variant ng Grok voice agent para sa streaming, bidirectional na audio at mga pag-uusap sa teksto

Voice agent para sa mga live application gaya ng assistant at phone agent, na nakasentro sa streaming audio at teksto sa parehong direksyon. Katulad ng standard voice modelo ang mga input: `audio_url` para sa speech ng user, opsyonal na mga instruction ng persona sa `prompt`, pagpili ng `voice`, at opsyonal na `tools` para sa web, X o MCP access. Nagbabalik ito ng spoken WAV audio, duration nito at transcript.

- Model id: `xai/grok-voice/realtime`
- Made by: xAI
- Category: Audio
- Output: audio
- Charged by usage (up to $1.494 per run, typical $0.006; the rest of the hold is refunded): $0.00083 / second of the voice session (cheapest run $0.006 (6 API credits))
- Run: `POST https://api.doitong.ru/v1/run/xai/grok-voice/realtime`
- Quote: `POST https://api.doitong.ru/v1/quote/xai/grok-voice/realtime`
- Docs page: https://doitong.com/fil/developers/models/xai/grok-voice/realtime

## Pricing

Price: **$0.00083 / second of the voice session**. Charged by actual usage at $0.00083 / second of the voice session: up to $1.494 per run (the quote gives the maximum for your input), the rest is refunded automatically after the run. A typical run costs $0.006.

The full example input below holds up to $1.494 = 1494 API credits (up to 1800 s of voice session × $0.00083) when it starts; a typical run costs $0.006 (6 API credits).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). This model is charged by usage: `POST https://api.doitong.ru/v1/quote/xai/grok-voice/realtime` with the same JSON body returns the most the run can cost for that input (`credits`, debited when the run starts); after the run you pay the usage the model reports and the rest is refunded automatically. An input whose maximum would exceed the per-run limit is refused with 422. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `audio_url` | `audio` | string (audio URL) | yes |  |  | URL ng audio para sa speech ng user, limitado sa 10 minuto at 50 MB. Maaaring magbigay ng karamihan sa karaniwang audio format; bago matanggap ng Grok ang audio, kino-convert ito sa mono PCM na may 16-bit samples sa 24 kHz. Tumutugon ang agent sa recording gamit ang speech. |
| `prompt` |  | string \| null | no |  | ≤ 20000 characters | Opsyonal na system instruction na nagbibigay ng context ng conversation at tumutukoy sa persona bilang kapalit ng default ng Grok; kapag hindi ito ibinigay, nananatili ang default na persona. |
| `voice` |  | enum (string) \| null | no |  | `carina`, `zagan`, `helix`, `orion`, `luna`, `iris`, `altair`, `zenith`, `perseus`, `helios`, `lux`, `kepler`, `rigel`, `cosmo`, `celeste`, `ursa`, `sirius`, `lumen`, `castor`, `naksh`, `atlas`, `aurora`, `liora`, `ara`, `eve`, `leo`, `rex`, `sal` | Pumili ng built-in xAI voice para palitan ang default ng Grok para sa tugon ng agent; kapag hindi itinakda, nananatili ang default na voice. |
| `tools` |  | object {mcp_servers, web_search, x_search} | no | `{"mcp_servers":[],"web_search":{"enabled":false},"x_search":{"enabled":false}}` |  | Configuration ng tool ng agent para sa server-side use, na nagbubukod sa file_search/collections sa typed configuration dahil sa ZDR. Nagsisimula ang lahat ng tool na disabled; kabilang sa mga suportadong opsyon ang remote MCP tools, web tools, at X tools. |
| `tools.mcp_servers` |  | array of object {allowed_tools, authorization, enabled, headers, server_description, server_label, server_url} | no |  |  | Mga remote MCP server na kinokonektahan ng modelo provider para sa tool execution. |
| `tools.mcp_servers[].allowed_tools` |  | array of string \| null | no |  | ≥ 1 items | Opsyonal na listahan na tumutukoy kung aling mga pangalan ng tool ang inilalantad ng server na ito. |
| `tools.mcp_servers[].authorization` |  | string \| null | no |  |  | Sensitive authorization value na eksklusibong ipinapadala sa modelo provider. |
| `tools.mcp_servers[].enabled` |  | boolean | no | `true` |  | Inclusion flag ng server; inaalis ng false ang server. |
| `tools.mcp_servers[].headers` |  | object \| null | no |  |  | Mga sensitive header para sa MCP kahilingan, na eksklusibong ipinapadala sa modelo provider. |
| `tools.mcp_servers[].server_description` |  | string \| null | no |  | ≤ 2000 characters | Paglalarawan ng mga kakayahang ginagawang available ng server na ito. |
| `tools.mcp_servers[].server_label` |  | string | yes |  | 1 – 128 characters | Label ng server na ginagamit ng modelo provider para tukuyin ang mga tool nito at lagyan ng prefix ang mga pangalan ng mga ito. |
| `tools.mcp_servers[].server_url` |  | string | yes |  | ≥ 1 characters | HTTP(S) address na ibinigay ng caller para sa MCP server na malayuang kinokonektahan ng Grok gamit ang Streaming HTTP/SSE transports. |
| `tools.web_search` |  | object {allowed_domains, enable_image_understanding, enabled, excluded_domains, location} | no | `{"allowed_domains":null,"enable_image_understanding":null,"enabled":false,"excluded_domains":null,"location":null}` |  | Web search na pinamamahalaan ng provider, disabled maliban kung true ang enabled. |
| `tools.web_search.allowed_domains` |  | array of string \| null | no |  | 1 – 5 items | Paghihigpit sa domain para sa mga resulta ng search: tumukoy ng hanggang limang domain, nang walang protocol at path. |
| `tools.web_search.enable_image_understanding` |  | boolean \| null | no |  |  | Pahintulot para suriin ng agent ang mga larawang natuklasan sa web search. |
| `tools.web_search.enabled` |  | boolean | no | `false` |  | Access sa web search para sa agent: idinaragdag ng true ang web_search sa session.tools at pinapahintulutan ang web search; nananatiling disabled ang default. |
| `tools.web_search.excluded_domains` |  | array of string \| null | no |  | 1 – 5 items | Mga domain na hindi isasama sa mga resulta ng search, limitado sa limang entry at walang protocol at path. |
| `tools.web_search.location` |  | object {city, country, region, timezone} \| null | no |  |  | Opsyonal na lokasyon para iangkop sa heograpiya ang mga resulta ng search. |
| `tools.x_search` |  | object {allowed_x_handles, enable_image_understanding, enable_video_understanding, enabled, excluded_x_handles, from_date, to_date} | no | `{"allowed_x_handles":null,"enable_image_understanding":null,"enable_video_understanding":null,"enabled":false,"excluded_x_handles":null,"from_date":null,"to_date":null}` |  | X search na pinamamahalaan ng provider, disabled maliban kung true ang enabled. |
| `tools.x_search.allowed_x_handles` |  | array of string \| null | no |  | 1 – 20 items | Mga X handle na maaaring lumabas ang mga post sa mga resulta, limitado sa 20 handle. |
| `tools.x_search.enable_image_understanding` |  | boolean \| null | no |  |  | Pahintulot para suriin ng agent ang mga larawang natuklasan sa X. |
| `tools.x_search.enable_video_understanding` |  | boolean \| null | no |  |  | Pahintulot para suriin ng agent ang mga video na natuklasan sa X. |
| `tools.x_search.enabled` |  | boolean | no | `false` |  | Access sa mga X post sa pamamagitan ng search: idinaragdag ng true ang x_search sa session.tools upang mahanap ng agent ang mga post na iyon; nananatiling disabled ang default. |
| `tools.x_search.excluded_x_handles` |  | array of string \| null | no |  | 1 – 20 items | Mga X handle na hindi isasama ang mga post, limitado sa 20 handle. |
| `tools.x_search.from_date` |  | string \| null | no |  |  | Pinakamaagang petsa para sa mga post, ipinapahayag sa ISO format na YYYY-MM-DD. |
| `tools.x_search.to_date` |  | string \| null | no |  |  | Pinakahuling petsa para sa mga post, ipinapahayag sa ISO format na YYYY-MM-DD. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Maaaring luwagan ang screening sa pamamagitan ng pagtatakda ng false, kung awtorisado ang tumatawag. |

File parameters (`audio`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{
  "audio": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
}
```

A fuller example:

```json
{
  "audio_url": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.ru/v1/run/xai/grok-voice/realtime?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.ru/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.ru/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/xai/grok-voice/realtime?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "audio_url": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "audio_url": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/xai/grok-voice/realtime", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.ru/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "xai/grok-voice/realtime",
      "input": {
        "audio_url": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "xai/grok-voice/realtime",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 1494,
    "usd": "1.494",
    "charged": 1494,
    "refunded": 0
  },
  "input": {
    "audio_url": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
  },
  "output": {
    "audio": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp3",
      "content_type": "audio/mpeg",
      "file_name": "0-output.mp3",
      "file_size": 1843200
    },
    "text": "",
    "duration": 5
  },
  "outputs": [
    {
      "type": "audio",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp3",
      "content_type": "audio/mpeg",
      "file_size": 1843200,
      "duration": 12,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `audio` | object {url, content_type, file_name, file_size} | Sinasabing tugon mula sa Grok agent, na inihahatid bilang mono WAV sa 24 kHz. |
| `text` | string | Tekstong kasama ng pagsasalita ng agent: nangangahulugang walang transcript na ibinigay ang Grok ang isang walang-lamang string; kung hindi, naglalaman ito ng transcript. |
| `duration` | number | Haba ng nabuong audio, sinusukat sa segundo. |

## Related models

- [Grok Voice](https://doitong.com/developers/models/xai/grok-voice.md) (`xai/grok-voice`): $0.00083 / second of the voice session
- [MMAudio V2](https://doitong.com/developers/models/mmaudio-v2.md) (`mmaudio-v2`): $0.001 / second
- [DeepFilterNet 3](https://doitong.com/developers/models/deepfilternet3.md) (`deepfilternet3`): $0.001 / second of input audio
- [Demucs](https://doitong.com/developers/models/demucs.md) (`demucs`): $0.0007 / second of input audio
- [ElevenLabs Audio Isolation](https://doitong.com/developers/models/elevenlabs/audio-isolation.md) (`elevenlabs/audio-isolation`): $0.10 / minute of input file
- [Elevenlabs Sound Effects V2](https://doitong.com/developers/models/elevenlabs/sound-effects/v2.md) (`elevenlabs/sound-effects/v2`): $0.002 / second
- [ElevenLabs Voice Changer](https://doitong.com/developers/models/elevenlabs/voice-changer.md) (`elevenlabs/voice-changer`): $0.30 / minute of input audio
- [FFmpeg API \[Merge Audios\]](https://doitong.com/developers/models/ffmpeg-api/merge-audios.md) (`ffmpeg-api/merge-audios`): $0.00017 / second of processing time

## Links

- HTML page: https://doitong.com/developers/models/xai/grok-voice/realtime
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=xai/grok-voice/realtime
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.ru/v1/models/xai/grok-voice/realtime