How can I use callbacks with this API?

How can I use callbacks ?

The callback feature allows you to receive transcription results automatically once processing is complete.

Instead of continuously polling the API, you can provide a callback URL where results will be sent when ready.

How It Works

When you submit an audio file for transcription, you can enable the callback option.

If enabled, once the transcription is finished (successfully or with an error), the API will make an HTTP request to your endpoint with the transcription status.

This removes the need for polling, reduces server load, and ensures faster handling of results.

Request Example (with callback enabled)


{
  "audio_url": "YOUR_AUDIO_URL",
  "callback": true,
  "callback_config": {
    "url": "<https://yourserverurl.com/your/callback/endpoint/>",
    "method": "POST"
  }
}

Request Example (without callback)


{
  "audio_url": "YOUR_AUDIO_URL",
  "callback": false
}

Parameters

Base Parameters

Field	Type	Required	Description
`audio_url`	`string`	✅	URL of the audio file to transcribe.
`callback`	`boolean`	✅	Whether to use a callback (`true`) or not (`false`).

Callback Parameters (only required if `callback: true`)

Field	Type	Required	Description
`callback_config.url`	`string`	✅	The endpoint on your server that will receive the callback.
`callback_config.method`	`string`	❌	HTTP method used for the callback request. <br>Allowed values: `POST`(default), `PUT`.

Callback Request Format

When the transcription is ready, the system will send an HTTP request to your specified endpoint. The request body is a JSON object containing the transcription id and an event property that tells you if it’s a success or an error.

Example Request Body (success)


{
  "id": "transcription_12345",
  "event": "success",
  "payload": {
    ...
  }
}

Example Request Body (error)


{
  "id": "transcription_12345",
  "event": "error",
  "error": {
    "code": "...",
    "message": "..."
  }
}

Handling Large Payloads

In some cases, callback payloads may be large, depending on the transcription data returned.

To avoid 413 Payload Too Large errors, make sure your server and reverse proxy (e.g., NGINX, Apache, or Express.js) are configured to allow larger request bodies.

For NGINX, you may need to update:
```
client_max_body_size 20M;
```
For Express.js (Node.js), ensure you set the body parser limit:


app.use(express.json({ limit: '20mb' }));

How can I use callbacks with this API?