Name: OpenAI Whisper API: Speech to Text Transcription
Brand: magicapi
SKU: api-magicapi-speech-to-text-api-openai-whisper
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎙️ Speech-to-Text Transcription API (OpenAI Whisper)

## Overview
Whisper is a speech recognition model from OpenAI that converts speech in an audio file to text. It detects the spoken language automatically or uses the one you set, and can translate the speech to English.

Send an `audio` file URL. The response is a JSON object with the detected language, the full transcription and a list of timed segments. Choose `plain text`, `srt` or `vtt` for the transcription format.

## Features
- **Transcription**: converts speech in an audio file to text.
- **Language detection**: `language` defaults to `auto`; you can also set one of 100 language codes or their English names.
- **Translation to English**: set `translate` to `true` to translate the speech to English.
- **Subtitle formats**: `transcription` can be `plain text` (default), `srt` or `vtt`.
- **Timed segments**: the output lists segments with start and end times in seconds.
- **Decoding controls**: `temperature`, `patience`, `suppress_tokens`, `initial_prompt`, `condition_on_previous_text` and the fallback thresholds are exposed.

## Use Cases
1. **Meeting and interview transcripts**: turn recordings into searchable text.
2. **Subtitles**: generate `srt` or `vtt` captions for video and podcasts.
3. **Voice notes and support calls**: transcribe audio for search, tagging or analysis.
4. **Multilingual content**: transcribe speech in its own language or translate it to English.

## Visual Examples
### Example Input
Audio (`audio`): a 52-second English recording of read-aloud sentences.

