Name: Grok Speech to Text API: xAI Audio Transcription
Brand: magicapi
SKU: api-magicapi-transcribe-audio-to-text-xai-grok-speech-to-text
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎙️ Speech-to-Text API (xAI Grok Speech to Text)

## Overview
Grok Speech to Text is a transcription model from xAI. Its developer describes it as handling 25 languages, word-level timestamps, speaker diarization, multichannel audio and files up to 500 MB.

Send an `audio` URL and, optionally, its `language`. Turn on `timestamps` for word timings, `diarize` to label speakers and `multichannel` to transcribe each channel separately; these fill the `words` list in the output. With `format_text` and a set `language`, spoken numbers, currencies and units are written in their usual form. The output has the full `text`, the audio `duration` in seconds and the `language`.

## Features
- **25 languages**: set `language` to one of the listed codes or leave it on `auto`.
- **Word timestamps**: `timestamps` adds `start` and `end` for every word.
- **Speaker diarization**: `diarize` adds a `speaker` index to each word.
- **Multichannel audio**: `multichannel` transcribes each channel independently and adds a `channel` index to each word.
- **Written-form numbers**: `format_text` turns 'one hundred dollars' into '$100' (requires `language`).
- **Large files**: WAV, MP3, WebM, OGG, M4A, FLAC, AAC, MP4 and Opus up to 500 MB.

## Use Cases
1. **Meeting and call transcripts**: transcribe recordings and separate speakers with `diarize`.
2. **Subtitles and captions**: time captions with word-level `timestamps`.
3. **Two-channel call recordings**: transcribe agent and customer channels separately with `multichannel`.
4. **Searchable audio archives**: turn podcasts, lectures and interviews into text.

## Visual Examples
### Example Input
A 60-second English audiobook clip, with `language` set to `en` and `format_text` on. Timestamps, diarization and multichannel were off.

```json
{
  "audio": "https://blog.api.market/wp-content/uploads/2026/10/scribe-v2-input-api-market.mp3",
  "diarize": false,
  "language": "en",
  "timestamps": false,
  "format_text": true,
  "multichannel": false
}
```

### Example Output
The model returned the transcript (shortened here), the audio duration and the language:

```json
{
  "duration": 60.029,
  "language": "en",
  "text": "Section zero of Personal Memoirs of U. S. Grant. This is a LibriVox recording. All LibriVox recordings are in the public domain. For more information or to volunteer, please visit LibriVox.org. Recording by Jim Clevenger. Personal Memoirs of U. S. Grant by Ulysses S. Grant. Preface. ...",
  "words": null
}
```

`words` is `null` because `timestamps`, `diarize` and `multichannel` were all off.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `audio` | string (URL) | Yes |  |  | Audio file URL to transcribe. Supports WAV, MP3, WebM, OGG, M4A, FLAC, AAC, MP4 and Opus, up to 500 MB |
| `language` | string | No | `auto` | `auto`, `ar`, `cs`, `da`, `de`, `en`, `es`, `fa`, `fil`, `fr`, `hi`, `id`, `it`, `ja`, `ko`, `mk`, `ms`, `nl`, `pl`, `pt`, `ro`, `ru`, `sv`, `th`, `tr`, `vi` | Language code of the audio, for example 'en', 'fr' or 'de'. Needed for format_text. auto lets the model detect the language |
| `format_text` | boolean | No | `false` |  | Inverse text normalization: converts spoken-form numbers, currencies and units to written form (for example 'one hundred dollars' becomes '$100'). Requires language to be set |
| `multichannel` | boolean | No | `false` |  | Transcribe each audio channel separately. Each word in the output then has a 'channel' index |
| `diarize` | boolean | No | `false` |  | Speaker diarization. Each word in the output then has a 'speaker' index identifying who spoke it |
| `timestamps` | boolean | No | `false` |  | Include word-level start and end timestamps in the output |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.0021 per API unit.
- **1 API unit = 1 started minute of input audio**, as measured by the model for each request. One hour of audio is 60 units ($0.126).
- A 90-second file counts as 2 units ($0.0042). Language, timestamps, diarization, multichannel and text formatting do not change the price.
- If a request reports no audio length, it is billed as 10 units ($0.021).
- **Example cost**: the 60.03-second example was measured as 2 started minutes: 2 API units = **$0.0042**.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/transcribe-audio-to-text-xai-grok-speech-to-text`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/transcribe-audio-to-text-xai-grok-speech-to-text/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "xai/grok-speech-to-text",
    "input": {
      "audio": "https://blog.api.market/wp-content/uploads/2026/10/scribe-v2-input-api-market.mp3",
      "diarize": false,
      "language": "en",
      "timestamps": false,
      "format_text": true,
      "multichannel": false
    }
  }'
```

