# Create transcription

> Transcribes one audio file, in the format of OpenAI's speech-to-text API (`client.audio.transcriptions.create` in the OpenAI SDKs), with `vibevoice-asr` (alias `microsoft/vibevoice-asr`). The request is a `multipart/form-data` form with the file and the model. With `verbose_json`, the answer adds the duration and the segments, each with its start, end and speaker. More than 50 languages are detected automatically. At most 5 minutes of audio and a body of 16 MiB per request. Audio, transcripts and prompts are processed in memory only: they are never written to disk or logs and never used for training.

Source: https://docs.serenityedge.ai/docs/api/edge/create-transcription/

`POST https://api.serenityedge.ai/v1/audio/transcriptions`

Transcribes one audio file, in the format of OpenAI's speech-to-text API (`client.audio.transcriptions.create` in the OpenAI SDKs), with `vibevoice-asr` (alias `microsoft/vibevoice-asr`). The request is a `multipart/form-data` form with the file and the model. With `verbose_json`, the answer adds the duration and the segments, each with its start, end and speaker. More than 50 languages are detected automatically. At most 5 minutes of audio and a body of 16 MiB per request. Audio, transcripts and prompts are processed in memory only: they are never written to disk or logs and never used for training.

Billed per second of audio, rounded up, at least one second, at the price in `audio_pricing.per_second` of `GET /v1/models?format=openai`; `usage.seconds` of the answer is what was billed. A request that ends in an error is not billed. The model marks audio without speech with tags such as `[Silence]`; send `remove_nonspeech_tags=true` to remove them. A transcription that takes more than about 20 seconds is answered `200` at once with blank lines until the transcript follows; JSON parsers skip them. Only Serenity Edge API keys can use this route. See the [Speech to text guide](https://docs.serenityedge.ai/docs/audio-transcriptions).

## Request body (`multipart/form-data`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | string | yes | The audio file, once per request: FLAC, M4A or MP4, MP3, Ogg (Vorbis or Opus), WAV or WebM. The format is read from the file itself, not from its name. At most 5 minutes of audio, when the file states its duration, and 16 MiB. |
| `model` | string | yes | `vibevoice-asr`, or its alias `microsoft/vibevoice-asr`. `GET /v1/models?format=openai` lists it with `endpoints: ["/v1/audio/transcriptions"]`. |
| `response_format` | string | no | `json` (the transcript and `usage`), `text` (the transcript as `text/plain`) or `verbose_json` (also the duration and the segments with speakers). `srt` and `vtt` are refused with HTTP 400. One of `json`, `text`, `verbose_json`. Default `json`. |
| `prompt` | string | no | Up to 2000 characters of context: names, technical terms or the topic. The model uses them to spell what it hears. At most 2000 characters. |
| `language` | string | no | An ISO 639-1 code such as `es` or `en`. The model detects the language itself; the code is returned in `verbose_json`. |
| `temperature` | number | no | Accepted for compatibility and not used. At least 0. At most 1. |
| `timestamp_granularities[]` | array of string | no | `segment` only. Word timestamps are not available. |
| `stream` | boolean | no | Accepted and ignored: the answer comes in one piece. |
| `remove_nonspeech_tags` | boolean | no | `true` removes the tags the model writes for audio without speech (`[Silence]`, `[Noise]`, `[Music]`, `[Human Sounds]`, `[Environmental Sounds]` and `[Unintelligible Speech]`, in any letter case) from the text of every format; in `verbose_json`, a segment of tags only is left out and the segments are numbered again from 0. Other text in square brackets is kept. Billing does not change. Sent as `true` or `false` (with the OpenAI SDKs, in `extra_body`); any other value is refused with HTTP 400. Default `false`. |

## Responses

### 200: The transcript. `json`, the default, gives `text` and `usage`; `verbose_json` adds the language sent, the duration and the segments; `text` gives the transcript alone as `text/plain`.

Body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | yes | The transcript. |
| `usage` | TranscriptionUsage (object) | yes | What the request was billed: the duration of its audio in whole seconds, rounded up, at least one. |
| `usage.type` | string | yes | Always `duration`. |
| `usage.seconds` | integer | yes | At least 1. |
| `task` | string | yes | Always `transcribe`. |
| `language` | string | no | The `language` of the request, when it was sent. |
| `duration` | number | yes | Duration of the audio in seconds. |
| `text` | string | yes | The transcript. |
| `segments` | array of TranscriptionSegment (object) | yes |  |
| `segments[].id` | integer | yes |  |
| `segments[].start` | number | yes | Start, in seconds from the beginning of the audio. |
| `segments[].end` | number | yes | End, in seconds from the beginning of the audio. |
| `segments[].text` | string | yes |  |
| `segments[].speaker` | integer | no | The speaker, as labelled by the model within this file only. Absent on a segment without speech, such as `[Silence]`. |
| `usage` | TranscriptionUsage (object) | yes | What the request was billed: the duration of its audio in whole seconds, rounded up, at least one. |
| `usage.type` | string | yes | Always `duration`. |
| `usage.seconds` | integer | yes | At least 1. |

Body (`text/plain`)

Schema: string.

### 400: The request was refused: a body that is not a `multipart/form-data` form, no `file` or `model`, a second file, an audio format that is not supported, audio longer than 5 minutes (when the file states its duration), `srt` or `vtt`, word timestamps, a `remove_nonspeech_tags` other than `true` or `false`, a field out of range, or a model served on another route. `param` names the field at fault when there is one.

Body (`application/json`): `ErrorResponse`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | Error (object) | yes | OpenAI-style error object. |
| `error.message` | string | yes | Human-readable description of the problem. |
| `error.type` | string | yes | Error category. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`. |
| `error.code` | string or null | no | Machine-readable error code, when available. |
| `error.param` | string or null | no | The request parameter the error refers to, when applicable. |

### 401: Missing or invalid API key.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 403: The key is valid but cannot use this route: only Serenity Edge API keys can. Any other key, such as a key from a Serenity Star account, gets `permission_denied`.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 404: The model id is unknown, or it is a model of another route (`model_not_found`).

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 413: The request body, or the audio file in it, is larger than this route accepts (16 MiB, `request_too_large`).

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 429: Rate limit exceeded, or the service is temporarily at capacity for this model. Wait for the number of seconds in the `Retry-After` header before retrying.

Header `Retry-After`: Seconds to wait before retrying.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 500: The file took too long to transcribe (`timeout`): split it into shorter requests. Or an unexpected server error: the model service returned an unexpected response (`upstream_error`), or an error in the gateway. A transcription that fails after the `200` has started comes as this error object in the body instead; with `text`, the connection is closed before the end.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 503: The model service is temporarily unavailable (`upstream_unavailable`). Retry later and check the status page at https://status.serenityedge.ai.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.
