# Grok Voice · Realtime API

> רעאַל־טײַם־וועריאַנט פֿון דעם Grok קול־אַגענט פֿאַר סטרימינג און ביידירעקטיאָנעלע אַודיאָ־ און טעקסט־שמועסן

אַ קול־אַגענט פֿאַר לייוו־אַפּליקאַציעס ווי אַסיסטענטן און טעלעפֿאָן־אַגענטן, געבויט אַרום סטרימינג פֿון אַודיאָ און טעקסט אין ביידע ריכטונגען. די אַרייַנגעבער שטימען מיטן נאָרמאַלן קול־מאָדעל: `audio_url` פֿאַר דעם באַניצערס רייד, אַן אָפּציאָנאַלער `prompt` פֿאַר פּערזענלעכקייט־אנווײַזונגען, אַ `voice`־ברירה און אָפּציאָנאַלע `tools` פֿאַר וועב־, X־ אָדער MCP־צוטריט. עס גיט צוריק גערעדט WAV־אַודיאָ, זײַן געדויער און אַ טראַנסקריפּט.

- 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/yi/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 פֿאַרן באַניצערס רעדע, באַגרענעצט צו 10 מינוט און 50 MB. מע קען צושטעלן די מערסט געוויינטלעכע אַודיאָ־פֿאָרמאַטן; איידער Grok באַקומט די אַודיאָ, ווערט זי קאָנווערטירט צו מאָנאָ PCM מיט 16־ביט סאַמפּלס ביי 24 kHz. דער אַגענט ענטפֿערט אויף דער רעקאָרדירונג מיט רעדע. |
| `prompt` |  | string \| null | no |  | ≤ 20000 characters | אָפּציאָנאַלע סיסטעם־אנווײַזונגען וואָס צושטעלן שמועס־קאָנטעקסט און ספּעציפֿיצירן אַ פּערסאָנאַ אַנשטאָט פון Grok'ס סטאַנדאַרט; אָפּלאָזן זיי האַלט דעם סטאַנדאַרט־פּערסאָנאַ. |
| `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` | אויסקלײַבן אַן אינגעבויטע xAI קול צו איבערשרײַבן Grok'ס סטאַנדאַרט פֿאַר דעם אַגענט'ס ענטפֿער; אָן באַשטעטיקן דעם בלײַבט דער סטאַנדאַרט־קול. |
| `tools` |  | object {mcp_servers, web_search, x_search} | no | `{"mcp_servers":[],"web_search":{"enabled":false},"x_search":{"enabled":false}}` |  | אַגענט־געצייג־קאָנפֿיגוראַציע פֿאַר סערווער־זײַטיקן באַניץ, אויסשליסנדיק file_search/collections פון דער טיפּיזירטער קאָנפֿיגוראַציע צוליב ZDR. אַלע געצייג אָנהייבן אויסגעלאָשן; געשטיצטע אָפּציעס אַרײַננעמען remote MCP tools, web tools און X tools. |
| `tools.mcp_servers` |  | array of object {allowed_tools, authorization, enabled, headers, server_description, server_label, server_url} | no |  |  | רימאָוט MCP סערווערס צו וועלכע דער מאָדעל־פּראָווײַדער פֿאַרבינדט זיך פֿאַר דורכפֿירן געצייג־אָפּעראַציעס. |
| `tools.mcp_servers[].allowed_tools` |  | array of string \| null | no |  | ≥ 1 items | אָפּציאָנאַלע רשימה וואָס ספּעציפֿיצירט וועלכע געצייג־נעמען דער סערווער אַנטפּלעקט. |
| `tools.mcp_servers[].authorization` |  | string \| null | no |  |  | סענסיטיווע אָטעריזאַציע־ווערט געשיקט אויסשליסלעך צום מאָדעל־פּראָווײַדער. |
| `tools.mcp_servers[].enabled` |  | boolean | no | `true` |  | סערווער־אַרײַננעמונג־פֿאָן; false שליסט דעם סערווער אויס. |
| `tools.mcp_servers[].headers` |  | object \| null | no |  |  | סענסיטיווע העדערס פֿאַר MCP בקשות, געשיקט אויסשליסלעך צום מאָדעל־פּראָווײַדער. |
| `tools.mcp_servers[].server_description` |  | string \| null | no |  | ≤ 2000 characters | באַשרײַבונג וואָס צייכנט אויס די מעגלעכקייטן וואָס דער סערווער מאַכט צוטריטלעך. |
| `tools.mcp_servers[].server_label` |  | string | yes |  | 1 – 128 characters | סערווער־לאַבעל געניצט דורך דעם מאָדעל־פּראָווײַדער צו אידענטיפֿיצירן זײַנע געצייג און צולייגן אַ פּרעפֿיקס צו זייערע נעמען. |
| `tools.mcp_servers[].server_url` |  | string | yes |  | ≥ 1 characters | HTTP(S) אַדרעס צוגעשטעלט דורך דעם רופֿער פֿאַר אַן MCP סערווער צו וועלכן Grok פֿאַרבינדט זיך רימאָוט דורך Streaming HTTP/SSE טראַנספּאָרטן. |
| `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}` |  | וועב־זוכן געראטן דורך דעם פּראָווײַדער, אויסגעלאָשן סיידן enabled איז true. |
| `tools.web_search.allowed_domains` |  | array of string \| null | no |  | 1 – 5 items | דאָמיין־באַגרענעצונג פֿאַר זוך־רעזולטאַטן: ספּעציפֿיצירן ביז פֿינף דאָמיינס אָן פּראָטאָקאָלן און פּאַטס. |
| `tools.web_search.enable_image_understanding` |  | boolean \| null | no |  |  | דערלויבעניש פֿאַרן אַגענט צו באַטראַכטן בילדער אַנטדעקט דורך וועב־זוכן. |
| `tools.web_search.enabled` |  | boolean | no | `false` |  | וועב־זוך־צוטריט פֿאַרן אַגענט: true לייגט web_search צו session.tools און דערלויבט וועב־זוכן; דער סטאַנדאַרט לאָזט עס אויסגעלאָשן. |
| `tools.web_search.excluded_domains` |  | array of string \| null | no |  | 1 – 5 items | דאָמיינס צו אויסשליסן פון זוך־רעזולטאַטן, באַגרענעצט צו פֿינף איינטראָגן אָן פּראָטאָקאָלן און פּאַטס. |
| `tools.web_search.location` |  | object {city, country, region, timezone} \| null | no |  |  | אָפּציאָנאַלע אָרט פֿאַר געאָגראַפֿישער צופּאַסונג פון זוך־רעזולטאַטן. |
| `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־זוכן געראטן דורך דעם פּראָווײַדער, אויסגעלאָשן סיידן enabled איז true. |
| `tools.x_search.allowed_x_handles` |  | array of string \| null | no |  | 1 – 20 items | X האַנדלעס וועמענס פּאָסטס קענען זיך באַווײַזן אין די רעזולטאַטן, באַגרענעצט צו 20 האַנדלעס. |
| `tools.x_search.enable_image_understanding` |  | boolean \| null | no |  |  | דערלויבעניש פֿאַרן אַגענט צו באַטראַכטן בילדער אַנטדעקט אויף X. |
| `tools.x_search.enable_video_understanding` |  | boolean \| null | no |  |  | דערלויבעניש פֿאַרן אַגענט צו באַטראַכטן ווידעאָס אַנטדעקט אויף X. |
| `tools.x_search.enabled` |  | boolean | no | `false` |  | צוטריט צו X פּאָסטס דורך זוכן: true לייגט x_search צו session.tools, כּדי דער אַגענט זאָל קענען זוכן די פּאָסטס; דער סטאַנדאַרט לאָזט עס אויסגעלאָשן. |
| `tools.x_search.excluded_x_handles` |  | array of string \| null | no |  | 1 – 20 items | X האַנדלעס וועמענס פּאָסטס ווערן אויסגעשלאָסן, באַגרענעצט צו 20 האַנדלעס. |
| `tools.x_search.from_date` |  | string \| null | no |  |  | פריסטע דאַטע פֿאַר פּאָסטס, אויסגעדריקט אין ISO פֿאָרמאַט YYYY-MM-DD. |
| `tools.x_search.to_date` |  | string \| null | no |  |  | לעצטע דאַטע פֿאַר פּאָסטס, אויסגעדריקט אין ISO פֿאָרמאַט YYYY-MM-DD. |
| `enable_safety_checker` |  | boolean | no | `true` |  | סקרינינג קען ווערן פאַרלייכטערט דורך שטעלן false, אויב דער רופער איז אָטעריזירט. |

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} | גערעדטע ענטפער פֿונעם Grok אַגענט, איבערגעגעבן ווי מאָנאָ WAV ביי 24 kHz. |
| `text` | string | טעקסט וואָס באַגלייט דעם אַגענטס רעדע: אַן ליידיקע שטריקל מיינט, אַז Grok האָט נישט צוגעשטעלט קיין טראַנסקריפּט; אַנדערש אַנטהאַלט עס דעם טראַנסקריפּט. |
| `duration` | number | לענג פֿונעם גענערירטן אַודיאָ, געמאסטן אין סעקונדעס. |

## 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