Quickstart

This document explains the complete process of creating a job and checking its status using the API provided by Gaudio Developers.
In this demo, we'll create a job to separate vocal and accompaniment elements from mixed audio using the GSEP-Music-HQ model.

Workflow

The diagram below shows the complete process of creating a job, periodically checking its status, and confirming until the task is completed.

request-api-diagram

Call the job creation API.
Repeatedly call the status check API with the returned jobId.
Download the result files once the task is completed.

Job Status

Jobs can have the following statuses:

Status	Description
`waiting`	The job has passed validation and entered the queue. Processing time may be longer if there are many jobs waiting in the queue.
`running`	The job is currently being processed. Processing time varies depending on the product, processing options, and input file.
`success`	The job has been completed successfully and results can be downloaded.
`failed`	An error occurred during job processing and it failed.

When the status is success, you can download the result files through the downloadUrl included in the response.

Step-by-Step Guide

Prerequisites

Authentication Information
- All requests require authentication using an API Key. For issuance and creation methods, please refer to the Authentication document.
Upload ID
- You need to upload the source audio file to the temporary upload server and receive an ID. For upload and ID issuance methods, please refer to File Upload.

1. Create a job

Create a job using the uploadId of the uploaded file.

curl -X POST https://restapi.gaudiolab.io/developers/api/v1/gsep_music_hq_v1/jobs \
  -H "x-ga-apikey: {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
        "audioUploadId": "{UPLOAD_ID}",
        "type": "vocal,drum"
      }'

Response on success

{
  'resultCode': 1000,
  'resultData': {
    'jobId': 'aaffd346-74fc-11f0-8de9-0242ac120002'
  }
}

2. Get a job

Check the current status of the job using the Job ID.

curl -X GET "https://restapi.gaudiolab.io/developers/api/v1/gsep_music_hq_v1/jobs/{JOB_ID}" \
  -H 'x-ga-apikey: {API_KEY}'

Response on success

{
  'resultCode': 1000,
  'resultData': {
    'jobId': 'aaffd346-74fc-11f0-8de9-0242ac120002',
    'status': 'success',
    'expireAt': '2025-09-01T12:00:00Z',
    'downloadUrl': {
      'vocal': {
        'mp3': 'https://cdn_url/input-file_vocal.mp3',
        'wav': 'https://cdn_url/input-file_vocal.wav'
      },
      'drum': {
        'mp3': 'https://cdn_url/input-file_drum.mp3',
        'wav': 'https://cdn_url/input-file_drum.wav'
      },
      'others': {
        'mp3': 'https://cdn_url/input-file_others.mp3',
        'wav': 'https://cdn_url/input-file_others.wav'
      }
    }
  }
}

If the status is not 'success' or 'failed', it is still being processed.
If you make repeated requests too frequently, you may hit rate limiting. (For detailed information, please refer to the Rate Limiting document.)

Example Code

Below is a Python example that includes the entire process.

import os
import requests
import time
import json

SLEEP_INTERVAL = 10
SERVER = "https://restapi.gaudiolab.io/developers/api"

API_CREATE_UPLOAD = "/v1/files/upload-multipart/create"
API_COMPLETE_UPLOAD = "/v1/files/upload-multipart/complete"
API_CREATE_JOB = "/v1/gsep_music_hq_v1/jobs"
API_JOB_STATUS = "/v1/gsep_music_hq_v1/jobs/{}"

API_KEY = 'api_key_here'
INPUT_FILE = './test_file.wav'


def send_request(method, api, payload):
    headers = {
        'x-ga-apikey': API_KEY
    }
    if method == "POST":
        return requests.post(SERVER + api, headers=headers, json=payload)
    elif method == "GET":
        return requests.get(SERVER + api, headers=headers)
    else:
        raise ValueError(f"Invalid method: {method}")

def read_in_chunks(file_object, chunk_size):
    while True:
        data = file_object.read(chunk_size)
        if not data:
            break
        yield data


