Query Data

There are various ways to get detailed data about a production, preset, external services, output file formats and the user account.

Get details about a specific production/preset:

https://auphonic.com/api/{preset|production}/{uuid}.json

Here {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.json

See example Query External Services.

Get all supported external service types:

https://auphonic.com/api/info/service_types.json

See example Query Service Types.

Get all supported audio algorithms:

https://auphonic.com/api/info/algorithms.json

See example Query Audio Algorithms.

Get all supported output file formats:

https://auphonic.com/api/info/output_files.json

See example Query Output Formats.

Get available files on an external service:

https://auphonic.com/api/service/{uuid}/ls.json

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

Returns a dictionary with status codes and names.

Get information about the user account:

https://auphonic.com/api/user.json

Returns 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.json
  • https://auphonic.com/api/info/algorithms.json
  • https://auphonic.com/api/info/output_files.json
  • https://auphonic.com/api/info/production_status.json

Details about a Production

curl https://auphonic.com/api/production/{uuid}.json -u username:password

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": {
            "hipfilter": 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}
            ]
        }
    }
}
Infos about the parameters:
  • status, status_string: current production status, see Query Production Status for status codes

  • uuid: the UUID of the production

  • output_basename: basename for output file, see Setting Filenames

  • image: 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 incoming

  • input_file: input audio or video filename

  • length: output audio length in seconds - IMPORTANT: if you have intro or outro files, they are included in this length!

  • length_timestring: output audio length in HH:MM:SS.mmm - IMPORTANT: if you have intro or outro files, they are included in this length!

  • channels: channels of input audio

  • samplerate: input audio samplerate

  • bitrate: input audio bitrate

  • format: input audio file format (mp3, vorbis, aac, ...)

  • has_video: true of input file contains a video track

  • cut_start: time in sec to cut from the start of an audio file, see Cut Start/End of Audio Files

  • cut_end: time in sec to cut from the end of an audio file, see Cut Start/End of Audio Files

  • start_allowed: indicates if it’s allowed to start the production

  • change_allowed: indicates if it’s allowed to change the production (e.g. not during audio processing)

  • status_page: URL to the auphonic status web page

  • edit_page: URL to the auphonic edit web page

  • error_message: an error message, if an error occurred while processing

  • error_status: the processing status, where an error occurred (see status)

  • warning_message: a warning message, if a warning occurred while processing

  • warning_status: the processing status, where a warning occurred (see status)

  • is_multitrack: indicates if this production is a multitrack production, see also API Response of Multitrack Productions

  • multi_input_files: shows information about multiple input files (intro and outro) using the same fields as for the main input file

  • chapters:

    • title: the title of the current chapter
    • url: 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 or use cut_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 or use cut_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 or use cut_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 or use cut_start, its length is included here!

    Warning

    You must use start_output or start_output_sec to correctly display chapter marks to an end user!

  • outgoing_services:

    • transfer_success: true if the file transfer was successful
    • error_message: error message, if the file transfer was not successful
    • result_page: web page generated by an external service, e.g. the YouTube, SoundCloud or archive.org page
    • result_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 bytes
    • size_string: human readable string of file size
    • download_url: HTTP URL on auphonic servers to download the result file
    • outgoing_services: referenced outgoing file transfers, see Reference Output Files for Outgoing File Transfers
    • checksum: 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 Webhooks

  • used_credits: used recurring, one-time and combined credits for this production in hours, for details see Pricing

  • statistics:

    • levels: processing statistics about audio levels, loudness, gain changes, peaks etc. of input and output files
    • music_speech: lists music and speech segments within the audio file (> 20 sec)
    • noise_hum_reduction: lists segments with noise and/or hum reduction

    For more details about audio processing statistics see Audio Processing Statistics Explained!

Details about a Preset

curl https://auphonic.com/api/preset/{uuid}.json -u username:password

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": {
            "hipfilter": 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 -u username:password
Furthermore it’s possible to limit the number of returned entries with the paramters limit and offset:
  • limit: Limits the number of returned entries. If only a limit is given, the list starts with the latest entry.
  • offset: List starts at the defined number (index starts at zero!), counting from the latest entry.

For example:

curl https://auphonic.com/api/productions.json?limit=10 -u username:password

returns the 10 latest productions and:

curl https://auphonic.com/api/productions.json?limit=10&offset=10 -u username:password

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": {
                "hipfilter": false,
                "normloudness": false,
                "denoise": false,
                "leveler": false,
                "loudnesstarget": -23,
            },
            ...
            "preset_name": "My Preset 2",
            ...
        },
        {
            ...
            "uuid": "9KN6czHvcrVeYWex5aQz59",
            ...
            "preset_name": "My Preset 3",
            ...
        },
        ...
    ]
}

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 -u username:password

This results in:

{
    "status_code": 200,
    "form_errors": {},
    "error_code": null,
    "error_message": "",
    "data": [
        "gTZa9CPNqDrSTeufve2A6D",
        "Svia3HLsrcHAatUX7bYwsN",
        "dRFtYcig2j8jhcKsQnPNFY",
        "V4N3eJJXny587difp2Wnbg",
        "gvLm2meH3YyoLuhCoSJ68W",
        ...
    ]
}

List Files on an External Service

curl https://auphonic.com/api/service/{uuid}/ls.json -u username:password

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 -u username:password

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 -u username:password

If you use OAuth 2.0 Authentication, you have to provide your access token as a GET parameter:

curl https://auphonic.com/api/download/audio-result/J6BnqA8dbf4y5EmBzYzcMk/auphonic_intro.mp3?bearer_token={your_access_token}