Speech To Text API Documentation and Reference

Get started with Ebby.co powerful Speech To Text API

Getting started

Introduction

Ebby's Speech To Text API is available to all customers.

Using the API you can programmatically upload, transcribe and get your transcript or closed captions.

Base URL and Versioning

Base URL has the following format: https://api.ebby.co/VERSION

The latest version is v1, so the most current base URL is https://api.ebby.co/v1

Endpoints described in the documentation are relative to the base URL above.

Authentication

Ebby's API uses API keys to authenticate requests.

Generate an API key in your Account page.

Your API key carry many privileges, so be sure to keep it secure! Do not share your API key in publicly accessible areas such as GitHub, client-side code, etc.

All API requests should include a Bearer Authorization header with your API key.

Authorization: Bearer API_KEY
Unauthorized requests

Unauthorized API requests will return an HTTP response code 401 with the following JSON:

{
    "message": "Unauthenticated."
}
Error Codes

Ebby uses conventional HTTP response codes to indicate the success or failure of an API request.
In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, unauthorized request, etc.). Codes in the 5xx range indicate an error with Ebby's servers (which are rare).

Erroneous responses include a message with more information:

{
    "message": "Unauthenticated."
}
Response code Meaning Description
200 OK Everything worked as expected.
204 No Content The requested transcript has no text. Usually due to low quality audio or wrong transcription language/dialect (the provided language parameter does not actually match the spoken language in the recording).
401 Unauthorized Request Usually due to invalid or missing API Key.
400 Bad Request Ebby cannot process your request, usually due to invalid or missing parameters.
402 Payment Required You do not have sufficient transcription credit to transcribe this file.
403 Forbidden Unauthorized request.
404 Not Found The file you requested was not found.
429 Too Many Requests You have reached your rate limit.
500 Internal Server Error Ebby failed to process your request.
Rates & Limits

Ebby's API accepts no more than one request every 3 seconds.

Transcribe

Send a media file for transcription

Request
HTTP Method POST
Endpoint /transcribe
Parameters
Name Required Default Description
file Required The audio or video file as multi-part form data.
language Required Language code describing the spoken language in the media file. See supported languages for valid language codes.
callback_url Required URL for Ebby to make a POST request once transcription is done (successfully or not). See callback URL for more information.
multi_speakers true Indicate if there's more than one speaker in the recording.
identify_speakers false

When set to true Ebby's AI will try and distinguish speakers by voice (currently in beta). Otherwise, speakers are distinguished by other criteria.

Available only for the following language codes (ignored otherwise): ar-sa, ar-ae, zh, zh-tw, da-dk, en-au, en-ca, en-gh, en-hk, en-in, en-ie, en-ke, en-nz, en-ng, en-pk, en-ph, en-ab, en-sg, en-za, en-tz, en-gb, en-us, en-wl, fr-fr, de-de, de-ch, id-id, it-it, ja-jp, ko-kr, ms-my, fa-ir, pt-br, pt-pt, ru-ru, es-es, ta-in, te-in, th-th.
num_speakers 2 If identify_speakers is set to true, specify how many speakers are in the recording.
filter_profanity false Ebby will attempt to filter out profane words by replacing them with their first letter followed by asterisks (e.g. f***). This filter is not applied to phrases.
Example
curl -XPOST https://api.ebby.co/v1/transcribe \
    -H "Authorization: Bearer API_KEY" \
    -F file=@interview.mp3 \
    -F language=en-us \
    -F callback_url=https://example.com/ebby_callback
Response
Name Type Description
id string Unique ID of the transcribed file
name string The name of the transcribed file
duration int The transcribed file's duration, in seconds
created_at string ISO-8601 compatible date
updated_at string ISO-8601 compatible date
status string transcribing
Example
{
    "id": "RwwHNc97",
    "name": "interview.mp3",
    "duration": 3600,
    "created_at": "2021-02-18T13:16:32.000000Z",
    "updated_at": "2021-02-18T13:16:32.000000Z",
    "status": "transcribing"
}
Limits

