Automated transcription by Sonix starts with a great microphone

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

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

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' 

Sample Response Body

{
  "id": "DT2ePNvJ",
  "name": "My Podcast",
  "status": "preparing",
  "language": "en",
  "created_at": 1533170400,
  "public_url": "https://sonix.ai/r/NNvAJNpj6Ga4D8yKVQuIxBxmY"
} 

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
} 

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 File

The media status must be completed before requesting the SRT File.
HTTP MethodGET
Endpoint/v1/media/<media id>/transcript.srt
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}, ...]}' 

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": "t[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
} 

The best automated transcription service in 2020 ๐Ÿš€

Easily convert your audio to text with Sonix

Sonix transcribes, timestamps, and organizes your audio and video files so they are easy to search, edit, and share. Start your free trial todayโ€”all features included, no credit card required.

Try Sonix for freeIncludes 30 minutes of free transcription

Transcribe and translate confidently knowing youโ€™re backed by our award-winning team who is ready to answer your questions. You can also visit our Support Center for tips, articles, and videos.

Visit our Help Center