Response (201 Created):
```json
{
  "id": "136s76t87xrmy0d1cd79c3g334",
  "version": "xai/grok-speech-to-text",
  "status": "starting",
  "created_at": "2026-10-22T11:10:37.257Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/transcribe-audio-to-text-xai-grok-speech-to-text/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "136s76t87xrmy0d1cd79c3g334",
  "status": "succeeded",
  "output": {
    "duration": 60.029,
    "language": "en",
    "text": "Section zero of Personal Memoirs of U. S. Grant. This is a LibriVox recording. All LibriVox recordings are in the public domain. For more information or to volunteer, please visit LibriVox.org. Recording by Jim Clevenger. Personal Memoirs of U. S. Grant by Ulysses S. Grant. Preface. ...",
    "words": null
  },
  "error": null,
  "created_at": "2026-10-22T11:10:37.257Z",
  "started_at": "2026-10-22T11:10:37.271Z",
  "completed_at": "2026-10-22T11:10:38.523Z"
}
```

`output` is an object with `text`, `duration` (seconds of audio) and `language`. `words` is a list of words with `text`, `start`, `end` and, when enabled, `speaker` and `channel`; it is `null` when timestamps, diarization and multichannel are off.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `audio` or a `language` code that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/transcribe-audio-to-text-xai-grok-speech-to-text";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "xai/grok-speech-to-text", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
    "audio": "https://blog.api.market/wp-content/uploads/2026/10/scribe-v2-input-api-market.mp3",
    "diarize": false,
    "language": "en",
    "timestamps": false,
    "format_text": true,
    "multichannel": false
  }).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/transcribe-audio-to-text-xai-grok-speech-to-text"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "xai/grok-speech-to-text", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


print(create_and_wait_for_prediction({
    "audio": "https://blog.api.market/wp-content/uploads/2026/10/scribe-v2-input-api-market.mp3",
    "diarize": False,
    "language": "en",
    "timestamps": False,
    "format_text": True,
    "multichannel": False
}))
```

## FAQ
- **Which languages are supported?**
  - `ar`, `cs`, `da`, `de`, `en`, `es`, `fa`, `fil`, `fr`, `hi`, `id`, `it`, `ja`, `ko`, `mk`, `ms`, `nl`, `pl`, `pt`, `ro`, `ru`, `sv`, `th`, `tr` and `vi`. Leave `language` on `auto` to detect it.
- **How do I get word timestamps or speaker labels?**
  - Set `timestamps` and/or `diarize` to `true`. The `words` list then holds each word with `start`, `end` and a `speaker` index.
- **Why did `format_text` not change my numbers?**
  - It requires `language` to be set to a language code rather than `auto`.
- **How is a file priced?**
  - $0.0021 per started minute of audio. The 60.03-second example counted as 2 minutes ($0.0042); an hour costs $0.126.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page. You can also email our support team at hello@magicapi.com.


Transcribe audio files up to 500 MB in 25 languages with xAI's Grok, with word-level timestamps, speaker diarization and multichannel support.