Sonix API Documentation

Better integrate your software with Sonix

Getting Started 🎤

Requirements

The Sonix API is available to all paying subscribers. With the API, you can programatically upload your media files for transcription and download the resulting transcript as text.

API Key

If you are subscribed to Sonix (paid subscription), you can access your API key here: https://my.sonix.ai/api

If you are on a Sonix trial account, email [email protected] to request an API key.

Authentication

All Sonix API operations must be authorized with your API key via a Bearer Authorization header.

The current version of the API is v1. All operations use the following base URL: https://api.sonix.ai/v1

Example Curl Request

curl -H "Authorization: Bearer <API Key>" 

Supported Languages

Sonix can transcribe files in any of the following languages. Contact us to request an additional language.

Language Code
Englishen
Frenchfr
Germande
Spanishes
Arabicar
Armenianhy-AM
Bulgarianbg
Catalanca
Croatianhr
Chinese (Cantonese)yue-Hant-HK
Chinese (Mandarin)cmn-Hans-CN
Czechcs
Danishda
Dutchnl
Finnishfi
Greekel
Hebrewhe-IL
Hindihi
Hungarianhu
Indonesianid-ID
Italianit
Japaneseja
Koreanko
Latvianlv
Lithuanianlt
Malayms-MY
Norwegiannb-NO
Polishpl
Portuguesept
Romanianro
Russianru
Slovaksk
Sloveniansl
Swedishsv
Thaith-TH
Turkishtr-TR
Vietnamesevi-VN

Error Codes

Below are all the possible error codes you may encounter using the API.

Error Code Message Description
400Invalid request We do not know how to handle your request. Most likely your parameters are invalid or missing. Check the error message for details.
401Invalid API Key We do not recognize your API key. Check your API key and resubmit.
402Payment Error We had an issue processing your last payment. Please login to update payment information.
403No API access Your account is no longer subscribed to Sonix. Only paid subscribers can use the Sonix API.
404Media file not found Media file with associated ID cannot be found or is not associated with this account.
409Media file is being transcribed You are requesting a transcript for media that is still being transcribed. Please try again later.

Sample Response Body

{
  "code": 401,
  "message": "Invalid API key"
} 

Media 💽

Media Attributes

Media files will be returned with the following attributes:

Field Description
idUnique identifier for the media file
nameUser given name for the media file. Defaults to the filename.
durationDuration in seconds
languageLanguage code for the transcription.
videotrue or false depending on whether the given media is a video file or audio only.
created_atTime at which the media was uploaded. Measured in seconds since the Unix epoch.
public_urlURL for shareable, read-only view of the transcript.
custom_dataSet of key-value pairs that you can attach to the media. This can be useful for storing additional information about file.
status

Current status of the media. Possible status codes are:

  • preparing: Preparing the media file for transcription
  • transcribing: Transcription is in progress
  • completed: Transcription is completed
  • blocked: Transcription blocked due to account issue. Please contact support.
  • failed: Transcription failed due to invalid media format

List Media Files

HTTP MethodGET
Endpoint/v1/media
ReturnsArray of all media files in your account. Files are ordered by creation date, with the most recent file listed first.

Parameters

Field Default Description
page1 Current page number. The API will return 100 files at a time. The response will include total_pages and current page, page.
status Filter by media status. You can filter by completed, transcribing, aligning, or failed.
search Search files that match by name.

Example Usage

curl -XGET https://api.sonix.ai/v1/media?page=0 -H "Authorization: Bearer <API Key>" 

Sample Response Body

{
  "media": [
      {
        "id": "DT2ePNvJ",
        "name": "My Podcast",
        "duration": 95.2,
        "language": "en-GB",
        "video": false,
        "status": "preparing",
        "created_at": 1533170400,
        "public_url": "https://sonix.ai/r/NNvAJNpj6Ga4D8yKVQuIxBxmY"
      },
      {
        "id": "qmnY1nD5",
        "name": "Phone Call",
        "duration": 858.3,
        "language": "it",
        "video": false,
        "status": "completed",
        "created_at": 1533170524,
        "public_url": "https://sonix.ai/r/NNvAJNpj6Ga4D8yKVQuIxBxmY"
      }
  ],
  "page": 0,
  "total_pages": 1
} 

Submit New Media

HTTP MethodPOST
Endpoint/v1/media
ReturnsMedia JSON for the newly uploaded file.

Parameters

Field Required Description
fileThe audio or video file as multi-part form data.
file_url URL pointing to the audio/video file. NOTE: Only one of file or file_url is required.
languageLanguage code for the transcription. See supported languages for valid language codes.
name Name of the file in Sonix. If no name is provided, we will default to the filename.
transcript_textExisting transcript - if present, will align the transcript rather than transcribing.
folder_id ID of folder to place the media in. If left blank, the media will be placed in the Home directory
keywords Comma separated list of words or phrases to use as hints to the transcription engine. If this is provided, then the account level keywords will not be used.
custom_data Set of key-value pairs that you can attach to the media.
callback_url URL for Sonix to make a POST request notifying of a change in transcript status (either failed or completed). The POST will include the media status JSON.

