Sonix API Documentation

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.

Error Codes

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

Sample Response Body

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

Media Attributes

Media files will be returned with the following attributes:

List Media Files

Parameters

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

Parameters

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.

Parameters

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

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

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

Parameters

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

Example Usage

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

Sample Response Body

{
  "status": 204
} 

Create Export

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

Parameters

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

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"
} 

Get Text Transcript

The media status must be completed before requesting the transcript.

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.

Parameters

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.

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.

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.

Parameters

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 

Create Translation

The media status must be completed before requesting a 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

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. 

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.

Parameters

All parameters are optional.

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

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"} 

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.

Parameters

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

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

Create New Batch Summarization

Batch Summarizations allow you to create AI summaries for all media files within a folder at once. The files in the folder must have completed status before requesting a batch summarization.

Parameters

Example Usage

curl -XPOST https://api.sonix.ai/v1/folders/abc123/batch_summarizations -H "Authorization: Bearer " \
-F prompt='Summarize in German' 

Sample Response Body

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

Error Responses

Get Batch Summarization

Example Usage

curl -XGET https://api.sonix.ai/v1/batch_summarizations/abc123 -H "Authorization: Bearer " 

Sample Response Body

{
  "id": "abc123",
  "status": "completed",
  "prompt": "Summarize in German",
  "summaries": [
    {
      "media_id": "abc123",
      "summary": "Dies ist eine Zusammenfassung der ersten Datei..."
    },
    {
      "media_id": "def456",
      "summary": "Dies ist eine Zusammenfassung der zweiten Datei..."
    }
  ]
} 

List Batch Summarizations

Example Usage

curl -XGET https://api.sonix.ai/v1/folders/0dB8e2o6/batch_summarizations -H "Authorization: Bearer " 

Sample Response Body

{
  "batch_summarizations": [
    {
      "id": "abc123",
      "status": "completed",
      "prompt": "Summarize in German",
      "created_at": "2024-11-05T12:00:00Z"
    },
    {
      "id": "def456",
      "status": "processing",
      "prompt": "Write 5 promotional tweets",
      "created_at": "2024-11-05T12:30:00Z"
    }
  ]
} 

New Folder

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

Parameters

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

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

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"
} 

List Users

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

Parameters

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

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"
} 

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.

Parameters

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

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

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
} 

Enterprise feature Only available to select enterprise accounts. Please upgrade your contract to include Webhooks by contacting our Enterprise sales team.

Create webhook

Our API supports webhooks to notify your application of specific events in real-time. This allows you to build integrations that react immediately to changes in our system. You must be an Admin on the account to setup webhooks.

Verifying Webhook Signatures

When you set a webhook secret, we generate a signature for each payload using HMAC-SHA256. This signature is sent in the X-Webhook-Signature header

Subscribe to events

When you create a webhook, you specify a URL and subscribe to event types. When an event that your webhook is subscribed to occurs, Sonix will send an HTTP request with data about the event to the URL that you specified. If your server is set up to listen for webhook deliveries at that URL, it can take action when it receives one.

Events