Only one concurrent call is allowed.

If you need to make several Transcribe calls, execute the next call after the response was received.

Callback URL

Ebby will POST the callback_url once the transcription process is done, either successfully or not.

Transcription completed successfully

Will include status property with completed as its value.

{
    "id": "RwwHNc97",
    "name": "interview.mp3",
    "duration": 3600,
    "created_at": "2021-02-18T13:16:32.000000Z",
    "updated_at": "2021-02-18T13:16:32.000000Z",
    "status": "completed"
}
Transcription failed

Will include status property with failed as its value.

The message property provides additional information.

{
    "id": "RwwHNc97",
    "name": "interview.mp3",
    "duration": 3600,
    "created_at": "2021-02-18T13:16:32.000000Z",
    "updated_at": "2021-02-18T13:16:32.000000Z",
    "status": "failed",
    "message": "Identify Speakers is not supported for Hindi (India)"
}
Supported Languages

Lists of all supported languages and their codes

Name Language Code
Afrikaans (South Africa) af-za
Albanian (Albania) sq-al
Amharic (Ethiopia) am-et
Arabic (Algeria) ar-dz
Arabic (Bahrain) ar-bh
Arabic (Egypt) ar-eg
Arabic (Iraq) ar-iq
Arabic (Israel) ar-il
Arabic (Jordan) ar-jo
Arabic (Kuwait) ar-kw
Arabic (Lebanon) ar-lb
Arabic (Mauritania) ar-mr
Arabic (Morocco) ar-ma
Arabic (Oman) ar-om
Arabic (Qatar) ar-qa
Arabic (Saudi Arabia) ar-sa
Arabic (State of Palestine) ar-ps
Arabic (Tunisia) ar-tn
Arabic (United Arab Emirates) ar-ae
Arabic (Yemen) ar-ye
Armenian (Armenia) hy-am
Azerbaijani (Azerbaijan) az-az
Basque (Spain) eu-es
Bengali (Bangladesh) bn-bd
Bengali (India) bn-in
Bosnian (Bosnia and Herzegovina) bs-ba
Bulgarian (Bulgaria) bg-bg
Burmese (Myanmar) my-mm
Catalan (Spain) ca-es
Chinese, Cantonese (Traditional Hong Kong) yue-hant-hk
Chinese, Mandarin (Simplified, China) zh
Chinese, Mandarin (Traditional, Taiwan) zh-tw
Croatian (Croatia) hr-hr
Czech (Czech Republic) cs-cz
Danish (Denmark) da-dk
Dutch (Belgium) nl-be
Dutch (Netherlands) nl-nl
English (Australia) en-au
English (Canada) en-ca
English (Ghana) en-gh
English (Hong Kong) en-hk
English (India) en-in
English (Ireland) en-ie
English (Kenya) en-ke
English (New Zealand) en-nz
English (Nigeria) en-ng
English (Pakistan) en-pk
English (Philippines) en-ph
English (Scotland) en-ab
English (Singapore) en-sg
English (South Africa) en-za
English (Tanzania) en-tz
English (United Kingdom) en-gb
English (United States) en-us
English (Wales) en-wl
Estonian (Estonia) et-ee
Filipino (Philippines) fil-ph
Finnish (Finland) fi-fi
French (Belgium) fr-be
French (Canada) fr-ca
French (France) fr-fr
French (Switzerland) fr-ch
Galician (Spain) gl-es
Georgian (Georgia) ka-ge
German (Austria) de-at
German (Germany) de-de
German (Switzerland) de-ch
Greek (Greece) el-gr
Gujarati (India) gu-in
Hebrew (Israel) iw-il
Hindi (India) hi-in
Hungarian (Hungary) hu-hu
Icelandic (Iceland) is-is
Indonesian (Indonesia) id-id
Italian (Italy) it-it
Italian (Switzerland) it-ch
Japanese (Japan) ja-jp
Javanese (Indonesia) jv-id
Kannada (India) kn-in
Kazakh (Kazakhstan) kk-kz
Khmer (Cambodia) km-kh
Korean (South Korea) ko-kr
Lao (Laos) lo-la
Latvian (Latvia) lv-lv
Lithuanian (Lithuania) lt-lt
Macedonian (North Macedonia) mk-mk
Malay (Malaysia) ms-my
Malayalam (India) ml-in
Marathi (India) mr-in
Mongolian (Mongolia) mn-mn
Nepali (Nepal) ne-np
Norwegian Bokmål (Norway) no-no
Norwegian Bokmål (Norway) nb-no
Persian (Iran) fa-ir
Polish (Poland) pl-pl
Portuguese (Brazil) pt-br
Portuguese (Portugal) pt-pt
Punjabi (Gurmukhi India) pa-guru-in
Romanian (Romania) ro-ro
Russian (Russia) ru-ru
Serbian (Serbia) sr-rs
Sinhala (Sri Lanka) si-lk
Slovak (Slovakia) sk-sk
Slovenian (Slovenia) sl-si
Spanish (Argentina) es-ar
Spanish (Bolivia) es-bo
Spanish (Chile) es-cl
Spanish (Colombia) es-co
Spanish (Costa Rica) es-cr
Spanish (Dominican Republic) es-do
Spanish (Ecuador) es-ec
Spanish (El Salvador) es-sv
Spanish (Guatemala) es-gt
Spanish (Honduras) es-hn
Spanish (Mexico) es-mx
Spanish (Nicaragua) es-ni
Spanish (Panama) es-pa
Spanish (Paraguay) es-py
Spanish (Peru) es-pe
Spanish (Puerto Rico) es-pr
Spanish (Spain) es-es
Spanish (United States) es-us
Spanish (Uruguay) es-uy
Spanish (Venezuela) es-ve
Sundanese (Indonesia) su-id
Swahili (Kenya) sw-ke
Swahili (Tanzania) sw-tz
Swedish (Sweden) sv-se
Tamil (India) ta-in
Tamil (Malaysia) ta-my
Tamil (Singapore) ta-sg
Tamil (Sri Lanka) ta-lk
Telugu (India) te-in
Thai (Thailand) th-th
Turkish (Turkey) tr-tr
Ukrainian (Ukraine) uk-ua
Urdu (India) ur-in
Urdu (Pakistan) ur-pk
Uzbek (Uzbekistan) uz-uz
Vietnamese (Vietnam) vi-vn
Zulu (South Africa) zu-za

