Synopsis

POST /transcribe/$org_short/$folder -F token=$token -F file=@$input_file

/transcribe does not accept token or file arguments as query parameters. The -F argument in the synopsis is used with cURL to send form parameters.

$org_short

Organization short name used to filter the request.

$folder

Folder used to filter the request.

$token

Authorization token with the required read or write permissions for the request.

$input_file

File path for query input.

Content Types

• POST requests require the "multipart/form-data" MIME type, and return data with the "text/html" MIME type.

• Errors are returned with the "text/html" MIME type.

Example request

curl -X POST 'http://example.company.com:3000/transcribe/co1-orgA/folder0' -F token=$token -F file=@0706.mp3.zip

d41814eb-b055-4169-83a8-e7f2d1f76b18

Example shell script implementation

Refer to the transcription and results shell script tutorial for an example of using /transcribe and /request together.

/transcribe with Amazon S3

To use /transcribe with data stored in Amazon Web Service Simple Storage System (AWS S3), include the relevant S3 credentials and bucket location as form parameters with the request.

The following example shows the general format of a cURL /transcribe request to transcribe a file or directory that is stored in AWS S3.

curl -F token=$token \
     -F aws_id=$aws_access_key \
     -F aws_secret=$aws_secret_key \
     -F s3key=s3://$bucket/$filepath \
     -F region=$s3_region \
     -X POST http://$host/transcribe/$org_short/$folder

$host

Hostname or URL for the system running V‑Spark.

$token

Authorization token with the required read or write permissions for the request.

$org_short

Organization short name used to filter the request.

$folder

Folder used to filter the request.

$aws_access_key

The Amazon access key for the source data bucket.

$aws_secret_key

The secret Amazon key for the source data bucket.

$bucket

The name for the Amazon S3 source data bucket.

$path

The path to the file, zip, or hierarchy of files to be processed.

Specifying a directory queues all of the files in that directory for transcription.

Files that are not in a supported format are not processed. These files are noted in the V‑Spark folder's processing log as UNSUPPORTED.

$s3_region

You must specify the Amazon S3 region of the S3 bucket. The region option on the request specifies which regional endpoint to use for the request.

This option reduces request latency and is required.

The following example request calls /transcribe with a zip stored in S3.

curl -F token=0123456789abcde0123456789abcde01 \
     -F aws_id=012345678901234567890 \
     -F aws_secret=01234567890123456789012345678901234567890 \
     -F s3key=s3://example/documentation-TEST.zip \
     -F region=us-east-1 \
     -X POST http://example.company.com:3000/transcribe/Test-Testing/Test01

This example submits the file documentation-TEST.zip in the bucket example and puts the results of that transcription in the Test01 folder of the organization Test-Testing. The example call returns the requestid for the job.

By default, the request only reads data from the specified S3 source and transcribed files remain stored in those buckets.

Include delete=true with the /transcribe request to delete files stored in S3 after they are processed, like this next example.

curl -F token=0123456789abcde0123456789abcde01 \
     -F aws_id=012345678901234567890 \
     -F aws_secret=01234567890123456789012345678901234567890 \
     -F s3key=s3://example/documentation-TEST.zip \
     -F region=us-east-1 \
     -F delete=true \
     -X POST http://example.company.com:3000/transcribe/Test-Testing/Test01