Example Usage

curl -XPOST https://api.sonix.ai/v1/media -H "Authorization: Bearer <API Key>"  \
  -F [email protected]_audio.mp3 \
  -F language=en \
  -F name='Podcast Episode 45' \
  -F keywords='Sonix, Bergamasco, Kairos, Chewbacca' \
  -F custom_data='{"internal_id": "123412", "customer_email": "[email protected]"}' 

Sample Response Body

{
  "id": "DT2ePNvJ",
  "name": "My Podcast",
  "status": "preparing",
  "language": "en",
  "created_at": 1533170400,
  "public_url": "https://sonix.ai/r/NNvAJNpj6Ga4D8yKVQuIxBxmY",
  "custom_data": {"internal_id": "123412", "customer_email": "[email protected]"}
} 

Get Media Status

HTTP MethodGET
Endpoint/v1/media/<id>
ReturnsMedia JSON for the corresponding id

Example Usage

curl -XGET https://api.sonix.ai/v1/media/qmnY1nD5 -H "Authorization: Bearer <API Key>" 

Sample Response Body

{
  "id": "qmnY1nD5",
  "name": "Phone Call",
  "duration": 858.3,
  "language": "en",
  "video": false,
  "status": "completed",
  "created_at": 1533170524
} 

Update Media

HTTP MethodPUT
Endpoint/v1/media/<media id>
ReturnsUpdated Media JSON

Parameters

Field Description
nameNew name for the media file.
custom_labelApply a custom label to the file.

Example Usage

curl -XPUT https://api.sonix.ai/v1/media/DT2ePNvJ -H "Authorization: Bearer <API Key>"  \
      -F name="New Name" \
      -F custom_label="In Progress" 

Sample Response Body

{
  "id": "DT2ePNvJ",
  "name": "New Name",
  "status": "completed",
  "language": "en",
  "created_at": 1533170400,
  "public_url": "https://sonix.ai/r/NNvAJNpj6Ga4D8yKVQuIxBxmY",
  "custom_label": "In Progress",
} 

Delete Media

HTTP MethodDELETE
Endpoint/v1/media/<media id>

Example Usage

curl -XDELETE https://api.sonix.ai/v1/media/qmnY1nD5 -H "Authorization: Bearer <API Key>" 

Sample Response Body

{
  "status": 204
} 

Media Exports 💽

Create Export

Export a media file with either only highlights or all strikethroughs removed

HTTP MethodPOST
Endpoint/v1/media/<media id>/media_exports
ReturnsID and status of the media export

Parameters

Field Default Description
media_formatmp3Can be either mp3, wav, or mp4. mp4 is only valid if the media file is video.
remove_strikethroughfalseBy default, a media file with only highlights will be returned. If set to true, then the full media file will be returned with only strikethroughs removed.

Example Usage

curl -XPOST https://api.sonix.ai/v1/media/qmnY1nD5/media_exports -H "Authorization: Bearer <API Key>"  \
  -F media_format='wav' \
  -F remove_strikethrough=true 

Sample Response Body

{
  "id": "DT2ePKvJ",
  "status": 'processing'
} 

Get Media Export Status

HTTP MethodGET
Endpoint/v1/media_exports/<id>
ReturnsMedia Export JSON for the corresponding id

Example Usage

curl -XGET https://api.sonix.ai/v1/media_exports/DT2ePKvJ -H "Authorization: Bearer <API Key>" 

Sample Response Body

{
  "id": "DT2ePKvJ",
  "status": "completed",
  "file_url": "https://sonix-ai.s3.amazonaws.com/highlights/myfile.mp3"
} 

Transcripts 📄

Get Text Transcript

The media status must be completed before requesting the transcript.

HTTP MethodGET
Endpoint/v1/media/<media id>/transcript
ReturnsText of the transcript for the requested media file

Example Usage

curl -XGET https://api.sonix.ai/v1/media/qmnY1nD5/transcript -H "Authorization: Bearer <API Key>" 

Sample Response Body

Phone Call with John

Martin: [00:00:01] Hello, is now still a good time to chat?

John: [00:00:13] Yes, lets chat. 

Get SRT/VTT File

The media status must be completed before requesting the SRT File.

HTTP MethodGET
Endpoint (SRT)/v1/media/<media id>/transcript.srt
Endpoint (VTT)/v1/media/<media id>/transcript.vtt
ReturnsText of the transcript for the requested media file

