Basic Job Workflow

Learn all the basics on how to use the API to create different kind of jobs and how to get the result.

The Job Workflow

In general, creating a job and getting the result consists of the following steps:

1. Send new job request to our API
2. Check the job status (via request or webhook)
3. Get the result via request

Each type of job will have specific parameters and result formats. Check out the #Jobs chapter for the specific details.

1. New Job Request via API

Create a new job request via Klangio API:

warning

Depending on your current subscription billing status, creating a job may inflict quota costs. For a testing account a demo transcription is created by default.

tip

We recommend you to specify an endpoint url as the parameter webhook_url. We will send updates about the job status to your specified endpoint. (See step 2. Check Job Status)

(Make sure to check out the OpenApi Docs for all required and available parameters)

  import requests

  # use your KLANGIO API KEY
  API_KEY = 'YOUR_KLANGIO_API_KEY'

  # open your audio file
  audio_file = open('{YOUR_FILE_NAME}', 'rb')

  # set the parameters (these vary with type of job)
  query_parameters = {
    'model': 'universal',
    'webhook_url': '{YOUR_WEBHOOK_ENDPOINT_URL}' # optional, but recommended
  }

  # set the audio file in the multipart parameters
  multipart_params = {
    'file': audio_file,
  }

  # (only needed for transcription job)
  data_params = {
    'outputs': ['mxml']
  }

  # send a post request to our endpoints (the specific endpoint will change with the type of job)
  resp = requests.post(
    'https://api.klang.io/transcription',
    headers={
      'kl-api-key': API_KEY
    },
    params=query_parameters,
    data=data_params,
    files=multipart_params
    )
  
  # the response will contain information about the new job
  if resp.status_code == 200:
    print(resp.json())
    # {
    #  'job_id': 'SOME_JOB_ID', 
    #  'creation_date': '2023-01-01', 
    #  'deletion_date': '2023-02-01',
    #  'status_endpoint_url': 'https://api.klang.io/job/{SOME_JOB_ID}/status'
    # }

2. Check Job Status

While we offer the option to use polling to actively get updates on the job status, we highly recommend to utilize the optional webhook_url field when making job requests. We will send a notification as POST Request to the url specified as webhook when a job is finished.

Here is how you poll the status of a job:

  import requests

  API_KEY = 'YOUR_KLANGIO_API_KEY'

  resp = requests.get(
    'https://api.klang.io/job/{YOUR_JOB_ID}/status', 
    headers={
      'kl-api-key': API_KEY
    })
  if resp.status_code == 200:
    print(resp.json())
    # {"status": "IN_QUEUE"}

Possible Status Values:

• IN_QUEUE - job is waiting in queue for processing
• IN_PROGRESS - job is currently processed
• FAILED - processing of job was not possible and failed
• COMPLETED - processing of job was successful and result files can be fetched

The status response may include different error messages. See the chapter Error Descriptions for details on these error responses.

3. Get the result data

Once the job is in state COMPLETED or the webhook notification is received, you can fetch the results from the job/{job_id}/{format} endpoint.

Here is a list of all possible result formats.

Result format	Transcription	Source Separation	Chord Recognition	Chord Recognition Extended	Beat Tracking	Strum Recognition
json			✅	✅	✅	✅
xml (MusicXML)	✅
gp5 (Guitar Pro 5)	✅
midi	✅
midi_quant (quantized)	✅
pdf	✅
audio		✅

Here is an example python code snippet to fetch the xml of the transcription:

  import requests

  API_KEY = 'YOUR_KLANGIO_API_KEY'

  resp = requests.get(
    'https://api.klang.io/job/{YOUR_JOB_ID}/xml',
    headers={
      'kl-api-key': API_KEY
    })

  if resp.status_code == 200:
    with open('test.mxml', 'wb') as file:
      file.write(resp.content)

Workflow diagram