def main():
    print("\n[STEP] Create Upload URL")
    print("-" * 40)
    file_size = os.path.getsize(INPUT_FILE)
    payload = {
        'fileName': os.path.basename(INPUT_FILE),
        'fileSize': file_size
    }
    create_resp = send_request("POST", API_CREATE_UPLOAD, payload)
    if create_resp.status_code != 200:
        print(f"  ERROR) Request failed: status_code {create_resp.status_code}, {create_resp.text}")
        return
    
    result_code = create_resp.json().get('resultCode')
    if result_code != 1000:
        result_message = create_resp.json().get('resultMessage')
        print(f"  ERROR) Create upload url failed: resultCode {result_code}, resultMessage {result_message}")
        return
    
    result_data = create_resp.json()['resultData']
    upload_id = result_data['uploadId']
    chunk_size = result_data['chunkSize']
    urls = result_data['preSignedUrl']
    print(f"  SUCCESS) uploadId: {upload_id}")
    print(f"  SUCCESS) chunkSize: {chunk_size} bytes")
    print(f"  SUCCESS) chunks: {len(urls)}")


    print("\n[STEP] Upload File")
    print("-" * 40)
    parts = []
    with open(INPUT_FILE, 'rb') as f:
        print(f"  INFO) Uploading {len(urls)} chunk(s)")
        for i, chunk in enumerate(read_in_chunks(f, chunk_size)):
            resp = requests.put(urls[i], data=chunk)
            etag = resp.headers.get('ETag', '').replace('"', '')
            parts.append({'awsETag': etag, 'partNumber': i + 1})
            print(f"    PROGRESS) chunk {i + 1}/{len(urls)} uploaded")

           
    print("\n[STEP] Complete Upload")
    print("-" * 40)
    complete_payload = {'uploadId': upload_id, 'parts': parts}
    complete_resp = send_request("POST", API_COMPLETE_UPLOAD, complete_payload)
    if complete_resp.status_code != 200:
        print(f"  ERROR) Request failed: status_code {complete_resp.status_code}, {complete_resp.text}")
        return
    
    result_code = complete_resp.json().get('resultCode')
    if result_code != 1000:
        result_message = complete_resp.json().get('resultMessage')
        print(f"  ERROR) Upload complete failed: resultCode {result_code}, resultMessage {result_message}")
        return
    
    print("  SUCCESS) Upload completed successfully")


    print("\n[STEP] Create Job")
    print("-" * 40)
    job_payload = {'audioUploadId': upload_id, 'type': 'vocal,drum'}
    job_resp = send_request("POST", API_CREATE_JOB, job_payload)
    if job_resp.status_code != 200:
        print(f"  ERROR) Request failed: status_code {job_resp.status_code}, {job_resp.text}")
        return
    
    result_code = job_resp.json().get('resultCode')
    if result_code != 1000:
        result_message = job_resp.json().get('resultMessage')
        print(f"  ERROR) Create job failed: resultCode {result_code}, resultMessage {result_message}")
        return
    
    result_data = job_resp.json()['resultData']
    job_id = result_data['jobId']
    print(f"  SUCCESS) jobId: {job_id}")


    print("\n[STEP] Check Job Status")
    print("-" * 40)
    while True:
        print(f"    PROGRESS) Checking job status...")
        status_resp = send_request("GET", API_JOB_STATUS.format(job_id), {})
        if status_resp.status_code != 200:
            print(f"  ERROR) Request failed: status_code {status_resp.status_code}, {status_resp.text}")
            break
        
        result_code = status_resp.json().get('resultCode')
        if result_code != 1000:
            result_message = status_resp.json().get('resultMessage')
            print(f"  ERROR) Status check failed: resultCode {result_code}, resultMessage {result_message}")
            break
        
        result_data = status_resp.json()['resultData']
        status = result_data['status']
        
        if status == 'success':
            download_url = result_data.get('downloadUrl')
            print("  SUCCESS) Job completed!")
            print("  Download URLs:")
            print(json.dumps(download_url, indent=2))
            break
        
        print(f"    PROGRESS) Status: {status}")
        print(f"    PROGRESS) Retrying in {SLEEP_INTERVAL} seconds...")
        time.sleep(SLEEP_INTERVAL)

if __name__ == '__main__':
    main()

Workflow​

Job Status​

Step-by-Step Guide​

Prerequisites​

1. Create a job​

2. Get a job​

Example Code​