Transcription API

- NEW! - Interactive API docs, now live!

Visit 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.

Overview

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

Review the following links for sample use cases of when a company might benefit from the Transcription API or detailed examples that explain how to call the Transcription API across Plum's product suite.

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)

<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",
}

Transcription Status

GET https://hosting.plumvoice.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	Unique 128-bit hexidecimal identifier for this transcription request. Note: This value is provided in the result of a queued transcription request.

Headers

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

200

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

<?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

Real-Time Transcription

POST https://hosting.plumvoice.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	The audio file that will be transcribed. Note: Currently only headerless u-law audio is supported.

200

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

<?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:[e-mail]/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.