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
Spanish & Englishes-en
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
Ukrainianuk
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.
folder_id Scope files only to those with the given folder_id
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. The limit is 100MB using this parameter. For larger files, use file_url
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 file=@my_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]"}
} 

Submit Multitrack Media

The Sonix API also supports channel based speaker detection if your input is encoded on multiple channels and each channel is isolated with a distinct speaker. This is the same as the Submit New Media endpoint, with additional parameters.

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

Parameters

These are in addition to the supported parameters for Submit New Media.

Field Required Description
multitrackFor multitrack files, this must be set to true
speaker_labelsA JSON array of the speaker labels. If speaker labels are not given, then defaults will be used.

Example Usage

curl -XPOST https://api.sonix.ai/v1/media -H "Authorization: Bearer <API Key>"  \
  -F file=@my_audio.mp3 \
  -F language=en \
  -F name='Podcast Episode 45' \
  -F multitrack=true \
  -F speaker_labels='["Interviewer", "Guest"]' 

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,
  "folder": {
    "name": "Podcasts",
    "id": "JOAXjoG0"
  }
} 

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.
folder_idMove file to another folder within the account

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,
  "updated_at": 1625159359,
  "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 timecodes 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}, ...]}' 

Split Transcript

Automatically split the transcript into subtitles. The media status must be completed before splitting the transcript.

HTTP MethodPUT
Endpoint/v1/media/<media id>/transcript/split
ReturnsUpdated transcript in JSON format.

Parameters

Field Default Description
subtitle_lines1 Whether the subtitles should be split over 1 or 2 lines.
max_characters45 Maximum number of characters a subtitle can contain.
max_duration10 Maximum duration, in seconds, a subtitle should cover.
max_cps12 Maximum characters per second
language (optional) If splitting a translation, pass in the language to of the transcript.

Example Usage

curl -XPUT https://api.sonix.ai/v1/media/qmnY1nD5/transcript/split -H "Authorization: Bearer <API Key>" \
  -F subtitle_lines=2 -F max_characters=50 -F max_duration=10 -F max_cps=10 

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 -XPOST 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. 

Video Burn Ins 📄

Create Burn In

Video burn ins allow you to add subtitles directly on to the video. The media status must be completed before requesting a burn in.

HTTP MethodPOST
Endpoint/v1/media/<media id>/video_burn_ins
ReturnsThe ID and status of the burn in

Parameters

All parameters are optional.

Field Default Description
languagesource lang The language will default to the original transcript language. If translations have been created, then you can specify one of those languages here to use instead.
fontArial Font used for subtitles. Available fonts are Arial, Arial Black, Comic Sans MS, Courier New, Georgia, Impact, Lucida Grande, Palatino, Segoe UI, Tahoma, Times New Roman, Tiresias Infofont, Trebuchet MS, Verdana
font_size16 Font size for subtitles. Can be anything from 10 through 42.
font_color#FFFFFF Font color for subtitles.
boldfalse Whether text should be bold or not
italicfalse Whether text should be italic or not
h_aligncenter How the text should be aligned horizontally. Can be either centerright, or left
v_alignbottom How the text should be aligned vertically. Can be either top, middle, or bottom
border_stylewrap How the background of the subtitles are styled. Can be none, outline, wrap, or full
border_color#000000 Color for border around subtitle text
ratiooriginal Aspect ratio for output video. Options are original, 1:1, 9:16, 16:9, 5:4, or 4:5
export_positionfit How the video should be scaled to fit the aspect ratio. fitto ensure the entire video fits within the frame, or fillthe entire frame, which may result in cropping part of the video.
background_color#000000 Background color for when the fit option is used for export_position.

Example Usage

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

Sample Response Body

{"video_export_id":"abc123","status":"processing","url":"https://my.sonix.ai/video_exports/xxxxxxxxxxx"} 

Get Burn In Status

HTTP MethodGET
Endpoint/v1/video_burn_ins/<video_export_id>
ReturnsThe status and url of the burn in

Example Usage

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

Sample Response Body

{"video_export_id":"abc123","status":"completed","url":"https://my.sonix.ai/video_exports/xxxxxxxxxxx"} 

Summarizations 📄

Create new summarization

Summarizations allow you to summarize or ask questions about your media file. The media status must be completed before requesting a summarization.

HTTP MethodPOST
Endpoint/v1/media/<media id>/summarizations
ReturnsThe ID and status of the summarization

Parameters

Field Required Description
promptThe prompt used for summarization. For example "Summarize in 10 sentences", "Create a summary in German", or "Write 5 promotional tweets for this podcast"

Example Usage

curl -XPOST https://api.sonix.ai/v1/media/qmnY1nD5/summarizations -H "Authorization: Bearer <API Key>" \
-F Prompt='Summarize in 10 sentences' 

Sample Response Body

{"summarization_id":"abc123","status":"processing"} 

Get Summarization

HTTP MethodGET
Endpoint/v1/summarizations/<summarization_id>
ReturnsThe completed summary and prompt used

Example Usage

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

Sample Response Body

{"summarization_id":"abc123","status":"completed","prompt":"Summarize", summary: "This is a summary of the media file."} 

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/v1/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]"]
    }
  ]
} 

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":  [
    {
      "id": "qmnY1nD1",
      "name": "Joe Smith",
      "email": "[email protected]",
      "role": "admin",
    },
    {
      "id": "qmnY1nD2",
      "name": "Andy Jones",
      "email": "[email protected]",
      "role": "producer"
    }
  ]
} 

Invite User to Account

HTTP MethodPOST
Endpoint/v1/users
ReturnsNew user that has been created

Parameters

Field Required Description
nameName of the user
emailEmail of the user
roleRole of the user. Can be admin, producer , editor, team_member, individual_member, view_only, billing_admin, disabled, external_editor, or external_viewer.

Example Usage

curl -XPOST https://api.sonix.ai/v1/users -H "Authorization: Bearer <API Key>" -F email='[email protected]' -F role='Producer' -F name='John Doe' 

Sample Response Body

{
  "id": "qmnY1nD2",
  "name": "John Doe",
  "email": "[email protected]",
  "role": "producer"
} 

Update User Role

HTTP MethodPUT
Endpoint/v1/users/<user id>
ReturnsUpdated user object

Example Usage

curl -XPUT https://api.sonix.ai/v1/users/qmnY1nD2 -H "Authorization: Bearer <API Key>" -F role='Member' 

Sample Response Body

{
  "id": "qmnY1nD2",
  "name": "John Doe",
  "email": "[email protected]",
  "role": "member"
} 

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
}