Introduction

The Speechpad API allows you to make flexible integrations with our system.

The Basics

This section outlines the basics of the Speechpad API.

REST API

The Speechpad API adheres to pragmatic REST principals.

Base URLs

Speechpad offers different API URLs for sandbox development and production use.

These URLs also require the API version to be specified as the first part of the URL path. This allows for easy versioning.

Base URL for Sandbox Development

https://api.dev.speechpad.com/2.0-beta

Base URL for Production

https://api.speechpad.com/2.0-beta

Terms

A request is an HTTP request to the API.

A resource is an object acted on by the request. Resources are uniquely identifiable by the request endpoint URL.

An action is the server-side controller action which handles a request

Tenets

The Speechpad API adheres to some simple ground rules as convention:

• Use only standard HTTP verbs, eg. GET, POST, PUT, DELETE
• Appropriate HTTP status codes are included in response headers
• Endpoint URLs use nouns to represent the resource
• HTTP verbs are used to specify how we act on the resource
• All API endpoints must use SSL.

HTTP Verbs

REST is often thought of as mapping CRUD operations to HTTP verbs. However, this is an over-simplified view. With a little deeper understanding of REST principles, and by following this styleguide, it is not difficult to see how to achieve actions beyond basic CRUD.

• GET - Retrieve resource(s)
  • No GET request shall modify the resource
• POST - Create a resource
• PUT - Update a resource (by replacing it with the request payload)
• PATCH - Update a resource (partially)
• DELETE - Delete a resource
• HEAD - Like GET but get only the response headers
• OPTIONS - Check which HTTP verbs are allowed on this resource

Responses

Status Codes

Speechpad uses the following HTTP status codes:

• 200 - OK
• 404 - Not Found
• 500 - Internal Server Error
• 201 - Created
• 304 - Not Modified
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 405 - Method Not Allowed

The API responds with the appropriate status codes in the status response header, and the statusCode property of any Response Envelope contained in the response.

The Response Envelope

Most responses are in the form of a JSON object "envelope". Exceptions include endpoints which return binary data, such as a file download.

{
    "statusCode": 200,
    "errors": [],
    "body": {

    }
}

Response Envelope Properties

Authentication

Speechpad requires exchanging credentials (API keys or username/password) for a token which can be used for subsequent requests. Specifically, tokens are in JSON Web Token (JWT) format.

Authenticating with Username and Password

To authenticate with username and password:

curl 'BASE_URL/auth' -X POST \
  -d 'username=example@domain.tld&password=P@ssworD'

// TODO

// TODO

Make sure to replace the placeholders above with actual values. Hardcoding is not recommended.

On success, your JWT token is found in body.token, and it's expiration time is specified as a Unix timestamp in body.expires.

Authenticating with a username and password is handy in situations where an application consuming the API either is to be used by many different users, or provides an alternative user interface to our core functionality.

An example of an app username and password authentication is acceptable would be a mobile application requiring a user to log into a specific Speechpad account.

Authenticating with API Keys

To authenticate with your API keys (access and secret):

curl 'BASE_URL/auth' -X POST
  -d 'accessKey=MY_ACCESS_KEY&secretKey=MY_SECRET_KEY'

// TODO

// TODO

Make sure to replace the placeholders above with actual values, such as from form fields. Hardcoding is not recommended.

On success, your JWT token is found in body.token, and it's expiration time is specified as a Unix timestamp in body.expires.

The preferred way of authenticating against the API is to use API keys. To obtain an API key, please first create an account at speechpad.com, then request a new Speechapd API key by emailing support@speechpad.com.

Using API keys is recommended for use cases such as B2B apps, custom integrations, or white-labeling our services.

Authorization

curl 'BASE_URL/example' -X GET
  -d 'param=somedata'
  -H 'Authorization:Bearer AUTH_TOKEN'

// TODO

// TODO

Once you have an access token (JWT), you can pass it to other endpoints which require authorization.

To do this, pass the token in the Authorization header.

Customer Actions

The customer API actions allow access to several account features including uploading media, placing orders, and retrieving transcripts and captions.

