Skip to main content

Create a transcription

Learn how to create your first audio transcription with the Klangio API.

1. Model Selection​

For demonstration purpose we will use the generalized universal model to process the audio file. To provide optimal transcription results, it is highly recommended to read the Model Selection for Transcription Jobs in Advanced Usage.

2. Decide on the Output Formats​

The Klangio AI can generate Transcription jobs results in various formats, based on your needs. Results will be available for 14 days. Make sure to fetch and store them in your system or else there won't be any option to recover them, besides making a new request.

warning

Use as little output formats as possible. Multiple formats may inflict additional quota costs for a transcription job.

3. Request via API​

Create a transcription via Klangio API:

warning

Depending on your current subscription billing status, calls to the /transcription-endpoint may inflict quota costs. For a testing account a demo transcription is created by default.

  import requests

  API_KEY = 'YOUR_KLANGIO_API_KEY'


  audio_file = open('{YOUR_FILE_NAME}', 'rb')

  query_parameters = {
    'model': 'guitar', # required
    'title': 'Awesome recording', # optional
    'composer': 'John Doe', # optional
    'webhook_url': '{YOUR_WEBHOOK_ENDPOINT_URL}' # optional, but recommended
  }

  multipart_params = {
    'file': audio_file,
    'outputs': ['midi', 'pdf', 'gp5']
  }

  resp = requests.post(
    'https://api.klang.io/transcription',
    headers={
      'kl-api-key': API_KEY
    },
    params=query_parameters,
    files=multipart_params
    )
  
  if resp.status_code == 200:
    print(resp.json())
    # {
    #  'job_id': 'SOME_JOB_ID', 
    #  'creation_date': '2023-01-01', 
    #  'deletion_date': '2023-02-01',
    #  'gen_xml': true,
    #  'gen_midi': true,
    #  'gen_midi_unq': false,
    #  'gen_gp5': false,
    #  'status_endpoint_url': 'https://api.klang.io/job/{SOME_JOB_ID}/status'
    # }

4. Check Job Status​

  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
    })
  print(resp)
  # {"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

Sequence Diagram: TBD

Use WebHooks​

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

5. Get the Output Data​

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

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(res.content)