[Listen to the example input audio](https://cdn.api.market/FUguf75BzBwGXZDbrU82_55uMXs3Iq6W/-/mgxm/e5159b1b-508a-4be4-b892-e1eb47850bdc/OSR_uk_000_0050_8k.wav)

Settings: `transcription` `plain text`, `translate` `false`, `temperature` 0, the default thresholds, and `language` left at `auto`.

### Example Output
Detected language: `english`

Transcription (first part): "the little tales they tell are false the door was barred locked and bolted as well ripe pears are fit for a queen's table a big wet stain was on the round carpet the kite dipped and swayed but stayed aloft ..."

The full JSON response is shown under Check Prediction Status below.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `audio` | string (URL) | Yes |  |  | Audio file URL |
| `transcription` | string | No | `plain text` | `plain text`, `srt`, `vtt` | Format of the transcription |
| `translate` | boolean | No | `false` |  | Translate the text to English when set to `true` |
| `language` | string | No | `auto` | `auto`, 100 language codes or their English names (full list below) | Language spoken in the audio; `auto` detects it |
| `temperature` | number | No | `0` |  | Temperature to use for sampling |
| `patience` | number | No | none |  | Optional patience value for beam decoding; the default (1.0) is equivalent to conventional beam search |
| `suppress_tokens` | string | No | `-1` |  | Comma-separated list of token ids to suppress during sampling; `-1` suppresses most special characters except common punctuation |
| `initial_prompt` | string | No | none |  | Optional text to provide as a prompt for the first window |
| `condition_on_previous_text` | boolean | No | `true` |  | If `true`, the previous output is used as a prompt for the next window. Disabling it may make the text inconsistent across windows, but the model becomes less prone to getting stuck in a failure loop |
| `temperature_increment_on_fallback` | number | No | `0.2` |  | Temperature increase when decoding fails to meet either of the thresholds below |
| `compression_ratio_threshold` | number | No | `2.4` |  | If the gzip compression ratio is higher than this value, treat the decoding as failed |
| `logprob_threshold` | number | No | `-1` |  | If the average log probability is lower than this value, treat the decoding as failed |
| `no_speech_threshold` | number | No | `0.6` |  | If the probability of the no-speech token is higher than this value and decoding has failed due to `logprob_threshold`, treat the segment as silence |

### Supported `language` values
Codes: `auto`, `af`, `am`, `ar`, `as`, `az`, `ba`, `be`, `bg`, `bn`, `bo`, `br`, `bs`, `ca`, `cs`, `cy`, `da`, `de`, `el`, `en`, `es`, `et`, `eu`, `fa`, `fi`, `fo`, `fr`, `gl`, `gu`, `ha`, `haw`, `he`, `hi`, `hr`, `ht`, `hu`, `hy`, `id`, `is`, `it`, `ja`, `jw`, `ka`, `kk`, `km`, `kn`, `ko`, `la`, `lb`, `ln`, `lo`, `lt`, `lv`, `mg`, `mi`, `mk`, `ml`, `mn`, `mr`, `ms`, `mt`, `my`, `ne`, `nl`, `nn`, `no`, `oc`, `pa`, `pl`, `ps`, `pt`, `ro`, `ru`, `sa`, `sd`, `si`, `sk`, `sl`, `sn`, `so`, `sq`, `sr`, `su`, `sv`, `sw`, `ta`, `te`, `tg`, `th`, `tk`, `tl`, `tr`, `tt`, `uk`, `ur`, `uz`, `vi`, `yi`, `yo`, `yue`, `zh`

Names: `Afrikaans`, `Albanian`, `Amharic`, `Arabic`, `Armenian`, `Assamese`, `Azerbaijani`, `Bashkir`, `Basque`, `Belarusian`, `Bengali`, `Bosnian`, `Breton`, `Bulgarian`, `Burmese`, `Cantonese`, `Castilian`, `Catalan`, `Chinese`, `Croatian`, `Czech`, `Danish`, `Dutch`, `English`, `Estonian`, `Faroese`, `Finnish`, `Flemish`, `French`, `Galician`, `Georgian`, `German`, `Greek`, `Gujarati`, `Haitian`, `Haitian Creole`, `Hausa`, `Hawaiian`, `Hebrew`, `Hindi`, `Hungarian`, `Icelandic`, `Indonesian`, `Italian`, `Japanese`, `Javanese`, `Kannada`, `Kazakh`, `Khmer`, `Korean`, `Lao`, `Latin`, `Latvian`, `Letzeburgesch`, `Lingala`, `Lithuanian`, `Luxembourgish`, `Macedonian`, `Malagasy`, `Malay`, `Malayalam`, `Maltese`, `Mandarin`, `Maori`, `Marathi`, `Moldavian`, `Moldovan`, `Mongolian`, `Myanmar`, `Nepali`, `Norwegian`, `Nynorsk`, `Occitan`, `Panjabi`, `Pashto`, `Persian`, `Polish`, `Portuguese`, `Punjabi`, `Pushto`, `Romanian`, `Russian`, `Sanskrit`, `Serbian`, `Shona`, `Sindhi`, `Sinhala`, `Sinhalese`, `Slovak`, `Slovenian`, `Somali`, `Spanish`, `Sundanese`, `Swahili`, `Swedish`, `Tagalog`, `Tajik`, `Tamil`, `Tatar`, `Telugu`, `Thai`, `Tibetan`, `Turkish`, `Turkmen`, `Ukrainian`, `Urdu`, `Uzbek`, `Valencian`, `Vietnamese`, `Welsh`, `Yiddish`, `Yoruba`

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.0015 per API unit.
- **1 API unit = 1 request with up to 6 seconds of processing.** A request that runs longer bills one more unit for each started 6-second block (for example, 20 seconds of processing is 4 units, $0.006).
- Processing time grows with the length of the audio, so longer recordings use more units.
- **Example cost**: the example request below (52 seconds of audio) took 8.2 seconds of processing, which is 2 units: $0.003.
- **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/speech-to-text-api-openai-whisper`

### 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/speech-to-text-api-openai-whisper/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "8099696689d249cf8b122d833c36ac3f75505c666a395ca40ef26f68e7d3d16e",
    "input": {
      "audio": "https://cdn.api.market/FUguf75BzBwGXZDbrU82_55uMXs3Iq6W/-/mgxm/e5159b1b-508a-4be4-b892-e1eb47850bdc/OSR_uk_000_0050_8k.wav",
      "translate": false,
      "temperature": 0,
      "transcription": "plain text",
      "suppress_tokens": "-1",
      "logprob_threshold": -1,
      "no_speech_threshold": 0.6,
      "condition_on_previous_text": true,
      "compression_ratio_threshold": 2.4,
      "temperature_increment_on_fallback": 0.2
    }
  }'
```

Response (201 Created):
```json
{
  "id": "xf7psnkzt1rga0d1ccvt8byhtr",
  "version": "8099696689d249cf8b122d833c36ac3f75505c666a395ca40ef26f68e7d3d16e",
  "status": "starting",
  "created_at": "2026-10-22T10:45:44.205Z"
}
```

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

Response when the prediction has finished (200 OK). The example returned 5 segments; only the first is shown here:
```json
{
  "id": "xf7psnkzt1rga0d1ccvt8byhtr",
  "status": "succeeded",
  "output": {
    "detected_language": "english",
    "segments": [
      {
        "avg_logprob": -0.060147291276513075,
        "compression_ratio": 1.412280701754386,
        "end": 18.6,
        "id": 0,
        "no_speech_prob": 0.05821266025304794,
        "seek": 0,
        "start": 0,
        "temperature": 0,
        "text": " the little tales they tell are false the door was barred locked and bolted as well ripe pears are fit for a queen's table a big wet stain was on the round carpet",
        "tokens": [50365, 264, 707, 27254, 436, 980, 366, 7908, 264, 2853, 390, 2159, 986, 9376, 293, 13436, 292, 382, 731, 31421, 520, 685, 366, 3318, 337, 257, 12206, 311, 3199, 257, 955, 6630, 16441, 390, 322, 264, 3098, 18119, 51295]
      }
    ],
    "transcription": " the little tales they tell are false the door was barred locked and bolted as well ripe pears are fit for a queen's table a big wet stain was on the round carpet the kite dipped and swayed but stayed aloft the pleasant hours fly by much too soon the room was crowded with a mild wab the room was crowded with a wild mob this strong arm shall shield your honour she blushed when he gave her a white orchid the beetle droned in the hot june sun thank you",
    "translation": null
  },
  "error": null,
  "created_at": "2026-10-22T10:45:44.205Z",
  "started_at": "2026-10-22T10:45:44.226Z",
  "completed_at": "2026-10-22T10:45:52.450Z"
}
```

`output` is a JSON object. `detected_language` and `transcription` are always present; `transcription` holds the text in the format you chose (`plain text`, `srt` or `vtt`). `segments` lists timed segments with `start` and `end` in seconds, `text` and decoding statistics. `translation` holds the English translation when `translate` is `true` and is `null` otherwise. The output schema also defines optional `txt_file` and `srt_file` URL fields.

### 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` 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/speech-to-text-api-openai-whisper";

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: "8099696689d249cf8b122d833c36ac3f75505c666a395ca40ef26f68e7d3d16e", 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://cdn.api.market/FUguf75BzBwGXZDbrU82_55uMXs3Iq6W/-/mgxm/e5159b1b-508a-4be4-b892-e1eb47850bdc/OSR_uk_000_0050_8k.wav",
  translate: false,
  temperature: 0,
  transcription: "plain text",
  suppress_tokens: "-1",
  logprob_threshold: -1,
  no_speech_threshold: 0.6,
  condition_on_previous_text: true,
  compression_ratio_threshold: 2.4,
  temperature_increment_on_fallback: 0.2
}).then((output) => console.log(output.detected_language, output.transcription));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/speech-to-text-api-openai-whisper"


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": "8099696689d249cf8b122d833c36ac3f75505c666a395ca40ef26f68e7d3d16e", "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")