Assets and Files

In order to perform our work, we first need you to send us your files.

To do this, you simply create an asset resourse, then either upload a file to the resource, or specify a URL to the file.

Create a Media Asset Resource

The Speechpad API allows you to create an asset resource and upload media from your local computer or a public URL.

curl 'BASE_URL/assets' -X POST \
-H 'Authorization: Bearer AUTH_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"asset": {"type": "media"}}'

// TODO

// TODO

We recommend persisting the asset.id somewhere in your system as a cross-reference to the media asset in your Speechpad account.

Create a media asset by POSTing a request to the /assets endpoint. The POST body should contain a JSON object specifying an asset type, in this case media.

Once you have created the media asset, it's time to upload media. This is done by PUTting a file or remote URL to the URL provided by POSTing an /assets

Create a Text Asset Resource

The Speechpad API allows you to create an asset resource and upload text from your local computer or a public URL.

curl 'BASE_URL/assets' -X POST \
-H 'Authorization: Bearer AUTH_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"asset": {"type": "transcript"}}'

// TODO

// TODO

We recommend persisting the asset.id somewhere in your system as a cross-reference to the media asset in your Speechpad account.

Create a text asset by POSTing a request to the /assets endpoint. The POST body should contain a JSON object specifying an asset type, in this case transcription.

Once you have created the text asset, it's time to upload the file. This is done by PUTting a file or remote URL to the URL provided by POSTing an /assets

Uploading - Local file

curl 'FILE_URL?filename=ORIGINAL_FILE_NAME' -X PUT \
-H 'Authorization: Bearer AUTH_TOKEN' \
-H 'Content-Type: video/mp4' \
--data-binary '@LOCAL_FILE_PATH'

// TODO

// TODO

Replace FILE_URL with asset.fileUrl found in the POST response from creating the asset.

Replace CONTENT_TYPE with the proper MIME Type for the file you are uploading.

On success, the response looks like this:

{
    "statusCode": 200,
    "errors": [],
    "body": null
}

Uploading a local file is helpful when you have the files accessible locally by the application consuming the API.

Uploading - Remote file

curl 'FILE_URL' -X PUT \
-H 'Authorization: Bearer AUTH_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"url": "REMOTE_FILE_URL"}'

// TODO

// TODO

Replace FILE_URL with asset.fileUrl found in the POST response from creating the asset.

On success, the response looks like this:

{
    "statusCode": 200,
    "errors": [],
    "body": null
}

Uploading a remote file by URL is helpful in the following scenarios:

1. When your media files are very large or it is not practical to download them to your own system first
2. You have a public URL pointing directly to your media (pre-signed, time-bombed URLs are OK)
3. Your media is already hosted by a common video platforms

Request Parameters

Jobs

Create a Job Resource

curl 'BASE_URL/jobs' -X POST \
-H 'Authorization: Bearer AUTH_TOKEN' \
-H 'Content-Type: application/json'

// TODO

// TODO

On success, the response returns a representation of the new job resource, like this:

{
    "statusCode": 201,
    "errors": [],
    "body": {
        "job": {
            "id": 12345,
            "serviceCode": null,
            "service": null,
            "turnaround": null,
            "priceTotal": 0,
            "customerJobId": null,
            "customerMeta": null,
            "inCart": false,
            "assets": null,
            "instructions": "",
            "options": {
                "verbatim": false,
                "languageSource": false,
                "languageDestination": false,
                "timestamps": false
            },
            "failed": false,
            "failedMessages": null,
            "ordered": null,
            "created": "2018-02-12 21:24:21",
            "deleted": null
        }
    }
}

We recommend persisting the job.id somewhere in your system as a cross-reference to the job created in your Speechpad account.

Attach Media Asset to a Job

curl 'BASE_URL/asset' -X PUT \
-H 'Authorization: Bearer AUTH_TOKEN' \
-H 'Content-Type: text/plain' \
-d 'ASSET_ID'

// TODO

// TODO

On success, the response looks like this:

{
    "statusCode": 200,
    "errors": [],
    "body": null
}

