# Grok Voice · Realtime API

> Biến thể thời gian thực của tác nhân giọng nói Grok cho hội thoại âm thanh và văn bản hai chiều dạng streaming

Tác nhân giọng nói dành cho các ứng dụng trực tiếp như trợ lý và tác nhân điện thoại, dựa trên âm thanh và văn bản streaming theo cả hai chiều. Đầu vào giống mô hình giọng nói tiêu chuẩn: `audio_url` cho lời nói của người dùng, `prompt` tùy chọn cho chỉ dẫn tính cách, lựa chọn `voice` và `tools` tùy chọn để truy cập web, X hoặc MCP. Trả về âm thanh WAV có lời nói, thời lượng và bản chép lời.

- 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/vi/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 âm thanh cho lời nói của người dùng, tối đa 10 phút và 50 MB. Có thể cung cấp hầu hết định dạng âm thanh phổ biến; trước khi Grok nhận âm thanh, âm thanh được chuyển đổi thành PCM mono với mẫu 16 bit ở 24 kHz. Tác nhân phản hồi bản ghi bằng lời nói. |
| `prompt` |  | string \| null | no |  | ≤ 20000 characters | Chỉ dẫn hệ thống tùy chọn cung cấp ngữ cảnh hội thoại và chỉ định vai trò thay cho vai trò mặc định của Grok; bỏ qua sẽ giữ vai trò mặc định đó. |
| `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` | Chọn giọng nói xAI tích hợp để ghi đè giọng mặc định của Grok cho phản hồi của tác nhân; không đặt giá trị này sẽ giữ giọng mặc định. |
| `tools` |  | object {mcp_servers, web_search, x_search} | no | `{"mcp_servers":[],"web_search":{"enabled":false},"x_search":{"enabled":false}}` |  | Cấu hình công cụ của tác nhân cho việc sử dụng phía máy chủ, loại trừ file_search/collections khỏi cấu hình kiểu do ZDR. Tất cả công cụ ban đầu đều bị tắt; các tùy chọn được hỗ trợ gồm công cụ MCP từ xa, công cụ web và công cụ X. |
| `tools.mcp_servers` |  | array of object {allowed_tools, authorization, enabled, headers, server_description, server_label, server_url} | no |  |  | Các máy chủ MCP từ xa mà nhà cung cấp mô hình kết nối để thực thi công cụ. |
| `tools.mcp_servers[].allowed_tools` |  | array of string \| null | no |  | ≥ 1 items | Danh sách tùy chọn chỉ định tên các công cụ mà máy chủ này cung cấp. |
| `tools.mcp_servers[].authorization` |  | string \| null | no |  |  | Giá trị ủy quyền nhạy cảm chỉ được gửi đến nhà cung cấp mô hình. |
| `tools.mcp_servers[].enabled` |  | boolean | no | `true` |  | Cờ đưa máy chủ vào; false loại trừ máy chủ. |
| `tools.mcp_servers[].headers` |  | object \| null | no |  |  | Các header nhạy cảm cho yêu cầu MCP, chỉ được gửi đến nhà cung cấp mô hình. |
| `tools.mcp_servers[].server_description` |  | string \| null | no |  | ≤ 2000 characters | Mô tả các khả năng mà máy chủ này cung cấp. |
| `tools.mcp_servers[].server_label` |  | string | yes |  | 1 – 128 characters | Nhãn máy chủ được nhà cung cấp mô hình sử dụng để xác định công cụ và thêm tiền tố vào tên của chúng. |
| `tools.mcp_servers[].server_url` |  | string | yes |  | ≥ 1 characters | Địa chỉ HTTP(S) do bên gọi cung cấp cho máy chủ MCP mà Grok kết nối từ xa qua các phương thức truyền 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}` |  | Tìm kiếm web do nhà cung cấp quản lý, bị tắt trừ khi enabled là true. |
| `tools.web_search.allowed_domains` |  | array of string \| null | no |  | 1 – 5 items | Giới hạn miền cho kết quả tìm kiếm: chỉ định tối đa năm miền, bỏ qua giao thức và đường dẫn. |
| `tools.web_search.enable_image_understanding` |  | boolean \| null | no |  |  | Quyền cho tác nhân kiểm tra hình ảnh được phát hiện qua tìm kiếm web. |
| `tools.web_search.enabled` |  | boolean | no | `false` |  | Quyền truy cập tìm kiếm web cho tác nhân: true thêm web_search vào session.tools và cho phép tìm kiếm web; mặc định để tính năng này tắt. |
| `tools.web_search.excluded_domains` |  | array of string \| null | no |  | 1 – 5 items | Các miền cần loại trừ khỏi kết quả tìm kiếm, tối đa năm mục và bỏ qua giao thức cùng đường dẫn. |
| `tools.web_search.location` |  | object {city, country, region, timezone} \| null | no |  |  | Vị trí tùy chọn để điều chỉnh kết quả tìm kiếm theo khu vực địa lý. |
| `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}` |  | Tìm kiếm X do nhà cung cấp quản lý, bị tắt trừ khi enabled là true. |
| `tools.x_search.allowed_x_handles` |  | array of string \| null | no |  | 1 – 20 items | Các handle X có bài đăng có thể xuất hiện trong kết quả, tối đa 20 handle. |
| `tools.x_search.enable_image_understanding` |  | boolean \| null | no |  |  | Quyền cho tác nhân kiểm tra hình ảnh được phát hiện trên X. |
| `tools.x_search.enable_video_understanding` |  | boolean \| null | no |  |  | Quyền cho tác nhân kiểm tra video được phát hiện trên X. |
| `tools.x_search.enabled` |  | boolean | no | `false` |  | Quyền truy cập bài đăng X qua tìm kiếm: true thêm x_search vào session.tools để tác nhân có thể tìm kiếm các bài đăng đó; mặc định để tính năng này tắt. |
| `tools.x_search.excluded_x_handles` |  | array of string \| null | no |  | 1 – 20 items | Các handle X có bài đăng bị loại trừ, tối đa 20 handle. |
| `tools.x_search.from_date` |  | string \| null | no |  |  | Ngày sớm nhất của các bài đăng, biểu thị theo định dạng ISO YYYY-MM-DD. |
| `tools.x_search.to_date` |  | string \| null | no |  |  | Ngày muộn nhất của các bài đăng, biểu thị theo định dạng ISO YYYY-MM-DD. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Có thể nới lỏng việc kiểm duyệt bằng cách đặt thành false, nếu người gọi được cấp quyền. |

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} | Câu trả lời bằng giọng nói từ tác nhân Grok, được cung cấp dưới dạng WAV mono ở 24 kHz. |
| `text` | string | Văn bản đi kèm với lời nói của tác nhân: chuỗi trống cho biết Grok không cung cấp bản chép lời; nếu không, chuỗi này chứa bản chép lời. |
| `duration` | number | Độ dài âm thanh được tạo, tính theo giây. |

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