import { Tabs, TabsContent, TabsList, TabsTrigger } from "zudoku/ui/Tabs";

# Sync Transcribe

The Sync Transcription endpoint accepts audio files and returns transcribed text within the same HTTP request/response cycle.

`POST` <span href="" style={{"cursor": "none", "pointer-events": "none"}}>https://api.lelapa.ai/v1/transcribe/sync</span>

### Supported Audio Formats

- WAV
- MP3
- FLAC
- AAC
- OGG
- MP4
- AIFF
- OPUS

**Important Note:** Processing may take up to 2min30s or fail altogether on long, low-quality or complex audio.

### Request

#### Headers

| Header           | Type   | Required | Description                          |
| ---------------- | ------ | -------- | ------------------------------------ |
| `X-CLIENT-TOKEN` | string | Yes      | API token generated for the project  |
| `Content-Type`   | string | Yes      | Must be set to `multipart/form-data` |

#### Form Data

| Parameter | Type | Required | Description                 |
| --------- | ---- | -------- | --------------------------- |
| `file`    | file | Yes      | Audio file content in bytes |

#### Query Parameters

| Parameter      | Type    | Required | Description                                                                        |
| -------------- | ------- | -------- | ---------------------------------------------------------------------------------- |
| `lang_code`    | string  | No       | Language code for transcription. If not specified, language will be auto-detected. |
| `diarise`      | boolean | No       | Enable diarisation (Default: false)                                                |
| `detect_music` | boolean | No       | Enable music on hold detection (Default: false)                                    |

#### Supported Language Codes

- `afr` - Afrikaans
- `zul` - isiZulu
- `sot` - Sesotho
- `eng` - South African English
- `fra` - African French
- `cs-zul` - Code-switched isiZulu (alpha)

### Response

<details>
  <summary>🟢 `200 OK`</summary>
  <div>
    <div>The request was successful.</div> <br/>
```json
{
  "id": "5f15e81b-53c2-4c5c-a779-1f6776100543",
  "upload_file_size": null,
  "audio_length_seconds": 20.0,
  "sample_rate": null,
  "channels": null,
  "frame_rate": null,
  "mime_type": null,
  "language_code": "eng",
  "warnings": null,
  "diarisation_result": {
    "timeline": [
      {
        "start_time": 0.0,
        "end_time": 2.14,
        "type": "silence"
      },
      {
        "start_time": 2.14,
        "end_time": 10.54,
        "type": "speech",
        "speaker_id": "speaker0",
        "text": "Thank you so much for calling. You're through to Thandi, how can help you?"
      },
      {
        "start_time": 10.54,
        "end_time": 15.98,
        "type": "speech",
        "speaker_id": "speaker1",
        "text": "Hi, Thandi, I would like to settle my bill for yesterday."
      },
      {
        "start_time": 15.98,
        "end_time": 20.0,
        "type": "music"
      }
    ],
    "words": [
      {
        "word": "Thank",
        "start_time": 2.14,
        "end_time": 2.45,
        "confidence": 0.94,
        "weight": null,
        "word_intensity": null,
        "best_path": true,
        "speaker_id": "speaker0"
      },
      {
        "word": "you",
        "start_time": 2.45,
        "end_time": 2.60,
        "confidence": 0.91,
        "weight": null,
        "word_intensity": null,
        "best_path": true,
        "speaker_id": "speaker0"
      }
      // More words would follow here...
    ]
  },
  "transcription_text": "Thank you so much for calling. You're through to Thandi, how can help you? Hi, Thandi, I would like to settle my bill for yesterday.",
  "transcription_status": "COMPLETED",
  "error_message": null,
  "status_datetime": "2025-04-16T10:45:00Z",
  "upload_datetime": "2025-04-16T10:43:12Z"
}
````
    </div>
</details>

### Error Responses

<details>
  <summary>🔴 `400 Bad Request`</summary>
  <div>
    <div>The request was malformed or contained invalid data</div>
  </div>
</details>

<details>
  <summary>🔴 `413 Payload Too Large`</summary>
  <div>
    <div>File size exceeds limit</div>
  </div>
</details>

<details>
  <summary>🔴 `415 Unsupported Media Type`</summary>
  <div>
    <div>Invalid audio file format</div>
  </div>
</details>

<details>
  <summary>🟠 `401 Unauthorized`</summary>
  <div>
    <div>The client token is missing or invalid.</div>
  </div>
</details>

<details>
  <summary>🔴 `500 Internal Server Error`</summary>
  <div>
    <div>An unexpected error occurred on the server.</div>
  </div>
</details>

<details>
  <summary>🔴 `503 Service Unavailable`</summary>
  <div>
    <div>We are currently unable to handle the request due to a temporary overload. Retry later.</div>
  </div>
</details>


<details>
  <summary>🔴 `504 Gateway Timeout Error`</summary>
  <div>
    <div>We are currently experiencing service downtime. Retry later.</div>
  </div>
</details>

### Code Examples

<Tabs defaultValue="py">
      <TabsList>
              <TabsTrigger value="py">Python HTTP</TabsTrigger>
              <TabsTrigger value="curl">cURL</TabsTrigger>
            </TabsList>
  <TabsContent value="py">
```python showLineNumbers
import requests
from pprint import pprint

# Configuration
API_KEY = "<INSERT-TOKEN>"
WAV_FILE = "<INSERT-PATH-TO-AUDIO>"

def file_data(path: str):
    with open(path, "rb") as f:
        return f.read()

url = "https://api.lelapa.ai/v1/transcribe/sync"

headers = {
    "X-CLIENT-TOKEN": API_KEY,
}

files = {
    'file': ('audio.wav', file_data(WAV_FILE), 'audio/wav')
}

# Optional parameters
params = {
    "lang_code": "<INSERT-LANGUAGE-CODE>",
    "diarise": 1,
}

resp = requests.post(url, headers=headers, files=files, params=params)
pprint(resp.json())
````

</TabsContent>

<TabsContent value="curl">

```bash
curl -X 'POST' \
  'https://api.lelapa.ai/v1/transcribe/sync/file?lang_code=<INSERT-LANGUAGE-CODE>&diarise=1' \
  -H 'content-type: multipart/form-data' \
  -H 'X-CLIENT-TOKEN: <INSERT_TOKEN>' \
  -F file=@recording.wav
```

</TabsContent>

</Tabs>