Get Transcript

Get the transcript in your desired format

Request
HTTP Method GET
Endpoint /transcript/{id}/{format}
Path Parameters
Name Required Default Description
id Required The file's id.
format Required Valid values are text, html, word, pdf, srt, vtt and json.
Query Parameters
Name Required Default Description
speakers true

Include speaker names in the transcript? Valid values are true or false.

Speaker names are available only for files transcribed with multi_speakers=true.
ts true

Include paragraph timecode in the transcript? Valid values are true or false.

Applicable to text, html, word and pdf formats.
inline_ts false

Add inline timecodes to the transcript? Valid values are true or false.

Applicable to text, html, word and pdf formats.
inline_ts_frequency 10

How often, in seconds should an inline timecode be inserted into the transcript. Valid value is an integer greater than 2.

Applicable to text, html, word and pdf formats, when inline_ts is set to true.
Get Subtitles

An example for srt request and response

Request
curl -XGET https://api.ebby.co/v1/transcript/RwwHNc97/srt \
    -H "Authorization: Bearer API_KEY"
Response
{
    "name": "interview.mp3",
    "transcript": [
        {
            "speaker": "Speaker 1",
            "words": [
                {
                    "startTime": 0.3,
                    "endTime": 0.8,
                    "text": "Hello"
                },
                {
                    "startTime": 0.8,
                    "endTime": 1,
                    "text": "World"
                }
            ]
        }
    ]
}
Get Word

