Transcription API

Transcription API Description

Attention! Our queue transcription API method has reached its End of Life (EOL). Please use our AI powered transcription method instead.

Plum offers two services for its Transcription REST API:

Method

Service

Description

GET

transcription/status

Returns a single transcription resource.

POST

transcription/transcribe

Performs a real-time machine based transcription and immediately returns the result.

Please note that each of the Transcription REST APIs use HTTP AUTH for authentication. Please contact your account manager to get access credentials.

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

XML (success)
XML (failure)
JSON (success)
JSON (failure)
XML (success)
<sample>
<status>success</status>
<error/>
<result>
<!-- SAMPLE RESULT DATA -->
</result>
</sample>
XML (failure)
<sample>
<status>failure</status>
<error>Unauthorized access to sample service</error>
</sample>
JSON (success)
{
"status":"success",
"error":"",
"result": {
// SAMPLE RESULT DATA
}
}
JSON (failure)
{
"status":"failure",
"error":"Unauthorized access to sample service",
}

get
Transcription Status

https://hosting.plumvoice.com/ws/transcription/{resource_type}/{transcription_id}
Returns the status of a transcription request.
Request
Response
Request
Path Parameters
resource_type
required
string
status.json or status.xml
transcription_id
required
string
Unique 128-bit hexidecimal identifier for this transcription request. Note: This value is provided in the result of a queued transcription request.
Headers
accept
optional
string
application/json, application/xml
Response
200: OK
JSON
XML
JSON
{
"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"
}
}
XML
<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>

Sample Code

checkstatus.php
CURL (command line)
checkstatus.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.plumvoice.com/ws/transcription/status.xml/".$transcription_message_id);
echo(curl_exec($ch));
curl_close($ch);
?>
CURL (command line)
curl -u username:password https://hosting.plumvoice.com/ws/transcription/status.json/f85bd7682c9f71b60e216f2f6d39e95d

post
Real-Time Transcription

https://hosting.plumvoice.com/ws/transcription/{resource_type}
Performs real-time transcription of an audio file.
Request
Response
Request
Path Parameters
resource_type
required
string
transcribe.json or transcribe.xml
Headers
accept
optional
string
application/json, application/xml
Form Data Parameters
language
required
string
The language code the AI-engine should use. Note: Please see table below for all supported languages.
audio
required
object
The audio file that will be transcribed. Note: Currently only headerless u-law audio is supported.
Response
200: OK
JSON
XML
JSON
{
"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"
}
}
XML
<?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>

Sample Code

transcribe.xml
CURL (command line)
transcribe.xml
<?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.plumvoice.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>
CURL (command line)
curl -u username:password -F language=en-US -F audio=@/path/to/audio https://hosting.plumvoice.com/ws/transcription/transcribe.json

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

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.