​
Minimal python usage of Voice Harbor API

1

Token Managment.

1.1 Use your admin token to create usage token’s..

Minimal usage token creation example:

# Configuration
BASE_URL = "https://voiceharbor.ai"
ADMIN_TOKEN = "your_admin_token_here"
endpoint = f"{BASE_URL}/api/admin/developer-token"
headers = {"Authorization": f"Bearer {ADMIN_TOKEN}"}
response = requests.post(endpoint, headers=headers)
response.raise_for_status()
data = response.json()
print("Usage tokens:", data)

Result:

{
  "developerToken": "<string>"
}
2

Submision Managment.

2.1 Use the usage token to create a job and submit files.

Minimal job creation example:

def create_job():
    """Creates a new job and returns its job_id."""
    resp = requests.post(f"{BASE_URL}/api/jobs", headers={"Authorization": TOKEN})
    resp.raise_for_status()
    return resp.json()["job_id"]

Minimal file upload example:

def get_signed_url(job_id, file_name, mime_type):
    """Retrieves a signed URL for uploading a file."""
    url = f"{BASE_URL}/api/jobs/{job_id}/files/upload-url"
    payload = {"fileName": file_name, "fileType": mime_type}
    resp = requests.post(url, json=payload, headers={"Authorization": TOKEN})
    resp.raise_for_status()
    return resp.json()["signedUrl"]

def upload_file(job_id, file_path):
    """Uploads a file to the server using its signed URL."""
    file_path = Path(file_path)
    mime_type, _ = mimetypes.guess_type(str(file_path))
    mime_type = mime_type or "application/octet-stream"
    signed_url = get_signed_url(job_id, file_path.name, mime_type)
    with file_path.open("rb") as f:
        resp = requests.put(signed_url, data=f, headers={"Content-Type": mime_type})
        resp.raise_for_status()

2.2 Select and Define the job parameters.

Minimal parameter creation example:

def create_job_yaml(job_id, input_file):
    """Creates a YAML job file with the required parameters."""
    params = {
        "files": [Path(input_file).name],
        "model": "mini"
    }
    yaml_file = Path(f"{job_id}.yaml")
    with yaml_file.open("w") as f:
        yaml.safe_dump(params, f, default_flow_style=False)
    return yaml_file

Minimal file upload example:

def upload_file(job_id, file_path):
    """Uploads a file to the server using its signed URL."""
    file_path = Path(file_path)
    mime_type, _ = mimetypes.guess_type(str(file_path))
    mime_type = mime_type or "application/octet-stream"
    signed_url = get_signed_url(job_id, file_path.name, mime_type)
    with file_path.open("rb") as f:
        resp = requests.put(signed_url, data=f, headers={"Content-Type": mime_type})
        resp.raise_for_status()
3

Download protected audio and trascription.

3.1 Use your usage token and job id to download the results.

def get_signed_url_download(job_id, file_name, usage_token):
    """Gets a signed URL to download the specified file."""
    url = f"{BASE_URL}/api/jobs/{job_id}/files/download-url"
    payload = {"fileName": file_name}
    resp = requests.post(url, json=payload, headers={"Authorization": usage_token})
    resp.raise_for_status()
    return resp.json()["signedUrl"]

def download_file(job_id, file_name, dest_dir):
    """Downloads the specified file once it is available."""
    download_url = get_signed_url_download(job_id, file_name)
    resp = requests.get(download_url)
    resp.raise_for_status()
    dest = Path(dest_dir) / file_name
    dest.parent.mkdir(parents=True, exist_ok=True)
    with dest.open("wb") as f:
        f.write(resp.content)

Minimal usage example:

# -----------------------------------------------------------------------------
# Example usage:
#
# job_id = create_job()
#
# # Upload the main input file.
# upload_file(job_id, "input.wav")
#
# # Create and upload the job YAML file.
# yaml_file = create_job_yaml(job_id, "input.wav")
# upload_file(job_id, yaml_file)
#
# # Download the processed files (the masked and its JSON result).
# download_file(job_id, "input.wav", "./results")
# download_file(job_id, "input.json", "./results")
# -----------------------------------------------------------------------------