Before ordering a job, you need to PUT a media asset to the job.

Modify job options (optional)

curl 'BASE_URL/jobs/JOB_ID/options' -X PUT \
-H 'Authorization: Bearer AUTH_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"options":{"timestamps":{"timestamps":true,"format":"[00:00:00]","interval":"paragraph"},"verbatim":true,"languageSource":"ptBR"}}'

// TODO

// TODO

On success, the response looks like this:

{
    "statusCode": 200,
    "errors": [],
    "body": null
}

If you want to modify the job to specify any additional instructions, order timestamps, obtain a verbatim transcript, or specify the language of the source media, you can PUT options to the job resource.

Request Parameters

Change job service/priority

curl 'BASE_URL/jobs/JOB_ID/service' -X PUT \
-H 'Authorization: Bearer AUTH_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"service":"STD_CAPTIONS","turnaround":"1WK"}'

// TODO

// TODO

On success, the response looks like this:

{
    "statusCode": 200,
    "errors": [],
    "body": null
}

If you want to modify the job to specify any additional instructions, order timestamps, obtain a verbatim transcript, or specify the language of the source media, you can PUT options to the job resource.

Request Parameters

Get a Job

curl 'BASE_URL/jobs/JOB_ID' -X GET \
-H 'Authorization: Bearer AUTH_TOKEN' \

// TODO

// TODO

On success, the response looks like this:

{
    "statusCode": 200,
    "errors": [],
    "body": {
        "job": {}
    }
}

This endpoint retrieves a single job.

HTTP Request

GET BASE_URL/jobs/JOB_ID

Request Parameters

None.

Get a Collection of Jobs

curl 'BASE_URL/jobs' -X GET \
-H 'Authorization: Bearer AUTH_TOKEN' \

// TODO

// TODO

This endpoint retrieves a collection of your jobs.

HTTP Request

GET BASE_URL/jobs

Request Parameters

Orders

Submit order

curl 'BASE_URL/orders/submit' -X POST \
-H 'Authorization: Bearer AUTH_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"jobIds":[JOB_ID_1,JOB_ID_N],"paymentMethod":"card","card":{"cardType":"visa","number":"4111111111111111","expire":{"month":"03","year":"2025"},"fullName":"Cardholder Name"}}'

// TODO

// TODO

On success, the response looks like this:

Once you have one or more jobs prepared to order, you can go ahead an place the order.

Request Parameters

Use Cases

Uploading and Ordering Files

The Speechpad API allows full control of the media assets and jobs in your account.

The basic workflow for ordering transcripts and captions is as follows:

1. Create a media asset resource
2. Upload media
   • From your local computer
   • From a public URL
3. Create a job resource
4. Attach the media asset to the job
5. Modify job options
6. Change the job service or priority
7. Place an order

Ordering Files for Review

Speechpad offers services for reviewing existing transcripts and captions. This service is appropriate in cases such as:

1. You have existing transcripts or captions you need reviewed for accuracy
2. You have existing transcripts which need timestamps

The flow is very similar to Uploading and Ordering Files, with the exception that you will create both a media asset and a text asset, upload your media and text to the assets, then attach them both to a job.

1. Create a media asset resource
2. Upload media
   • From your local computer
   • From a public URL
3. Create a text asset resource
4. Upload text transcript or captions file
   • From your local computer
   • From a public URL
5. Create a job resource
6. Attach the media asset to the job
7. Attach the text asset to the job
8. Modify job options
9. Change the job service or priority to specify service as "TRANSCRIPTION_REVIEW" or "CAPTION_REVIEW"
10. Place an order

Checking Job Status

Once a job is ordered, it will enter into the appropriate internal workflow for the ordered service.

To periodically check on the status of a job, make a GET request to get a job or get a collection of jobs.

The completed property of a job resource will be null until the completed work is ready to retrieve.

Downloading Completed Files

Once the job is marked as published, an asset containing the completed work is available in the assets array of the job resource.

To retrieve the file, make a GET request to the fileUrl property of the appropriate asset resource.