# Initiate a Transcription

In order to initiate a transcription for an existing recording, you must do a POST request to the following endpoint.

## Transcribe recording

> Create transcription for a recording

```json
{"openapi":"3.0.3","info":{"title":"Voice","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateTranscription":{"type":"object","title":"CreateTranscription","additionalProperties":false,"properties":{"locale":{"$ref":"#/components/schemas/SupportedLocales"},"messageId":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"recordingId":{"type":"string","format":"uuid"}},"required":["locale"]},"SupportedLocales":{"type":"string","format":"locale-bcp47","default":"en-US","enum":["ar-AE","ar-SA","cmn-CN","cy-GB","da-DK","de-CH","de-DE","el-GR","en-AU","en-GB","en-GB-WLS","en-IE","en-IN","en-NZ","en-US","en-ZA","es-ES","es-MX","es-US","fr-CA","fr-FR","he-IL","hi-IN","id-ID","is-IS","it-IT","ja-JP","ko-KR","ms-MY","nb-NO","nl-NL","pl-PL","pt-BR","pt-PT","ro-RO","ru-RU","sv-SE","ta-IN","te-IN","th-TH","tr-TR","vi-VN","zh-CN","zh-HK","zh-TW","arb","af-ZA","bn-IN","ca-ES","cmn-TW","cs-CZ","fi-FI","fil-PH","gu-IN","hu-HU","kn-IN","lt-LT","lv-LV","ml-IN","mr-IN","pa-IN","sk-SK","sr-RS","uk-UA","yue-HK","no-NO"]},"Transcription":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/transcriptionId"},"recordingId":{"$ref":"#/components/schemas/recordingId"},"status":{"$ref":"#/components/schemas/TranscriptionStatus"},"stereo":{"type":"boolean"},"locale":{"$ref":"#/components/schemas/SupportedLocales"},"url":{"type":"string"},"summary":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","recordingId","status","stereo","locale","createdAt","updatedAt"]},"transcriptionId":{"title":"Transcription ID","description":"The ID for the transcription.","type":"string","format":"uuid"},"recordingId":{"title":"Recording ID","description":"The ID for the recording.","type":"string","format":"uuid"},"TranscriptionStatus":{"type":"string","enum":["accepted","ongoing","available","absent","failed"]},"RequestError":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"ValidationError":{"title":"A validation error description","additionalProperties":false,"properties":{"code":{"type":"string","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["code","message"]}},"responses":{"requestError":{"description":"The request did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestError"}}}},"validationError":{"description":"The request did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/workspaces/{workspaceId}/recordings/{recordingId}/transcriptions":{"post":{"summary":"Transcribe recording","description":"Create transcription for a recording","operationId":"createRecordingTranscription","tags":["voice-recordings"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTranscription"}}}},"responses":{"202":{"description":"Transcription was accepted for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcription"}}}},"400":{"$ref":"#/components/responses/requestError"},"404":{"$ref":"#/components/responses/requestError"},"422":{"$ref":"#/components/responses/validationError"}}}}}}
```

A transcription request is asynchronous. That means it will take some time before the result has been generated. This depends on the total duration of the recording.

{% tabs %}
{% tab title="Request" %}

```
curl "/workspaces/{workspaceId}/recordings/{recordId}/transcriptions" \
     -H 'Authorization: AccessKey YOUR_SECRET_TOKEN'
```

{% endtab %}

{% tab title="Response" %}

```
{
  "id": "85530fbe-6dc1-4884-a9e6-e62b0f4c6df1",
  "recordingId": "5b74ee9e-9d45-473a-82cd-f1f7feea6bbd",
  "status": "accepted",
  "stereo": false,
  "locale": "en-US",
  "createdAt": "2023-10-24T12:52:27.483Z",
  "updatedAt": "2023-10-24T12:52:27.483Z"
}
```

{% endtab %}
{% endtabs %}