Movatterモバイル変換

The Scribie.com REST API provides a programmable interface to our transcription service. The core functionality provided by our web interface is made available through this API. An application can upload files to our servers, pay for transcription, check the transcript progress, fetch the transcripts and delete the files.

This document describes the resources and methods which are exposed by the API. The target audience for this document are server side application developers. Thecurl examples are used throughout this document to illustrate the usage of the API.

This API exposes two resources:files andfile. Thefile resource refers to an individual file whereas thefiles resource is a collection offile's. TheGET requests can be used to retrieve the resource and any meta data associated with it. ThePOST request modifies the state of the resource.

The endpoint URL for the API ishttps://api.scribie.com/v1/. Only HTTPS is supported. HTTP requests will be redirected to HTTPS. The API is currently in version 1. The encoding used isapplication/json; charset=utf-8, except for thefilesPOST request which ismultipart/form-data.

A sandbox environment is available for testing at the endpoint URLhttps://api-sandbox.scribie.com/v1/. The data is retained for 24 hours only.

An account on Scribie.com with a saved payment method is required in order to use this API. Pleasesign-up if you do not have an account yet.

Only email support is available for the API. Please send your questions to support@scribie.com.

This API uses HTTP Basic authentication with the API key as the user. The API key can be generated from the accountsettings page. All requestsmust be authenticated.

Example Request

curl -X GET --user 764118cada1d4d7c899999434c00e761ac24b5c3: https://api.scribie.com/v1/files

The API key should be kept secret in order to prevent misuse of the account.

This API returns errors via HTTP response codes. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, or file type is unsupported, etc.). The 500 error code is returned if an unexpected application error occurs during processing. Additionally a error string is provided as a hint in the response body.

Example Response

{"error":"incorrect api key"}

Error Reference

Methods allowed:GET,POST

This resource represents a collection of thefile resource. TheGET method returns a list of file identifiers. The identifier can be used to send requests to the individualfile resource.

Example Request

curl -X GET --user 764118cada1d4d7c899999434c00e761ac24b5c3: https://api.scribie.com/v1/files

Example Response

[     {        "id":"5a5290c74787b392e31bfc81124ec11c9abf622c"   },   {        "id":"f8c0523d6b799b79ea9e40034df294094a7b00cc"   },   {...},   {...}]

ThisPOST request is used to create a newfile. The following pre-conditions should be met for this request to be processed.

• The requestmust contain afile or link parameter in the body.
• The content typemust bemultipart/form-data.
• If the paramter in the body islinkthen it should be publicly downloadable link.
• The file sizemust be less than 10 GB.
• The file formatmust be one of the following: mp3, wav, wma, wmv, avi, flv, mpg, mpeg, mp4, m4a, m4v, mov, ogg, webm, aif, aiff, amr, 3gp, 3ga, mts, ogv, aac, mkv, mxf, opus, flac. The format is determined from the MIME type of the file.

The response code is201 if thefile creation was successful. The credit card is charged towards the transcription cost on successful creation.

Example Request

curl -X POST --user 764118cada1d4d7c899999434c00e761ac24b5c3: -F file=@test.wav https://api.scribie.com/v1/files

Example Response

{"id":"hmabyoc74787b392e31bfc81124ec11c9abf622c"}

Options

The following options can be specified in the query parameters. The defaulttranscript order options is applied if an option is not found. Please note that spaces in the values have to be escaped.

Example Request

curl -X POST --user 764118cada1d4d7c899999434c00e761ac24b5c3: -F file=@test.wav 'https://api.scribie.com/v1/files?transcript_type=manual&strict_verbatim=off&subtitle_file=off&time_coding=on&speaker_tracking=on&speaker_tracking_format=initials&spelling_style=american&transcript_template=blank%20single%20line%20spaced&speaker_names=John%20Doe,Jane%20Doe

The options are case insensitive. The default options can be overridden from thesettings page. Some of these options are charged. Please check thePricing and theservice details page for more information. For theautomated transcript type, all options are ignored. For using custom formatting, you have to enabled it first and contactsupportto use this option.

Methods allowed:GET,POST,DELETE

This resource represents an individualfile. TheHEAD method returns meta data in theX-Scribie-Metadata header as a JSON string. All dates in the meta data are in the ISO 8601 format. It also contains the options which were applied. The scheduled delivery date is returned in the delivery parameter. Theprogress_percent parameter is a measure of the completeness of the transcript.

Example Request

curl -I -X HEAD --user 764118cada1d4d7c899999434c00e761ac24b5c3: https://api.scribie.com/v1/file/5a5290c74787b392e31bfc81124ec11c9abf622c

