JSON API: Start Productions using Presets

Our JSON-based API can be used for complex workflows and detailed control.

The examples on this page show how it’s possible to start a production by referencing an existing preset and how to add chapter marks. More in-depth examples without presets are on the next page.

Multiple steps might be necessary to create and start an audio post production:

Step 1:: Create a production and reference the preset you want to use.
When the production does not involve a local file upload, you can start the production already in Step 1.
Step 2 (optional):: Upload your local input file and add it to the newly created production.
Step 3 (optional):: Start the audio post production on our servers.

Start a Production and Upload a Local File

Step 1: The following POST request creates a new Production and references an existing Preset:

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/productions.json \
    -H "Authorization: bearer {api_key}" \
    -d '{
            "preset": "ceigtvDv8jH6NaK52Z5eXH",
            "metadata": { "title": "My first Production" }
        }'

Parameters:

api_key: your Auphonic API Key, please see API Key Authentication, HTTP Basic Authentication and OAuth 2.0 Authentication
preset: UUID of the referenced preset, you can find it on the Preset Page
title: the title metadata tag of the production

The API URL to create productions is https://auphonic.com/api/productions.json - here the ending .json means, that the returned data will be in JSON format. It’s also possible to use https://auphonic.com/api/productions.xml if you prefer XML data output.

Note

It’s necessary to set the HTTP Content-Type header to JSON (using curl -H “Content-Type: application/json”)!

This first request returns JSON data containing the UUID of the newly created production:

{
    "status_code": 200,
    "form_errors": {},
    "error_code": null,
    "error_message": "",
    "data": {
        ...
        "uuid": "KKw7AxpLrDBQKLVnQCBtCh",
        ...
    }
}

Step 2: Using the production UUID, it’s possible to upload a local input file:

curl -X POST https://auphonic.com/api/production/KKw7AxpLrDBQKLVnQCBtCh/upload.json \
    -H "Authorization: bearer {api_key}" \
    -F "input_file=@/home/user/your_audio_file.mp3"

Parameters:

the UUID of the production is now included in the URL https://auphonic.com/api/production/{uuid}/upload.json
input_file: the local audio or video file you want to upload

Note

For uploading files, it’s necessary to encode your POST request in multipart/form-data, not JSON!

Step 3: Now we have all data to start the audio post production on the Auphonic servers, which can be done with:

curl -X POST https://auphonic.com/api/production/KKw7AxpLrDBQKLVnQCBtCh/start.json -H "Authorization: bearer {api_key}"

where the UUID of the production is again part of the URL https://auphonic.com/api/production/{uuid}/start.json.

Upload Files with HTTP

The local file upload step is not necessary, if you fetch a file from an external HTTP server as input audio:

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/productions.json \
    -H "Authorization: bearer {api_key}" \
    -d '{
            "preset": "ceigtvDv8jH6NaK52Z5eXH",
            "input_file": "https://your_server.com/somefile.mp3",
            "metadata": { "title": "My first HTTP Production" },
            "action": "start"
        }'

Here we reference an existing preset, set the URL of the input file using the parameter input_file and update the metadata title tag.

When the production does not involve a local file upload, it can be created and started in one go by adding "action": "start" as a parameter to the request. Omit the action parameter to just save the production without starting it.

Upload Files with External Services (SFTP/FTP/Dropbox/etc.)

When fetching files from SFTP, FTP, Dropbox, Amazon S3, SoundCloud or other External Services, it’s necessary to reference the external service:

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/productions.json \
    -H "Authorization: bearer {api_key}" \
    -d '{
            "service": "pmefeNCzkyT4TbRbDmoCDf",
            "input_file": "my_dropbox_file.mp3",
            "preset": "ceigtvDv8jH6NaK52Z5eXH",
            "metadata": { "title": "My first Dropbox Production" },
            "action": "start"
        }'

Parameters:

service: the UUID of your registered external service (SFTP/FTP/Dropbox), see Services Page
input_file: the filename of the input file (e.g. on the Dropbox server, in the auphonic path)
preset: the UUID of the preset you want to use
action: can be start to start your production, or omit the action parameter to just save the production without starting it

Warning

For SoundCloud and Spreaker, you have to use the title for the field input_file. For Facebook please use the video ID (as shown on the SoundCloud/Spreaker/Facebook page or returned by List Files on an External Service)!

Adding Chapters

Create a new production with Chapter Marks:

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/productions.json \
    -H "Authorization: bearer {api_key}" \
    -d '{
            "preset": "ceigtvDv8jH6NaK52Z5eXH",
            "input_file": "http://your_server.com/somefile.mp3",
            "metadata": { "title": "My first Production with Chapters" },
            "chapters": [
                {"start": "00:00:00", "title": "Start Chapter", "url": "http://auphonic.com"},
                {"start": "00:02:18", "title": "Second Chapter"},
                {"start": "00:04:41", "title": "Chapter with Image from URL", "image": "https://auphonic.com/static/images/logo.png"},
                {"start": "00:05:41", "title": "Base64-encoded Chapter Image", "image": "/9j/4AAQEBAQEBAQEBAQEBAQE...E4fp2WCm0nHbX/9k"},
            ]
        }'

Chapters must be added to the chapters parameter, where start is the start time in HH:MM:ss[.mmm], title the title of the chapter and url is an URL with further information. You can also include the parameter image to add a chapter image. The image parameter must be a valid URL to a picture, or the image file itself encoded in base64 (without MIME-Type prefix, just the data).

Warning

Chapter mark start times must be relative to the main input file! If the production contains and additional intro, the length of this intro will be added to each chapter automatically!

Alternatively you can also reference a chapters file from a publicly available URL:

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/productions.json \
    -H "Authorization: bearer {api_key}" \
    -d '{
            "preset": "ceigtvDv8jH6NaK52Z5eXH",
            "input_file": "http://your_server.com/somefile.mp3",
            "metadata": { "title": "My first Production with Chapters" },
            "chapters": "http://your_server.com/chapters.txt"
        }'

Auphonic imports various chapter formats and marker file formats from audio editors, see How to Import Chapter Marks .