output = create_and_wait_for_prediction({
    "audio": "https://cdn.api.market/FUguf75BzBwGXZDbrU82_55uMXs3Iq6W/-/mgxm/e5159b1b-508a-4be4-b892-e1eb47850bdc/OSR_uk_000_0050_8k.wav",
    "translate": False,
    "temperature": 0,
    "transcription": "plain text",
    "suppress_tokens": "-1",
    "logprob_threshold": -1,
    "no_speech_threshold": 0.6,
    "condition_on_previous_text": True,
    "compression_ratio_threshold": 2.4,
    "temperature_increment_on_fallback": 0.2,
})
print(output["detected_language"], output["transcription"])
```

## FAQ
- **How do I get subtitles instead of plain text?**
  - Set `transcription` to `srt` or `vtt`. The `transcription` field of the output then holds the subtitle text.
- **Can it translate to English?**
  - Yes. Set `translate` to `true`; the English text is returned in `translation`.
- **Do I need to tell it the language?**
  - No. `language` defaults to `auto` and the detected language is returned in `detected_language`. Setting the language yourself skips detection.
- **What does the `model` field in the example do?**
  - `model` is not an input of this model version, so it has no documented effect. The example request included it; you can leave it out.
- **How much does a transcription cost?**
  - $0.0015 per started 6 seconds of processing. The 52-second example took 8.2 seconds of processing and cost $0.003.
- **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 with OpenAI Whisper: automatic language detection, translation to English, plain text, srt or vtt output and timed segments.