Example Response

HTTP/1.1 200 OKServer: nginx/1.6.2Date: Tue, 20 Jan 2015 07:17:19 GMTContent-Type: text/plain; charset=utf-8Content-Length: 183Connection: keep-aliveX-Powered-By: ExpressX-Scribie-Metadata: {"name":"test","created":"2015-01-20T12:47:06Z","seconds":"2","bytes":"13824","cost":"0.03","discount":"0","total":0.03,"transaction_id":"c684ty","refund_amount":"0","currency":"USD","delivery":"2015-01-27T12:47:11Z","delay_reason":null,"duplicates":null,"options":{"transcript_type":"manual","time_coding":"on","strict_verbatim":"off","subtitle_file":"off","speaker_tracking":"on","speaker_tracking_format":"full names","spelling_style":"american","speaker_names":["John Doe","Jane Doe"],"transcript_template":"blank single line spaced"},"progress_percent":0}Content-Disposition: attachment; filename="test.txt"Strict-Transport-Security: max-age=63072000

GET requests to this resource returns the transcript. We provide transcripts in .doc, .pdf, .odt, .txt, .sbv, .srt and .json formats. The extension can be appended to thefile identifier to retrieve the desired format. The default format is .txt. If the progress is less than 100% then the Work-In-Progress transcript is returned in .txt format.

Example Request

curl -X GET --user 764118cada1d4d7c899999434c00e761ac24b5c3: https://api.scribie.com/v1/file/5a5290c74787b392e31bfc81124ec11c9abf622c.txt

Example Response

NOTICEWork-In-Progress TranscriptThis transcript is not yet complete. It may have missing sections, higher number of mistakes, blanks and speaker tracking inconsistencies.----00:01 Austin Tuan: Hello.00:05 Rajiv Poddar: Hello. 00:07 AT: Yes. Rajiv can you hear me. 00:10 RP: Yeah, I can hear you. 00:11 AT: Hi. This is Austin Taun from Taipei, Taiwan. 00:17 RP: Hi Austin. How are you. 00:19 AT: I'm fine. Okay, so today, Rajiv could you first introduce yourself a little bit.

The JSON format is an array of objects. The description of each key in the object is provided below:

The following code snippet illustrates how to get the transcript from JSON file in Python

Example Request

import jsonwords = json.load(open('5a5290c74787b392e31bfc81124ec11c9abf622c.json'))transcript = ''.join([w['word'] if 'turn' in w else w['word'] + " " for w in words])

TheDELETE request removes thefile from our server and all the meta data associated with it. Thefile can be deleted only if the progress is below 60%, or when the transcript is complete, i.e., 100%. In the former case, a refund is also issued. The refund amount proportional to the progress and is issued after 1 business day. The response body is empty if the operation is successful.

Example Request

curl -X DELETE --user 764118cada1d4d7c899999434c00e761ac24b5c3: https://api.scribie.com/v1/file/5a5290c74787b392e31bfc81124ec11c9abf622c

A subsequentGET will return a404 not found error.

A webhook URL can be configured from thesettings page. On any progress update, the file id isPOST'ed to the URL. The request is JSON encoded. A subequentHEAD on the id returns the updated progress value in theX-Scribie-Metadata header.

Sample POST Body

{     "id":"5a5290c74787b392e31bfc81124ec11c9abf622c"}

Assuming that your Scribie.com account is set up (signed up, saved a credit card and generated an API key), the following steps have to be performed in order get the transcript of test.wav file.

Step 1:POST the file to thefiles resource. This returns theid of thefile which should be saved.

curl -X POST --user 764118cada1d4d7c899999434c00e761ac24b5c3: -F file=@test.wav https://api.scribie.com/v1/files

Step 2: Send aGET request to thefile with theid, parse theX-Scribie-Metadata header in the response and check theprogress_percent field. If progress is less than 100 then the Work-In-Progress transcript will be returned, otherwise the final transcript in text format will be returned. If theWebhook is configured, this request should be sent immediately after receiving the Webhook POST.

curl -I -X GET --user 764118cada1d4d7c899999434c00e761ac24b5c3: https://api.scribie.com/v1/file/<id returned in step 1>

Step 3: When theprogress_perecent is 100, you can send aGETrequest for the Word Document as well and save it somewhere.

curl -X GET --user 764118cada1d4d7c899999434c00e761ac24b5c3: https://api.scribie.com/v1/file/<id returned in step 1>.doc -o test.doc

That's it! These three requests are equivalent to uploading a file, ordering the transcript and then downloading the transcript through our web interface.

We provide only email support for the API. Please send an email tosupport@scribie.com for any questions or assistance.