Query Data
There are various ways to get detailed data about a production, preset, external services, output file formats and the user account.
- Query the status of a production:
https://auphonic.com/api/production/{uuid}/status.jsonReturns the status code and status string of a production,
{uuid}is the UUID of the production you want to query.Warning
If you have to query the status of a production very often, please use Webhooks instead!
- Get all details about a specific production/preset:
https://auphonic.com/api/{preset|production}/{uuid}.jsonHere
{uuid}is the UUID of the preset/production you want to query and{preset|production}should be either preset or production.- Get details about all productions/presets of a user:
https://auphonic.com/api/{presets|productions}.json- Get details about all external services of a user:
https://auphonic.com/api/services.jsonSee example Query External Services.
- Get all supported external service types:
https://auphonic.com/api/info/service_types.jsonSee example Query Service Types.
- Get all supported audio algorithms:
https://auphonic.com/api/info/algorithms.jsonSee example Query Audio Algorithms.
- Get all supported output file formats:
https://auphonic.com/api/info/output_files.jsonSee example Query Output Formats.
- Get available files on an external service:
https://auphonic.com/api/service/{uuid}/ls.jsonReturns a list of all supported audio and video files on the external service with the UUID
{uuid}.
- Get all possible status codes of an audio production:
https://auphonic.com/api/info/production_status.jsonReturns a dictionary with status codes and names.
- Get information about the user account:
https://auphonic.com/api/user.jsonReturns information about the current user.
- Get all info calls in a single request:
https://auphonic.com/api/info.json- Return the results of the following info calls in a single request:
https://auphonic.com/api/info/service_types.jsonhttps://auphonic.com/api/info/algorithms.jsonhttps://auphonic.com/api/info/output_files.jsonhttps://auphonic.com/api/info/production_status.json
Details about a Production
Warning
If you have to query the status of a production very often, please use Webhooks instead!
curl https://auphonic.com/api/production/{uuid}.json -H "Authorization: bearer {api_key}"
returns the following details:
{
"status_code": 200,
"form_errors": {},
"error_code": null,
"error_message": "",
"data": {
"status": 3,
"status_string": "Done",
"chapters": [
{
"title": "First Chapter Name",
"url": "https://auphonic.com",
"image": null,
"start": "00:00:10",
"start_sec": 10.0,
"start_output": "00:00:25.372",
"start_output_sec": 25.372585
},
{
"title": "Second Chapter",
"url": "",
"image": "https://auphonic.com/api/download/audio-upload/X2bUTQ8z888YaKukkU6vfJ/chapter1.png",
"start": "00:02:18",
"start_sec": 138.0,
"start_output": "00:02:33.372",
"start_output_sec": 153.372585
}
],
"outgoing_services": [
{
"display_name": "Georg Holzmann",
"type": "dropbox",
"uuid": "UC6aoChNZNt7KYZNxJTgUn",
"email": "georg@bla.com",
"transfer_success": true,
"error_message": "",
"incoming": true,
"outgoing": true,
"result_page": "https://www.dropbox.com/home/Apps/auphonic/auphonic-results",
"result_urls": []
},
{
"display_name": "My big FTP server",
"path": "my_mirror/",
"host": "ftp.auphonic.com",
"type": "ftp",
"uuid": "r6MSycBwyeWFAJYqUKtGeX",
"port": 21,
"base_url": "http://auphonic.com/myfiles/",
"transfer_success": true,
"error_message": "",
"incoming": true,
"outgoing": true,
"result_page": null,
"result_urls": [
"http://auphonic.com/myfiles/my_filename.mp3",
"http://auphonic.com/myfiles/my_vorbis_file.ogg"
]
},
{
"outgoing": true,
"sharing": "public",
"display_name": "auphonic-acc",
"uuid": "Asu5PxueRRxtqfZhe7zdia",
"track_type": "other",
"error_message": "",
"downloadable": false,
"incoming": true,
"type": "soundcloud",
"transfer_success": true,
"result_page": "http://soundcloud.com/auphonic-acc/auphonic-api-test",
"result_urls": []
},
{
"category": "Comedy",
"outgoing": true,
"display_name": "auphonic videos",
"uuid": "esSfxaPe6U2bNX2K9GGMeT",
"error_message": "",
"privacy": "private",
"incoming": false,
"type": "youtube",
"transfer_success": true,
"result_page": "https://www.youtube.com/watch?v=Ua11Jj44ydE",
"result_urls": []
}
],
"uuid": "X2bUTQ8z888YaKukkU6vfJ",
"output_basename": "production-filename",
"output_files": [
{
"format": "mp3",
"ending": "mp3",
"suffix": ""
"filename": "my_filename.mp3",
"split_on_chapters": false,
"bitrate": 96,
"mono_mixdown": false,
"size": 803635,
"size_string": "784.8 KB",
"download_url": "https://auphonic.com/api/download/audio-result/X2bUTQ8z888YaKukkU6vfJ/my_filename.mp3",
"outgoing_services": [],
"checksum": "1bcb74117e73d00dc469d4364625468e",
},
{
"format": "vorbis",
"ending": "ogg",
"suffix": "",
"filename": "my_vorbis_file.ogg",
"split_on_chapters": false,
"bitrate": 40,
"mono_mixdown": true
"size": 334848,
"size_string": "327.0 KB",
"download_url": "https://auphonic.com/api/download/audio-result/X2bUTQ8z888YaKukkU6vfJ/my_vorbis_file.ogg",
"outgoing_services": [],
"checksum": "f605a92ac8a833c75e99ec61613256ce"
}
],
"image": "https://auphonic.com/api/download/audio-upload/X2bUTQ8z888YaKukkU6vfJ/your-cover-image.png",
"thumbnail": "https://auphonic.com/api/download/audio-upload/X2bUTQ8z888YaKukkU6vfJ/thumbnail.jpg",
"waveform_image": "https://auphonic.com/api/download/audio-result/X2bUTQ8z888YaKukkU6vfJ/waveform.png",
"creation_time": "2012-05-15T13:10:47.105",
"change_time": "2012-05-15T13:10:47.105",
"algorithms": {
"filtering": true,
"normloudness": true,
"denoise": true,
"leveler": false,
"loudnesstarget": -23,
"denoiseamount": 12
},
"service": "UC6aoChNZNt7KYZNxJTgUn",
"input_file": "bbc4.mp3",
"length": 65.430,
"length_timestring": "00:01:05.430",
"channels": 2,
"samplerate": 44100,
"bitrate": 196.0,
"format": "mp3",
"has_video": false,
"cut_start": 0.0,
"cut_end": 0.0,
"metadata": {
"album": "some album",
"subtitle": "Our subtitle",
"summary": "Our very long summary.",
"license": "Creative Commons Attribution 3.0 Unported",
"artist": "auphonic",
"track": "1",
"title": "Auphonic API Test",
"publisher": "auphonic",
"url": "https://auphonic.com",
"license_url": "http://creativecommons.org/licenses/by/3.0/",
"year": "2012",
"genre": "Podcast",
"append_chapters": false,
"tags": ["query details", "auphonic", "production"],
"location": {
"latitude": "47.070",
"longitude": "15.439"
}
},
"multi_input_files": [
{
"input_channels": 2,
"service": "bXZVoQYenncgViYYtU4g2T",
"input_samplerate": 48000,
"input_file": "intro.opus",
"input_bitrate": 143.12,
"input_filetype": "libopus",
"type": "intro",
"id": "",
"offset": 0,
"input_length": 15.3725850340136
},
{
"input_channels": 1,
"service": "8HMJsgQi9MV26TEYmHKmdm",
"input_samplerate": 44100,
"input_file": "outro.mp3",
"input_bitrate": 196.0,
"input_filetype": "mp3",
"type": "outro",
"id": "",
"offset": 0,
"input_length": 15.3725850340136
}
],
"start_allowed": true,
"change_allowed": true,
"status_page": "https://auphonic.com/engine/status/X2bUTQ8z888YaKukkU6vfJ",
"edit_page": "https://auphonic.com/engine/upload/edit/X2bUTQ8z888YaKukkU6vfJ",
"error_status": null,
"error_message": "",
"warning_status": null,
"warning_message": "",
"webhook": "http://example.com/callback/",
"is_multitrack": false,
"used_credits": {
"onetime": 0.04,
"recurring": 0.01,
"combined": 0.05
},
"speech_recognition": {
"keywords": ["Auphonic", "Loudness", "Audio Restoration"],
"type": "google",
"uuid": "kw7q5CHaGSLgduyMhc9j9K",
"language": "en-US"
},
"statistics": {
"levels": {
"input": {
"lra": [19.23, "LU"],
"noise_level": [-49.63, "dB"],
"max_momentary": [-10.75, "LUFS"],
"signal_level": [-23.51, "dB"],
"snr": [26.12, "dB"],
"max_shortterm": [-12.71, "LUFS"],
"loudness": [-17.71, "LUFS"]
},
"output": {
"lra": [3.0, "LU"],
"max_shortterm": [-14.3, "LUFS"],
"max_momentary": [-11.02, "LUFS"],
"gain_min": [-2.5, "dB"],
"peak": [-1.0, "dBTP"],
"gain_mean": [7.9, "dB"],
"loudness": [-16.0, "LUFS"],
"gain_max": [21.04, "dB"]
}
},
"music_speech": [
{"label": "speech", "start": "00:00:00.000", "start_sec": 0.0, "stop": "00:01:13.440", "stop_sec": 73.44},
{"label": "music", "start": "00:01:13.440", "start_sec": 73.44, "stop": "00:01:35.520", "stop_sec": 95.52},
{"label": "speech", "start": "00:01:35.520", "start_sec": 95.52, "stop": "00:01:59.223", "stop_sec": 119.224}
],
"noise_hum_reduction": [
{"denoise": -12, "dehum": false, "start": "00:00:00.000", "start_sec": 0.0, "stop": "00:01:01.528", "stop_sec": 61.528},
{"denoise": false, "dehum": false, "start": "00:01:01.528", "start_sec": 61.528, "stop": "00:01:59.223", "stop_sec": 119.224}
]
"cuts": [
{
"name": "filler",
"length_s": 138.2994920634942,
"count": 338, "percent": 5.87,
"times_s": [
[10.21, 10.751], [11.4034, 11.6034], [13.9884, 14.3694], [18.7374, 19.7594], ...
]
},
{
"name": "silence",
"length_s": 131.46175125332218,
"count": 184, "percent": 5.58,
"times_s": [
[0.343, 1.9615], [6.4105, 6.9848], [15.2687, 16.3112], ...
]
}
]
}
}
}
- Infos about the parameters:
status,status_string: current production status, see Query Production Status for status codesuuid: the UUID of the productionoutput_basename: basename for output file, see Setting Filenamesimage: cover image of the production (original resolution)thumbnail: thumbnail of the cover image (200x200)waveform_image: image of the final waveform (as used by the audio player on the auphonic status page)creation_time: production creation time (UTC)change_time: indicates the time of the last change made by the auphonic system (UTC)service: the service UUID for incoming file transfer or null for file upload or HTTP incominginput_file: input audio or video filenamelength: output audio length in seconds - IMPORTANT: if you have intro, outro or insert files, they are included in this length!length_timestring: output audio length in HH:MM:SS.mmm - IMPORTANT: if you have intro, outro or insert files, they are included in this length!channels: channels of input audiosamplerate: input audio sampleratebitrate: input audio bitrateformat: input audio file format (mp3, vorbis, aac, …)has_video: true of input file contains a video trackcut_start: time in sec to cut from the start of an audio file, see Cut Start/End of Audio Filescut_end: time in sec to cut from the end of an audio file, see Cut Start/End of Audio Filesstart_allowed: indicates if it’s allowed to start the productionchange_allowed: indicates if it’s allowed to change the production (e.g. not during audio processing)status_page: URL to the auphonic status web pageedit_page: URL to the auphonic edit web pageerror_message: an error message, if an error occurred while processingerror_status: the processing status, where an error occurred (seestatus)warning_message: a warning message, if a warning occurred while processingwarning_status: the processing status, where a warning occurred (seestatus)is_multitrack: indicates if this production is a multitrack production, see also API Response of Multitrack Productionsmulti_input_files: shows information about multiple input files (intro and outro) using the same fields as for the main input filechapters:title: the title of the current chapterurl: the chapter URL (enhanced podcasts)image: the chapter image as downloadable URI (enhanced podcasts)start: start of the current chapter as timestring (in HH:MM:SS.mmm), relative to the main input file - IMPORTANT: if you have an additional intro, inserts or usecut_start, its length is NOT included here!start_sec: start of the current chapter in seconds, relative to the main input file - IMPORTANT: if you have an additional intro, inserts or usecut_start, its length is NOT included here!start_output: start of the current chapter as timestring (in HH:MM:SS.mmm), relative to output files - IMPORTANT: if you have an additional intro, inserts or usecut_start, its length is included here!start_output_sec: start of the current chapter in seconds, relative to output files - IMPORTANT: if you have an additional intro, inserts or usecut_start, its length is included here!
Warning
You must use
start_outputorstart_output_secto correctly display chapter marks to an end user!outgoing_services:transfer_success: true if the file transfer was successfulerror_message: error message, if the file transfer was not successfulresult_page: web page generated by an external service, e.g. the YouTube, SoundCloud or archive.org pageresult_urls: URLs of the copied output files on external servers. For FTP/SFTP this only works, if you set a base_url!
output_files:size: size of the output file in bytessize_string: human readable string of file sizedownload_url: HTTP URL on auphonic servers to download the result fileoutgoing_services: referenced outgoing file transfers, see Reference Output Files for Outgoing File Transferschecksum: 128 bit MD5 checksum of the output file
webhook: URL on your server (HTTP POST callback) which will be called after processing to automate further steps, for details see Webhooksused_credits: used recurring, one-time and combined credits for this production in hours, for details see Pricingstatistics:levels: processing statistics about audio levels, loudness, gain changes, peaks etc. of input and output filesmusic_speech: lists music and speech segments within the audio file (> 20 sec)noise_hum_reduction: lists segments with noise and/or hum reductioncuts: exact cut times for silence and fillerword cutting
For more details about audio processing statistics see Audio Processing Statistics Explained!
Details about a Preset
curl https://auphonic.com/api/preset/{uuid}.json -H "Authorization: bearer {api_key}"
returns details about a preset:
{
"status_code": 200,
"form_errors": {},
"error_code": null,
"error_message": "",
"data": {
"output_files": [
{
"format": "mp3",
"ending": "mp3",
"suffix": ""
"filename": "",
"split_on_chapters": false,
"bitrate": 96,
"mono_mixdown": false
"size": None,
"size_string": "",
"download_url": None,
"outgoing_services": [],
"outgoing_service_urls": []
},
{
"format": "vorbis",
"ending": "ogg",
"suffix": "-small",
"filename": "",
"split_on_chapters": false,
"bitrate": 40,
"mono_mixdown": true
"size": None,
"size_string": "",
"download_url": None,
"outgoing_services": [],
"outgoing_service_urls": []
}
],
"output_basename": "",
"outgoing_services": [
{
"display_name": "Georg Holzmann",
"type": "dropbox",
"uuid": "UC6aoChNZNt7KYZNxJTgUn",
"email": "georg@bla.com",
"transfer_success": false,
"error_message": ""
"incoming": true,
"outgoing": true,
"result_page": null,
"result_urls": []
},
{
"display_name": "SFTP bla.com",
"path": "/home/data/my_auphonic_dir/",
"host": "bla.com",
"type": "sftp",
"uuid": "r6MSycBwyeWFAJYqUKtGeX",
"port": 22,
"base_url": "",
"transfer_success": false,
"error_message": ""
"incoming": true,
"outgoing": true,
"result_page": null,
"result_urls": []
}
],
"uuid": "YnzGYccbzEj5MQwiSGfrqC",
"algorithms": {
"filtering": true,
"normloudness": true,
"denoise": false,
"leveler": true,
"loudnesstarget": -23,
"denoiseamount": 12
},
"image": "https://auphonic.com/api/download/preset/YnzGYccbzEj5MQwiSGfrqC/my-preset-image.png",
"creation_time": "2012-05-14T19:27:34.833",
"thumbnail": "https://auphonic.com/api/download/preset/YnzGYccbzEj5MQwiSGfrqC/thumbnail.jpg",
"preset_name": "New Api Preset",
"metadata": {
"album": "Auphonic Album",
"subtitle": "",
"license": "Creative Commons Attribution 3.0 Unported",
"summary": "",
"artist": "Auphonic",
"track": "",
"title": "",
"publisher": "Auphonic",
"url": "https://auphonic.com",
"license_url": "http://creativecommons.org/licenses/by/3.0/",
"year": "2012",
"genre": "Podcast",
"append_chapters": false,
"tags": ["query details", "auphonic", "preset"],
"location": {
"latitude": "47.070",
"longitude": "15.439"
}
},
"multi_input_files": [
{
"input_channels": 2,
"service": "bXZVoQYenncgViYYtU4g2T",
"input_samplerate": 48000,
"input_file": "intro.opus",
"input_bitrate": 143.12,
"input_filetype": "libopus",
"type": "intro",
"input_length": 15.3725850340136
},
{
"input_channels": 1,
"service": "8HMJsgQi9MV26TEYmHKmdm",
"input_samplerate": 44100,
"input_file": "outro.mp3",
"input_bitrate": 196.0,
"input_filetype": "mp3",
"type": "outro",
"input_length": 15.3725850340136
}
],
"speech_recognition": {
"keywords": ["Auphonic", "Loudness", "Audio Restoration"],
"type": "google",
"uuid": "kw7q5CHaGSLgduyMhc9j9K",
"language": "en-US"
},
"is_multitrack": false,
"webhook": "http://example.com/callback/"
}
}
List all Productions and Presets
The following command returns details about all productions/presets of a single user:
curl https://auphonic.com/api/{productions|presets}.json -H "Authorization: bearer {api_key}"
This query can get very expensive in case you have lots of productions. Please restrict the response with the following parameters.
- Parameters and limits:
limit: Limits the number of returned productions or presets. If you are not usinguuids_onlyorminimal_data, the limit is restricted to 10! If nooffsetis given, the list starts with the latest entry (zero offset).offset: List starts at the defined number (index starts at zero!), counting from the latest entry.uuids_only: only return UUIDs of productions/presets, see Query UUIDs only.minimal_data: only minimal data for each production/preset is retunred, see Query Minimal Production/Preset Data.
For example:
curl https://auphonic.com/api/productions.json?limit=10 -H "Authorization: bearer {api_key}"
returns the 10 latest productions and:
curl https://auphonic.com/api/productions.json?limit=10&offset=10 -H "Authorization: bearer {api_key}"
returns the next 10 elements.
The response contains now a list with details about all productions/presets, here an example with three presets:
{
"status_code": 200,
"form_errors": {},
"error_code": null,
"error_message": "",
"data": [
{
"output_files": [
{
...
},
...
"preset_name": "My Preset 1",
"metadata": {
"album": "Some Album",
...
}
},
{
"output_files": [],
"outgoing_services": [],
"uuid": "KtuzTdGoGcMgFfGM8iAcTK",
"algorithms": {
"filtering": false,
"normloudness": false,
"denoise": false,
"leveler": false,
"loudnesstarget": -23,
},
...
"preset_name": "My Preset 2",
...
},
{
...
"uuid": "9KN6czHvcrVeYWex5aQz59",
...
"preset_name": "My Preset 3",
...
},
...
]
}
Query UUIDs only
If you only want to get the UUIDs of all available productions or presets, please
add the parameter uuids_only=1 to the request:
curl https://auphonic.com/api/productions.json?uuids_only=1 -H "Authorization: bearer {api_key}"
This results in:
{
"status_code": 200,
"form_errors": {},
"error_code": null,
"error_message": "",
"data": [
"gTZa9CPNqDrSTeufve2A6D",
"Svia3HLsrcHAatUX7bYwsN",
"dRFtYcig2j8jhcKsQnPNFY",
"V4N3eJJXny587difp2Wnbg",
"gvLm2meH3YyoLuhCoSJ68W",
...
]
}
Query Minimal Production/Preset Data
Sometimes not all production/preset details are necessary if you want to show a user her/his available productions/presets in a third party application. Otherwise the transferred data (audio stats of lots of productions etc.) might become very big.
Please add the parameter minimal_data=1 to a request to get only some important
data of productions (status, uuid, title, output files, etc.):
curl https://auphonic.com/api/productions.json?minimal_data=1 -H "Authorization: bearer {api_key}"
This results in:
{
"status_code": 200,
"form_errors": {},
"error_code": null,
"error_message": "",
"data": [
{
"status": 3,
"uuid": "VorWAbWZLrrLL3pS4BG8od",
"is_multitrack": false,
"creation_time": "2017-11-09T15:42:28.931Z",
"metadata": {
"title": "auphonic-dehum"
},
"output_files": [
{
"format": "mp3",
"bitrate": 112,
"download_url": "https://auphonic.com/api/download/audio-result/VorWAbWZLrrLL3pS4BG8od/auphonic-dehum.mp3",
"filename": "auphonic-dehum.mp3"
}
]
},
...
]
}
It’s also possible to query presets with the parameter minimal_data=1, which results in:
{
"status_code": 200,
"form_errors": {},
"error_code": null,
"error_message": "",
"data": [
{
"preset_name": "My first preset",
"creation_time": "2012-02-07T10:13:41.330Z",
"uuid": "pmefeNCzkyT4TbRbDmoCDf",
"is_multitrack": false,
"metadata": {
"title": "test first preset"
}
},
{
"preset_name": "preset 2",
"creation_time": "2012-09-07T09:21:46.188Z",
"uuid": "UqKoxERcsFGaR4eLvmytcD",
"is_multitrack": false,
"metadata": {
"title": "my next preset"
}
},
...
]
}
List Files on an External Service
curl https://auphonic.com/api/service/{uuid}/ls.json -H "Authorization: bearer {api_key}"
returns a list of all supported audio and video files on the external
service with the UUID {uuid}:
{
"status_code": 200,
"form_errors": {},
"error_code": null,
"error_message": "",
"data": ["my_audio.mp3", "my_video.avi", "next_file.ogg"]
}
Information about a User Account
curl https://auphonic.com/api/user.json -H "Authorization: bearer {api_key}"
returns information and settings of an Auphonic user account:
{
"status_code": 200,
"form_errors": {},
"error_code": null,
"error_message": "",
"data": {
"username": "testuser",
"user_id": "6ba197a14abb5eee55713fef66feaf71",
"date_joined": "2013-02-28T21:20:03Z",
"email": "grh@auphonic.com",
"credits": 2.87309201310154,
"onetime_credits": 1.0,
"recurring_credits": 1.87309201310154,
"recharge_date": "2014-05-28T21:20:03Z",
"recharge_recurring_credits": 2.0,
"notification_email": true,
"error_email": true,
"warning_email": true,
"low_credits_email": false,
"low_credits_threshold": 10
}
}
The parameter user_id is a unique identifier for the specific user and
will also stay the same, when the username or email changes.
Available credits are listed in credits (in hours), which is the sum
of available onetime_credits and recurring_credits. Recurring credits
are recharged on recharge_date to recharge_recurring_credits.
Download Result Media Files
An Auphonic production will produce multiple result files (audio/video output files, input files, cover images, waveform images, chapter images, etc.).
All result files are listed with correct download URLs in the API response of a production:
{
...
"output_files": [
{
"format": "mp3",
"download_url": "https://auphonic.com/api/download/audio-result/J6BnqA8dbf4y5EmBzYzcMk/auphonic_intro.mp3",
...
},
{
"format": "chaps",
"download_url": "https://auphonic.com/api/download/audio-result/J6BnqA8dbf4y5EmBzYzcMk/auphonic_intro.chapters.txt",
...
}
],
"waveform_image": "https://auphonic.com/api/download/audio-result/J6BnqA8dbf4y5EmBzYzcMk/waveform.png",
...
}
If you use HTTP Basic Authentication, you can just download these files using your Auphonic user credentials:
curl https://auphonic.com/api/download/audio-result/J6BnqA8dbf4y5EmBzYzcMk/auphonic_intro.mp3 -H "Authorization: bearer {api_key}"
If you use OAuth 2.0 Authentication or API Key Authentication, you have to provide your access token or API Key as a GET parameter:
curl https://auphonic.com/api/download/audio-result/J6BnqA8dbf4y5EmBzYzcMk/auphonic_intro.mp3?bearer_token={your_access_token}