# Transcribe speech (REST)

> Submit an audio file to POST /api/v1/stt/submit/ and poll GET /api/v1/stt/status/{job_id}/ for the transcript as JSON or SRT.

Transcription of a file is asynchronous: submit the file, receive a `job_id`, then poll the status endpoint until the job is finished.

Requirements: an API key whose allowed services include `stt`.

## Submit a job

`POST https://moknah.io/api/v1/stt/submit/` with `multipart/form-data`.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio` | file | yes | | The audio file, for example MP3, WAV or M4A. At most 50 MB. |
| `language` | string | no | `ar-SA` | Language and region of the speech, for example `ar-SA`, `ar-JO`, `ar-EG`, `en-US`. |
| `output_format` | string | no | `json` | `json` or `srt`. |

Response `202`:

```json
{
  "job_id": 48213,
  "status": "queued",
  "message": "Audio submitted. Use the job_id to poll for completion."
}
```

Credits for the whole file are taken when the job is accepted, from the duration of the audio.

### Submit errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | A field is missing or invalid, or the file is larger than 50 MB. |
| 400 | `INVALID_AUDIO` | The file could not be read as audio. |
| 401 | `authentication_failed` | Missing, invalid or inactive key, or IP not allowed. |
| 402 | `INSUFFICIENT_CREDITS` | The balance does not cover the file. |
| 403 | (flat `detail`) | The key's allowed services do not include `stt`. |
| 429 | `RATE_LIMIT_EXCEEDED` | Requests per minute or credits per minute exceeded. |

## Check a job

`GET https://moknah.io/api/v1/stt/status/{job_id}/`

Only the key that submitted the job can read it.

| Job state | Response |
| --- | --- |
| Waiting | `200` `{"status": "queued"}` |
| Running | `200` `{"status": "processing"}` |
| Finished, `output_format` `json` | `200` with the JSON below |
| Finished, `output_format` `srt` | `200` with the SRT file itself: `Content-Type: text/plain; charset=utf-8`, sent as an attachment named `transcript_{job_id}.srt`. This response is not JSON. |
| Failed | `500` with code `JOB_FAILED` |
| Unknown id, or a job of another key | `404` with code `JOB_NOT_FOUND` |

Finished job, JSON:

```json
{
  "status": "completed",
  "duration_seconds": 73.4,
  "language": "ar-SA",
  "result": {
    "subtitles": [
      {"start_time": "00:00:00,150", "end_time": "00:00:03,900", "text": "مرحبا بك في منصة مكنة"}
    ]
  }
}
```

`result.subtitles` is a list of subtitle lines, each with `start_time`, `end_time` and `text`. Timestamps use the SRT time format `HH:MM:SS,mmm`.

When a job fails, the credits taken at submission are refunded automatically.

## Credits

Charged per minute of audio, in proportion to the file's duration. The current rate is in [Pricing](../pricing/index.md).

## Example

```python
import time
import requests

API = "https://moknah.io/api/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

with open("interview.mp3", "rb") as audio:
    submitted = requests.post(
        f"{API}/stt/submit/",
        headers=HEADERS,
        files={"audio": ("interview.mp3", audio, "audio/mpeg")},
        data={"language": "ar-JO", "output_format": "json"},
    )
submitted.raise_for_status()
job_id = submitted.json()["job_id"]

while True:
    response = requests.get(f"{API}/stt/status/{job_id}/", headers=HEADERS)
    if response.status_code != 200:
        print("Failed:", response.status_code, response.text)
        break
    result = response.json()
    if result.get("status") in ("queued", "processing"):
        time.sleep(5)
        continue
    for line in result["result"]["subtitles"]:
        print(line)
    break
```

```bash
curl -X POST "https://moknah.io/api/v1/stt/submit/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio=@interview.mp3" \
  -F "language=ar-JO" \
  -F "output_format=srt"

curl "https://moknah.io/api/v1/stt/status/48213/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output transcript.srt
```

## Notes

- Poll every few seconds. Long files can take several minutes.
- With `output_format` `srt`, check the status code and `Content-Type` before parsing: while the job is running the response is JSON, and when it is finished the response is the SRT text.
- The web app's Speech to Text tool does more than this endpoint: syncing your own text, translating subtitles and burning them onto a video. Those steps are not available through the API. See [Speech to Text](../products/speech-to-text.md).
