# Transcription API

{% hint style="success" %}
**- NEW! - Interactive API docs, now live!**

Visit [api-docs.plumvoice.com](https://api-docs.plumvoice.com/) to **read** Plum API documentation, **build and test requests** in our interactive API sandbox, **review** the responses, and **share** it all with your team.
{% endhint %}

## Overview

{% hint style="danger" %}
**Attention!** Our queue transcription API method has reached its End of Life (EOL). Please use our [AI-powered transcription method](#real-time-transcription) instead.
{% endhint %}

{% hint style="info" %}
Review the following links for [sample use cases](https://docs.plumvoice.com/documentation/using-the-plum-voice-suite/use-cases/adding-transcription-to-the-voice-channel) of when a company might benefit from the Transcription API or detailed examples that explain [how to call the Transcription API](https://docs.plumvoice.com/documentation/using-the-plum-voice-suite/how-to-guides/using-plums-transcription-api) across Plum's product suite.
{% endhint %}

Plum offers two services for its Transcription REST API:

| Method                           | Service                                              | Description                                                                                                      |
| -------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [GET](#transcription-status)     | [transcription/status](#transcription-status)        | [Returns a single transcription resource.](#transcription-status)                                                |
| [POST](#real-time-transcription) | [transcription/transcribe](#real-time-transcription) | [Performs a real-time machine based transcription and immediately returns the result.](#real-time-transcription) |

{% hint style="warning" %}
Please note that each of the Transcription REST APIs use HTTP AUTH for authentication. Please contact your account manager to get access credentials.
{% endhint %}

All of the Transcription REST APIs have the same return format that includes a status (success or failure), error message, and the result data.

### **Sample Responses**

{% tabs %}
{% tab title="XML (success)" %}

```markup
<sample>
  <status>success</status>
  <error/>
  <result>
    <!-- SAMPLE RESULT DATA -->
  </result>
</sample>
```

{% endtab %}

{% tab title="XML (failure)" %}

```markup
<sample>
  <status>failure</status>
  <error>Unauthorized access to sample service</error>
</sample>
```

{% endtab %}

{% tab title="JSON (success)" %}

```javascript
{
  "status":"success",
  "error":"",
  "result": {
    // SAMPLE RESULT DATA
  }
}
```

{% endtab %}

{% tab title="JSON (failure)" %}

```javascript
{
  "status":"failure",
  "error":"Unauthorized access to sample service",
}
```

{% endtab %}
{% endtabs %}

## Transcription Status

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/transcription/{resource_type}/{transcription_id}`

Returns the status of a transcription request.

#### Path Parameters

| Name              | Type   | Description                                                                                                                                                            |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| resource\_type    | string | `status.json` or `status.xml`                                                                                                                                          |
| transcription\_id | string | <p>Unique 128-bit hexidecimal identifier for this transcription request.<br><em>Note: This value is provided in the result of a queued transcription request.</em></p> |

#### Headers

| Name   | Type   | Description                       |
| ------ | ------ | --------------------------------- |
| accept | string | application/json, application/xml |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="JSON" %}

```javascript
{
  "status":"success",
  "error":"",
  "result": {
    "transcription_id":"f85bd7682c9f71b60e216f2f6d39e95d",
    "message":"This is the transcribed text.",
    "duration":4,
    "language":"en-US",
    "workflow":"hybrid",
    "request_timestamp":1394776766,
    "response_timestamp":1394776767,
    "result_url":"http://myserver.com/transcription_result.php",
    "status":"complete"
  }
}
```

{% endtab %}

{% tab title="XML" %}

```markup
<status>
  <status>success</status>
  <error/>
  <result>
    <transcription_id>f85bd7682c9f71b60e216f2f6d39e95d</transcription_id>
    <message>This is the transcribed text.</message>
    <duration>4</duration>
    <language>en-US</language>
    <workflow>hybrid</workflow>
    <request_timestamp>1394776766</request_timestamp>
    <response_timestamp>1394776767</response_timestamp>
    <result_url>http://myserver.com/transcription_result.php</result_url>
    <status>complete</status>
  </result>
</status>
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

**Sample Code**&#x20;

{% tabs %}
{% tab title="checkstatus.php" %}

```php
<?php
header("Content-type: text/xml");

// for this example, our transcription_id is f85bd7682c9f71b60e216f2f6d39e95d
$transcription_id = 'f85bd7682c9f71b60e216f2f6d39e95d';

// initialize curl
$ch = curl_init();

// set necessary curl options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
curl_setopt($ch, CURLOPT_URL, "https://hosting.vxml.sharpencx.com/ws/transcription/status.xml/".$transcription_message_id);

echo(curl_exec($ch));

curl_close($ch);
?>
```

{% endtab %}

{% tab title="CURL (command line)" %}

```
curl -u username:password https://hosting.plumvoice.com/ws/transcription/status.json/f85bd7682c9f71b60e216f2f6d39e95d
```

{% endtab %}
{% endtabs %}

## Real-Time Transcription

<mark style="color:green;">`POST`</mark> `https://hosting.vxml.sharpencx.com/ws/transcription/{resource_type}`

Performs real-time transcription of an audio file.

#### Path Parameters

| Name           | Type   | Description                           |
| -------------- | ------ | ------------------------------------- |
| resource\_type | string | `transcribe.json` or `transcribe.xml` |

#### Headers

| Name   | Type   | Description                       |
| ------ | ------ | --------------------------------- |
| accept | string | application/json, application/xml |

#### Request Body

| Name     | Type   | Description                                                                                                                    |
| -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| language | string | The language code the AI-engine should use. **Note: Please see table below for all supported languages.**                      |
| audio    | object | <p>The audio file that will be transcribed.<br><strong>Note: Currently only headerless u-law audio is supported.</strong> </p> |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="JSON" %}

```javascript
{
  "status":"success",
  "error":"",
  "result": {
    "transcription_id":"0ddc6c6f313b45b6a8b28640b679e602",
    "message":"This is the transcribed text.",
    "duration":4,
    "language":"en-US",
    "workflow":"auto",
    "request_timestamp":1531227497,
    "response_timestamp":1531227498,
    "status":"complete"
  }
}
```

{% endtab %}

{% tab title="XML" %}

```markup
<?xml version="1.0"?>
<transcribe>
  <status>success</status>
  <error></error>
  <result>
    <transcription_id>0ddc6c6f313b45b6a8b28640b679e602</transcription_id>
    <message>This is the transcribed text.</message>
    <duration>4</duration>
    <language>en-US</language>
    <workflow>auto</workflow>
    <request_timestamp>1531227497</request_timestamp>
    <response_timestamp>1531227498</response_timestamp>
    <status>complete</status>
  </result>
</transcribe>
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

**Sample Code**

{% tabs %}
{% tab title="transcribe.xml" %}

```markup
<?xml version="1.0"?>
<vxml version="2.0">
  <form>
    <record name="recording1" beep="true">
      <prompt bargein="false">Record your message after the beep.</prompt>
    </record>
    <block>
      <var name="language" expr="'en-US'"/>
      <var name="audio" expr="recording1"/>
      <data name="transcribe" src="https://username:password@hosting.vxml.sharpencx.com/ws/transcription/transcribe.json" namelist="language audio" method="post" enctype="multipart/form-data" accept="application/json"/>
      <if cond="transcribe.status == 'success'">
        <log expr="'transcription_id: '+transcribe.result.transcription_id"/>
        <prompt>You said: <value expr="transcribe.result.message"/></prompt>
      <else/>
        <log expr="'error: '+transcribe.error"/>
      </if>
    </block>
  </form>
</vxml>
```

{% endtab %}

{% tab title="CURL (command line)" %}

```
curl -u username:password -F language=en-US -F audio=@/path/to/audio https://hosting.plumvoice.com/ws/transcription/transcribe.json
```

{% endtab %}
{% endtabs %}

### Supported Language Codes

|    | Language Code | Language   | Country        |
| -: | ------------- | ---------- | -------------- |
|    | de-DE         | German     | Germany        |
| \* | en-AU         | English    | Australia      |
|    | en-GB         | English    | United Kingdom |
|    | en-US         | English    | United States  |
|    | es-ES         | Spanish    | Spain          |
| \* | es-MX         | Spanish    | Mexico         |
| \* | es-US         | Spanish    | United States  |
| \* | fr-CA         | French     | Canada         |
|    | fr-FR         | French     | France         |
|    | ja-JP         | Japanese   | Japan          |
|    | pt-BR         | Portuguese | Brazil         |
|    | zh-CN         | Mandarin   | China          |

{% hint style="info" %}
**Note:** Languages marked with an asterisk (\*) are currently in Beta release and may not be ready for production use and are subject to change. They are initial offerings that are expected to improve in quality with time and usage.
{% endhint %}