Parameters

Field Default Description
speaker_displaynone How the speaker shoudl be displayed. Options are none for no speakers, as_typed for how the speakers are displayed in the transcript, or uppercase to force speaker names to be uppercase.
limit_captionsfalse Whether subtitles should be limited by duration or number of characters. Default is false, which then breaks subtitles by paragraph. Must be set to true to use max_characters or max_duration options.
subtitle_lines1 Whether the subtitles should be split over 1 or 2 lines.
max_characters90 Maximum number of characters a subtitle can contain.
max_duration10 Maximum duration, in seconds, a subtitle should cover.

Example Usage

curl -XGET https://api.sonix.ai/v1/media/qmnY1nD5/transcript.srt -H "Authorization: Bearer <API Key>" \
  -F speaker_display='uppercase' \
  -F limit_captions=true \
  -F subtitle_lines=2 \
  -F max_characters=120 \
  -F max_duration=8 

Sample Response Body

1
00:00:01,350 --> 00:00:08,700
MARTIN LUTHER KING:
I have a dream that one day this nation will rise up,

2
00:00:10,110 --> 00:00:12,330
MARTIN LUTHER KING:
live out the true meaning of its creed.

3
00:00:13,620 --> 00:00:19,080
MARTIN LUTHER KING:
We hold these truths to be self-evident,
that all men are created equal. 

Get JSON Transcript

The media status must be completed before requesting the JSON file.

HTTP MethodGET
Endpoint/v1/media/<media id>/transcript.json
ReturnsTranscript in JSON format, with start and end timestamps for each word.

Example Usage

curl -XGET https://api.sonix.ai/v1/media/qmnY1nD5/transcript.json -H "Authorization: Bearer <API Key>" 

Sample Response Body

{
  "name": "Phone Call with John",
  "transcript": [
    {
      "speaker": "Martin",
      "start_time": 1.32,
      "end_time": 8.55,
      "words": [
        {
          "text": "Hello,",
          "start_time": 1.32,
          "end_time": 1.58
        },
        {
          "text": "is",
          "start_time": 1.58,
          "end_time": 1.8
        },
        {
          "text": "now",
          "start_time": 1.8,
          "end_time": 1.87
        },
        {
          "text": "still",
          "start_time": 1.87,
          "end_time": 2.32
        },
        {
          "text": "a",
          "start_time": 3.83,
          "end_time": 3.95
        },
        {
          "text": "good",
          "start_time": 3.95,
          "end_time": 4.26
        },
        {
          "text": "time to",
          "start_time": 4.26,
          "end_time": 6.65
        },
        {
          "text": "chat?",
          "start_time": 6.69,
          "end_time": 8.55
        }
      ]
    },
    {
      "speaker": "John",
      "start_time": 10.24,
      "end_time": 16.33,
      "words": [
        {
          "text": "Yes,",
          "start_time": 10.24,
          "end_time": 10.46
        },
        {
          "text": "lets",
          "start_time": 10.46,
          "end_time": 10.67
        },
        {
          "text": "chat!",
          "start_time": 10.78,
          "end_time": 16.33
        }
      ]
    }
  ]
} 

Update Transcript

The media status must be completed before updating the transcript.

HTTP MethodPUT
Endpoint/v1/media/<media id>/transcript

Example Usage

curl -XPUT https://api.sonix.ai/v1/media/qmnY1nD5/transcript -H "Authorization: Bearer <API Key>" \
  -F transcript='[{"speaker": "Martin","start_time": 1.32,"end_time": 8.55,"words": [{"text": "Hello,","start_time": 1.32,"end_time": 1.58,"highlight": true}, ...]}' 

Translations 📄

Create Translation

The media status must be completed before requesting a translation.

HTTP MethodPOST
Endpoint/v1/media/<media id>/translations
ReturnsThe status of the translation

Example Usage

curl -XGET https://api.sonix.ai/v1/media/qmnY1nD5/translations -H "Authorization: Bearer <API Key>" \
-F language=es 

Sample Response Body

{"language":"es","status":"queued"} 

Get Translation Status

HTTP MethodGET
Endpoint/v1/media/<media id>/translations/<language>
ReturnsThe status of the translation

Example Usage

curl -XGET https://api.sonix.ai/v1/media/qmnY1nD5/translations/es -H "Authorization: Bearer <API Key>" 

Sample Response Body

{"language":"es","status":"completed"} 

Export Translation

To export a translation, use the any of the transcript endpoints, but pass in a language parameter.

Example Usage

curl -XGET https://api.sonix.ai/v1/media/qmnY1nD5/transcript.srt -H "Authorization: Bearer <API Key>" \
  -F language=es \
  -F speaker_display='uppercase' \
  -F limit_captions=true \
  -F subtitle_lines=2 \
  -F max_characters=120 \
  -F max_duration=8 