An example request for a transcript exported as a Word document, without speaker names:

Request
curl -XGET https://api.ebby.co/v1/transcript/RwwHNc97/word?speakers=false \
    -H "Authorization: Bearer API_KEY" \
    --output interview.docx

Get File

Get information about a file

Request
HTTP Method GET
Endpoint /file/{id}
Parameters
Name Required Default Description
id Required The file's id.
Response
Name Type Description
id string Unique ID of the transcribed file
name string The name of the transcribed file
duration int The transcribed file's duration, in seconds
created_at string ISO-8601 compatible date
updated_at string ISO-8601 compatible date
language string The file's transcription language code
status string The file's transcription status. One of:
waiting - the file has been uploaded and pending transcription
transcribing - the file is being transcribed
completed - the file was successfully transcribed
failed - the file's last transcription attempt failed
Example
{
    "id": "RwwHNc97",
    "name": "interview.mp3",
    "duration": 3600,
    "created_at": "2021-02-18T13:16:32.000000Z",
    "updated_at": "2021-02-18T13:16:32.000000Z",
    "language": "en-us",
    "status": "completed"
}

List Files

Get information about all your files

Request
HTTP Method GET
Endpoint /files
Query Parameters
Name Required Default Description
page 1 Requested page number.
Response

See Get File response for file properties' description

Example
{
    "data": [
        {
            "id": "RwwHNc91",
            "name": "interview.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "completed"
        },
        {
            "id": "RwwHNc92",
            "name": "interview2.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "completed"
        },
        {
            "id": "RwwHNc93",
            "name": "interview3.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "completed"
        },
        {
            "id": "RwwHNc94",
            "name": "interview4.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "completed"
        },
        {
            "id": "RwwHNc95",
            "name": "interview5.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "completed"
        },
        {
            "id": "RwwHNc96",
            "name": "interview6.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "completed"
        },
        {
            "id": "RwwHNc97",
            "name": "interview7.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "completed"
        },
        {
            "id": "RwwHNc98",
            "name": "interview8.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "completed"
        },
        {
            "id": "RwwHNc99",
            "name": "interview9.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "completed"
        },
        {
            "id": "RwwHNc10",
            "name": "interview10.mp3",
            "duration": 3600,
            "created_at": "2021-02-18T13:16:32.000000Z",
            "updated_at": "2021-02-18T13:16:32.000000Z",
            "language": "en-us",
            "status": "waiting"
        }
    ],
    "links": {
        "first": "https://api.ebby.co/v1/files?page=1",
        "last": "https://api.ebby.co/v1/files?page=3",
        "prev": null,
        "next": "https://api.ebby.co/v1/files?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "path": "https://api.ebby.co/v1/files",
        "per_page": 10,
        "to": 10,
        "total": 27
    }
}

Update File

Update a file's name

Request
HTTP Method POST
Endpoint /file/update/{id}
Parameters
Name Required Default Description
id Required The file's id.
name Required The file's new name.
Example
curl -XPOST https://api.ebby.co/v1/file/update/RwwHNc97 \
    -H "Authorization: Bearer API_KEY" \
    -F name="Phone call with John"
Response

See Get File response for file properties' description

Delete File

Delete a file

Request
HTTP Method DELETE
Endpoint /file/{id}
Parameters
Name Required Default Description
id Required The file's id.
Example
curl -XDELETE https://api.ebby.co/v1/file/RwwHNc97 \
    -H "Authorization: Bearer API_KEY"
Response

See Get File response for file properties' description

Get User

Get your user information

Request
HTTP Method GET
Endpoint /user
Example
curl -XGET https://api.ebby.co/v1/user \
    -H "Authorization: Bearer API_KEY"
Response
Name Type Description
name string Your name
email string Your email
remaining_credit int Your remaining transcription credit, in seconds
Example
{
    "name": "John",
    "email": "john@example.com",
    "remaining_credit": 3600
}