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 |
---|
English | en |
French | fr |
German | de |
Spanish | es |
Spanish & English | es-en |
Arabic | ar |
Armenian | hy |
Bashkir | ba |
Basque | eu |
Belarusian | be |
Bulgarian | bg |
Catalan | ca |
Croatian | hr |
Chinese (Cantonese) | yue |
Chinese (Mandarin) | cmn |
Czech | cs |
Danish | da |
Dutch | nl |
Estonian | et |
Finnish | fi |
Greek | el |
Hebrew | he |
Hindi | hi |
Hungarian | hu |
Indonesian | id |
Italian | it |
Japanese | ja |
Korean | ko |
Latvian | lv |
Lithuanian | lt |
Malay | ms |
Marathi | mr |
Mongolian | mn |
Norwegian | no |
Persian | fa |
Polish | pl |
Portuguese | pt |
Romanian | ro |
Russian | ru |
Serbian | sr |
Slovak | sk |
Slovenian | sl |
Swedish | sv |
Tamil | ta |
Thai | th |
Turkish | tr |
Uyghur | ug |
Ukrainian | uk |
Urdu | ur |
Vietnamese | vi |
Welsh | cy |
Error Codes
Below are all the possible error codes you may encounter using the API.
Error Code | Message | Description |
---|
400 | Invalid request | We do not know how to handle your request. Most likely your parameters are invalid or missing. Check the error message for details. |
401 | Invalid API Key | We do not recognize your API key. Check your API key and resubmit. |
402 | Payment Error | We had an issue processing your last payment. Please login to update payment information. |
403 | No API access | Your account is no longer subscribed to Sonix. Only paid subscribers can use the Sonix API. |
404 | Media file not found | Media file with associated ID cannot be found or is not associated with this account. |
409 | Media 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 files will be returned with the following attributes:
Field | Description |
---|
id | Unique identifier for the media file |
name | User given name for the media file. Defaults to the filename. |
duration | Duration in seconds |
language | Language code for the transcription. |
video | true or false depending on whether the given media is a video file or audio only. |
created_at | Time at which the media was uploaded. Measured in seconds since the Unix epoch. |
public_url | URL for shareable, read-only view of the transcript. |
custom_data | Set 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
|
HTTP Method | GET |
Endpoint | /v1/media |
Returns | Array of all media files in your account. Files are ordered by creation date, with the most recent file listed first. |
Parameters
Field | Default | Description |
---|
page | 1 | 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
}
HTTP Method | POST |
Endpoint | /v1/media |
Returns | Media JSON for the newly uploaded file. |
Parameters
Field | Required | Description |
---|
file | | The 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. |
language | | Language 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_text | | Existing 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 Method | POST |
Endpoint | /v1/media/<id> |
Returns | Media JSON for the corresponding id |
Parameters
These are in addition to the supported parameters for Submit New Media.
Field | Required | Description |
---|
multitrack | | For multitrack files, this must be set to true |
speaker_labels | | A 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"]'
HTTP Method | GET |
Endpoint | /v1/media/<id> |
Returns | Media 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"
}
}
HTTP Method | PUT |
Endpoint | /v1/media/<media id> |
Returns | Updated Media JSON |
Parameters
Field | Description |
---|
name | New name for the media file. |
custom_label | Apply a custom label to the file. |
folder_id | Move 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",
}
HTTP Method | DELETE |
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
Export a media file with either only highlights or all strikethroughs removed
HTTP Method | POST |
Endpoint | /v1/media/<media id>/media_exports |
Returns | ID and status of the media export |
Parameters
Field | Default | Description |
---|
media_format | mp3 | Can be either mp3 , wav , or mp4 . mp4 is only valid if the media file is video. |
remove_strikethrough | false | By 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'
}
HTTP Method | GET |
Endpoint | /v1/media_exports/<id> |
Returns | Media 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 Method | GET |
Endpoint | /v1/media/<media id>/transcript |
Returns | Text 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 Method | GET |
Endpoint (SRT) | /v1/media/<media id>/transcript.srt |
Endpoint (VTT) | /v1/media/<media id>/transcript.vtt |
Returns | Text of the transcript for the requested media file |
Parameters
Field | Default | Description |
---|
speaker_display | none | 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_captions | false | 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_lines | 1 | Whether the subtitles should be split over 1 or 2 lines. |
max_characters | 90 | Maximum number of characters a subtitle can contain. |
max_duration | 10 | 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 Method | GET |
Endpoint | /v1/media/<media id>/transcript.json |
Returns | Transcript 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 Method | PUT |
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 Method | PUT |
Endpoint | /v1/media/<media id>/transcript/split |
Returns | Updated transcript in JSON format. |
Parameters
Field | Default | Description |
---|
subtitle_lines | 1 | Whether the subtitles should be split over 1 or 2 lines. |
max_characters | 45 | Maximum number of characters a subtitle can contain. |
max_duration | 10 | Maximum duration, in seconds, a subtitle should cover. |
max_cps | 12 | 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 Method | POST |
Endpoint | /v1/media/<media id>/translations |
Returns | The 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 Method | GET |
Endpoint | /v1/media/<media id>/translations/<language> |
Returns | The 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 Method | POST |
Endpoint | /v1/media/<media id>/video_burn_ins |
Returns | The ID and status of the burn in |
Parameters
All parameters are optional.
Field | Default | Description |
---|
language | source 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. |
font | Arial | 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_size | 16 | Font size for subtitles. Can be anything from 10 through 42. |
font_color | #FFFFFF | Font color for subtitles. |
bold | false | Whether text should be bold or not |
italic | false | Whether text should be italic or not |
h_align | center | How the text should be aligned horizontally. Can be either center , right , or left |
v_align | bottom | How the text should be aligned vertically. Can be either top , middle , or bottom |
border_style | wrap | How the background of the subtitles are styled. Can be none , outline , wrap , or full |
border_color | #000000 | Color for border around subtitle text |
ratio | original | Aspect ratio for output video. Options are original , 1:1 , 9:16 , 16:9 , 5:4 , or 4:5 |
export_position | fit | How the video should be scaled to fit the aspect ratio. fit to ensure the entire video fits within the frame, or fill the 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 Method | GET |
Endpoint | /v1/video_burn_ins/<video_export_id> |
Returns | The 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 Method | POST |
Endpoint | /v1/media/<media id>/summarizations |
Returns | The ID and status of the summarization |
Parameters
Field | Required | Description |
---|
prompt | | The 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 Method | GET |
Endpoint | /v1/summarizations/<summarization_id> |
Returns | The 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."}
Batch Summarizations
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.
HTTP Method | POST |
Endpoint | /v1/folders/<folder_id>/batch_summarizations |
Returns | The ID and status of the batch summarization |
Parameters
Field | Required | Description |
---|
prompt | | The prompt used for summarization. For example "Summarize in 10 sentences", "Create a summary in German", or "Write 5 promotional tweets for each file" |
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
Status Code | Description |
---|
403 | Insufficient credit for batch processing |
404 | Folder not found |
422 | Folder is too large for batch processing (>60 hours) |
Get Batch Summarization
HTTP Method | GET |
Endpoint | /v1/batch_summarizations/<batch_summarization_id> |
Returns | The status and completed summaries for the 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
HTTP Method | GET |
Endpoint | /v1/folders/<folder_id>/batch_summarizations |
Returns | A list of batch summarizations associated with the folder |
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"
}
]
}
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 Method | POST |
Endpoint | /v1/media/folders |
Returns | The folder attributes |
Parameters
Field | Required | Description |
---|
name | | Name of the folder |
parent_folder | | ID of parent folder. If left blank, folder will be placed in your root folder |
access_control | | Defaults to interal . Can also be exernal or restricted . |
restricted_users | | If 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 Method | GET |
Endpoint | /v1/folders |
Returns | Array 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 Method | PUT |
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 Method | GET |
Endpoint | /v1/users |
Returns | Array 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 Method | POST |
Endpoint | /v1/users |
Returns | New user that has been created |
Parameters
Field | Required | Description |
---|
name | | Name of the user |
email | | Email of the user |
role | | Role 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 Method | PUT |
Endpoint | /v1/users/<user id> |
Returns | Updated 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 Method | POST |
Endpoint | /v1/media/<id>/shares |
Returns | The email and permissions for the user |
Parameters
Field | Required | Description |
---|
email | | Email of the person to share with. |
can_edit | | Whether the user can edit or the transcript is read-only. Must be true or false . Default is false . |
notes | | Additional 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 Method | GET |
Endpoint | /v1/media/<media id>/shares |
Returns | Array 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 Method | DELETE |
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
}
Webhooks
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.
Field | Description |
---|
Payload URL | The payload URL is the URL of the server that will receive the webhook POST requests. |
Secret (optional) | Setting a webhook secret allows you to ensure that POST requests sent to the Payload URL are from Sonix. When you set a secret, you'll receive the X-Webhook-Signature header in the webhook POST request. |
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
Event | Description |
---|
Transcription finished | When a transcript has been fully generated by Sonix |
Translation finished | When a translation has completed |
Label change | When a transcript's label has changed |
Folder change | When a transcript's folder has changed |