The CastingWords Simple Transcription API v4 is a simplified API to create orders and obtain the resulting transcripts.
There are pre-written API clients in Python and PHP on github to ease integration.
The API is RESTish. The goal is not to follow REST's practices closely, but rather to make an easy API to get up to speed with using a dynamic language or curl. It accepts data as URL encoded key value pairs. An HTTP body of type JSON in a POST request and with content type application/json is also accepted.
Authentication is via a secret key posted in the HTTPS URL or as JSON in the POST Body (preferred). You may retrieve your secret key from you account at https://castingwords.com/customer/info
All URLS are in the format of
https://castingwords.com/store/API4/
Currently supported: application/json
Although all calls return a success message in the data, failures are always indicated via an HTTP code, 401 not authorized for instance. A message will accompany the error. An overview of HTTP status codes is available at http://en.wikipedia.org/wiki/HTTP_status
#ID indicates a CastingWords id. The '#' is not literal. All calls require an API Key parameter, which has been omitted for clarity (eg: &api_key=#APIKEY)
Returns the order and audiofile ids
POST
https://castingwords.com/store/API4/order_url
?api_key=#APIKEY&url=http://myaudio.com/audio.mp3
&sku=TRANS14&SKU=TSTMP1
See your prepay balance.
GET https://castingwords.com/store/API4/prepay_balance
See details on an audiofile, including it's current state
GET https://castingwords.com/store/API4/audiofile/#AUDIOFILEID
Returns the data of the transcript in the doc type requested by the extention.
GET
https://castingwords.com/store/API4/audiofile/#AUDIOFILEID/transcript.#ext
DEPRECATED:
GET or POST
https://castingwords.com/store/API4/transcript/#AUDIOFILEID.#ext
POST https://castingwords.com/store/API4/audiofile/#AUDIOFILEID/upgrade?sku=#SKU
POST https://castingwords.com/store/API4/audiofile/#AUDIOFILEID/refund
POST https://castingwords.com/store/API4/invoice/#INVOICEID
Set a URL for us to ping on transcript complete
GET or POST https://castingwords.com/store/API4/webhook?webhook=#URL_ENCODED_HTTP(S)_ENDPOINT
Description:
Creates a new order for a audio located at a URL.
Accepts many URLs and many SKUs, with all SKUs being applied to every URL.
Fetches data on all URLs, response time varies with the number of URLs and the speed of the host;
Parameters:
api_key - Required for authentication
url - Url(s) of audio/video to transcribe. Preferably points to an mp3. ;
sku - one or more skus to order.
TRANS14 = Budget Transcription
TRANS2 = 1 Day Transcription
TRANS6 or TRANS7 = 7 Day Transcription (same product)
These addon skus can be added to the transcription skus above (just add another sku=CAPTION1)
DIFFQ2 = Difficult Audio
TSTMP1 = Timestamps
CAPTION1 = Captions
VERBATIM1 = Verbatim
test - Creates a test only order that will not be transcribed.
notes - text feild with comments for the transcribers about this audio
name - Repeatable parameter with names of the speakers in the audio.
names - a synonym for name
Returns:
audiofiles - an array of ids id for the file order - an id for the order message - success/failure human readable
cURL Example
curl --data \
'{"api_key":"MYAPIKEY",
"url":"http://mydomain.com/media/test.mp3",
"test": "1",
"names": ["Jane Doe"]
}' \
https://castingwords.com/store/API4/order_url \
-H "Content-Type: application/json"
Description:
Returns the current prepay_balance in USD for this account as a json structure.
Parameters:
api_key - Required for authentication.
Returns:
balance - The current prepay balance
cURL Example
curl https://castingwords.com/store/API4/prepay_balance?api_key=MYAPIKEY \ -H "Content-Type: application/json"
audiofile_id
Parameters: api_key - Required for authentication.
Returns: audiofile - a hash of properties statename - A string describing the current state of a file names - A pipe delimited list of speaker names notes - Notes to the transcriber about this file. originallink - The link submitted for transcription title - Title of the transcript duration - Length in minute of the audio id - Audiofile ID description - A description of the audio quality_stars - Quality ranked on a 5 star system orders - a potentially nonexistent array of active order ids invoices - a potentially nonexistent array of active invoice ids total - the cost in dollars of this audiofile once finalized
States Audio Processing Awaiting Edit Awaiting Final Approval Billing Processing Checking Audio Quality Delivered Editing to Word Count Error On Hold Order Cancelled Order Chargeable Order Processing Out for edit Pre-Processing Processing Refunded Technical Difficulty Temporary Error Transcribing
cURL Example
curl https://castingwords.com/store/API4/audiofile/101?api_key=MYAPIKEY \ -H "Content-Type: application/json"
audiofile_id -
extension - (optional) defaults to .txt
.txt
.doc
.rtf
.html
Parameters:
api_key - Required for authentication. test - Returns a fake transcription for testing purposes.
Returns:
The text of the transcript in the requested mime types
cURL Example
curl --data '{"api_key":"MYAPIKEY", "test": "1"}'\
https://castingwords.com/store/API4/audiofile/101/transcript.txt \
-H "Content-Type: application/json"
<Deprecated Versions>
Also available from /transcript/#audiofileid.#ext, and via POST
audiofile_id -
Parameters:
sku - Repeatable. Valid values:
DIFFQ2 - Difficult Audio Upgrade. Difficult audio SKU on invoice may be different.
TSTMP1 - Timestamps.
EDIT01 - Extra Editing.
UPGRD1 - Upgrade TRANS14 to TRANS6
UPGRD2 - Upgrade TRANS14 to TRANS2
UPGRD3 - Upgrade TRANS6 to TRANS2
api_key - Required for authentication.
test - Returns a fake success for testing purposes. Only for use with audiofile 100 and 101.
Returns:
Success message.
cURL Example
curl --data '{"api_key":"MYAPIKEY", "test": "1", "sku": "TSTMP1"}'\
https://castingwords.com/store/API4/101/upgrade \
-H "Content-Type: application/json"
Description:
Refunds an audiofile, ordered with PREPAY or on an INVOICE. This only works when no transcription work has been done on a file. Potentially valid states are 'Pre-Processing', 'Audio Processing', and 'Error' .
URL Parameters:
audiofile_id -
Parameters:
api_key - Required for authentication. test - Returns a fake approval for testing purposes. Only for use with audiofile 100 and 101.
Returns:
Success message.
cURL Example
curl --data '{"api_key":"MYAPIKEY", "test": "1"}'\
https://castingwords.com/store/API4/101/refund \
-H "Content-Type: application/json"
invoice_id - the id of the invoice in question
Parameters:
api_key - Required for authentication.
Returns:
id - The ID
purchase_order - ID of the purchase order if any
createtime - time of creation
paidtime - time that payment was recorded
total - total price of invoiced items
items - A list of items consisting of:
id - Item ID
sku - SKU of the line item
quantity - Number ordered
price - Price per quantity
audiofile - ID of associated audiofile
total - price * quantity
cURL Example
curl https://castingwords.com/store/API4/webhook?api_key=MYAPIKEY \ -H "Content-Type: application/json"
api_key - Required for authentication.
Returns:
The registered webhook url for this account.
cURL Example
curl https://castingwords.com/store/API4/webhook?api_key=MYAPIKEY \ -H "Content-Type: application/json"
Description:
Sets the webhook url for this account
URL Parameters:
webhook - the new url to call on webhook triggers
Parameters:
api_key - Required for authentication.
Returns:
The current webhook url
cURL Example
curl --data '{"api_key":"MYAPIKEY", "webhook":"http://mydomain.com/webhook"}'\
https://castingwords.com/store/API4/webhook \
-H "Content-Type: application/json"
Webhooks are our async notification system. We do a 1 time HTTP POST to a url that you specify when an event occurs. The payload is application/x-www-form-urlencoded. Currently we support these events:
Common Parameters:
webhook_version: Incremented as we add Hooks.
Parameters:
audiofile - Used to retrieve your transcript order - The order this file was part of event - 'TRANSCRIPT_COMPLETE' originallink - A url with original location of audio. May not resolve.
Parameters:
audiofile - ID of the file in question order - The order this file was in. event - 'DUPLICATE_FILE' original_audiofile - The ID of previously transcribed file this file is a duplicate of.
Parameters:
amount - amount of refund audiofile - ID. Present on some refunds - most refunds are against entire orders. order - The order this transaction was against. event - 'REFUND_ISSUED' original_transaction - Old Transaction ID transaction - This Transaction ID
Parameters:
audiofile - ID. The file with the difficult audio. order - The order for this file. event - 'DIFFICULT_AUDIO'
Example
http://example.com/ ?audiofile=101 &order=TeSt &event=TRANSCRIPT_COMPLETE &originallink=https://castingwords.com/uploads/1294130176_hand_uploaded_file.mp3
Description:
Requests a test webhook call of a particular type.
URL Parameters:
type - One of the types of webhooks: TRANSCRIPT_COMPLETE DIFFICULT_AUDIO or REFUND_ISSUED
Parameters:
api_key - Required for authentication.
Returns:
The current webhook url
cURL Example
curl --data '{"api_key":"MYAPIKEY"}'\
https://castingwords.com/store/API4/webhook/test/TRANSCRIPT_COMPLETE \
-H "Content-Type: application/json"