Sample Response Body

1
00:00:01,350 --> 00:00:08,700
MARTIN LUTHER KING:
Tengo el sueño de que algún día esta nación se levantará,

2
00:00:10,110 --> 00:00:12,330
MARTIN LUTHER KING:
vive el verdadero significado de su credo.

3
00:00:13,620 --> 00:00:19,080
MARTIN LUTHER KING:
Sostenemos que estas verdades son evidentes por sí mismas,
que todos los hombres son creados iguales. 

Folder 📂

New Folder

Folders allow organization of your media, as well as the ability to set permissions on groups of files within that folder.

HTTP MethodPOST
Endpoint/v1/media/folders
ReturnsThe folder attributes

Parameters

Field Required Description
nameName of the folder
parent_folderID of parent folder. If left blank, folder will be placed in your root folder
access_controlDefaults to interal. Can also be exernal or restricted.
restricted_usersIf access_control is set to restricted, this should be an array of email addresses to restrict the access to.

Example Usage

curl -XPOST https://api.sonix.ai/folders -H "Authorization: Bearer <API Key>" \
  -F name="2019 Podcasts" \
  -F access_control="restricted" \
  -F "restricted_users[][email protected]" \
  -F "restricted_users[][email protected]" 

Sample Response Body

{
  "id": "34567",
  "name": "2019 Podcasts",
  "access_control": "restricted",
  "restricted_users": ["[email protected]", "[email protected]"]
} 

List Folders

HTTP MethodGET
Endpoint/v1/folders
ReturnsArray of folders and their access controls

Example Usage

curl -XGET https://api.sonix.ai/v1/folders -H "Authorization: Bearer <API Key>" 

Sample Response Body

{
  "folders":  [
    {
      "id": "123",
      "name": "root"
    },
    {
      "id": "456",
      "email": "Podcasts",
      "access_control": "internal"
    },
    {
      "id": "789",
      "email": "Podcasts/Season 1",
      "access_control": "restricted",
      "restricted_users": ["[email protected]", "[email protected]i"]
    }
  ]
} 

Update Folder

Update an existing folder

HTTP MethodPUT
Endpoint/v1/folders/<folder id>

Example Usage

curl -XPUT https://api.sonix.ai/v1/folders/34567 -H "Authorization: Bearer <API Key>" \
  -F name='Interviews' 

Sample Response Body

{
  "id": "34567",
  "name": "Interviews",
  "access_control": "internal"
} 

Users 👪

List Users

HTTP MethodGET
Endpoint/v1/users
ReturnsArray of users with their name, email, and role.

Example Usage

curl -XGET https://api.sonix.ai/v1/users -H "Authorization: Bearer <API Key>" 

Sample Response Body

{
  "users":  [
    {
      "name": "Joe Smith",
      "email": "[email protected]",
      "role": "Admin",
    },
    {
      "name": "Andy Jones",
      "email": "[email protected]",
      "role": "Producer"
    }
  ]
} 

Sharing 🙌

New Share

Sharing allows you to share your transcripts and media with other Sonix users. Transcripts can be shared either as view only or editable. To update permissions for an email that that has already been shared, submit a new share request and the permissions will be overwritten.

HTTP MethodPOST
Endpoint/v1/media/<id>/shares
ReturnsThe email and permissions for the user

Parameters

Field Required Description
emailEmail of the person to share with.
can_editWhether the user can edit or the transcript is read-only. Must be true or false. Default is false.
notesAdditional information to be put in the email to the user.

Example Usage

curl -XPOST https://api.sonix.ai/v1/media/qmnY1nD5/share -H "Authorization: Bearer <API Key>" \
  -F email="[email protected]" \
  -F notes="Can you edit this by 7pm tonight?" \
  -F can_edit=true 

Sample Response Body

{
  "email": "[email protected]",
  "can_edit": true,
} 

List Shares

HTTP MethodGET
Endpoint/v1/media/<media id>/shares
ReturnsArray of users and their permissions for the associated media.

Example Usage

curl -XGET https://api.sonix.ai/v1/media/qmnY1nD5/shares -H "Authorization: Bearer <API Key>" 

Sample Response Body

{
  "shares":  [
    {
      "email": "[email protected]",
      "can_edit": true,
    },
    {
      "email": "[email protected]",
      "can_edit": false,
    }
  ]
} 

Delete Shares

Delete shares for media file with associated email address

HTTP MethodDELETE
Endpoint/v1/media/<media id>/shares

Example Usage

curl -XDELETE https://api.sonix.ai/v1/media/qmnY1nD5/shares -H "Authorization: Bearer <API Key>" \
  -F email='[email protected]' 

Sample Response Body

{
  "status": 204
}