uhmbrella-api 0.1.3

Uhmbrella AIMD - client SDK and CLI for the Uhmbrella AI music detection API.

Uhmbrella AIMD API – CLI and HTTP reference

This document describes how to use the uhmbrella-api Python package via:

• The CLI command: uhmbrella-api
• The equivalent raw HTTP API calls (for curl or backend use)

It only covers behaviour that exists in the current cli.py.

Default base URL:

https://api.uhmbrella.io

You can override this with:

• --api-base https://your-api-host
• or environment variable UHM_API_BASE

All public endpoints require:

x-api-key: YOUR_API_KEY

You can supply the API key either as a CLI flag or via environment variable.

---

0. Authentication and globals

CLI

You can pass the API key directly:

uhmbrella-api --api-key YOUR_API_KEY usage

Or set an environment variable:

export UHM_API_KEY="YOUR_API_KEY"
uhmbrella-api usage

The CLI understands the following global options:

• --api-key - API key for auth (or set UHM_API_KEY)
• --api-base - override the API base URL

These flags can appear anywhere in the command. For example, all of these are equivalent:

uhmbrella-api --api-key KEY usage
uhmbrella-api usage --api-key KEY
uhmbrella-api usage --api-key=KEY

The CLI normalises the arguments before parsing.

---

1. Check usage

Shows current quota and usage for the API key.

CLI

uhmbrella-api usage --api-key YOUR_API_KEY

HTTP

curl "https://api.uhmbrella.io/usage" -H "x-api-key: YOUR_API_KEY"

The response is a JSON object similar to:

{
  "user_id": "test_user",
  "plan_name": "trial_100min",
  "quota_seconds": 6000,
  "used_seconds": 765,
  "remaining_seconds": 5235
}

---

2. Synchronous scan

The scan command uploads audio for immediate analysis.

Behaviour:

• If --input points to a single file, the CLI calls POST /v1/analyze.
• If --input points to a directory, the CLI calls POST /v1/analyze-batch for up to 40 files.
• Results are written as JSON files in the chosen output directory.

During upload, a tqdm progress bar shows bytes sent.

2.1 Single file

Results are saved as <output-dir>/<filename>.analysis.json.

CLI

uhmbrella-api scan --input "/path/to/audio.mp3" --output-dir "./uhm_results" --api-key YOUR_API_KEY

Key options:

• --input - path to an audio file
• --output-dir - directory to write JSON results (default ./uhm_results)

HTTP

curl -X POST "https://api.uhmbrella.io/v1/analyze" -H "x-api-key: YOUR_API_KEY" -F "file=@/path/to/audio.mp3"

The HTTP response is a single analysis object that includes:

• predicted class percentages
• segments and segmentsVox arrays
• audio length and billed seconds
• usage details for the API key

2.2 Small folder (up to 40 files)

If the input is a folder, the CLI will:

• collect audio files based on patterns
• upload them in a batch to /v1/analyze-batch
• write one JSON result per file

If more than 40 files are found, the CLI exits with an error and asks you to use jobs create instead.

CLI

uhmbrella-api scan --input "./audio_folder" --output-dir "./uhm_results" --recursive --api-key YOUR_API_KEY

Options:

• --input - directory containing audio files
• --output-dir - directory to write JSON results
• --recursive - recurse into subdirectories
• --patterns - override patterns, for example:

  --patterns "*.wav" "*.flac"
  

Default patterns are:

*.mp3 *.wav *.flac *.m4a

HTTP

curl -X POST "https://api.uhmbrella.io/v1/analyze-batch" -H "x-api-key: YOUR_API_KEY" -F "files=@/path/to/track1.wav" -F "files=@/path/to/track2.mp3"

The response contains:

• results - list of per file analysis objects
• usage - updated usage summary

Each result item has the same shape as a single file analysis.

---

3. Create async job

For larger sets of files, the CLI supports async jobs via the /v1/jobs endpoint. Files are uploaded once and processed in the background.

CLI

uhmbrella-api jobs create --input "./audio_folder" --recursive --api-key YOUR_API_KEY

Options:

• --input - file or directory
• --recursive - recurse into directories when --input is a folder
• --patterns - override default file patterns

Example with custom patterns:

uhmbrella-api jobs create --input "./audio_folder" --recursive --patterns "*.wav" "*.flac" --api-key YOUR_API_KEY

The CLI prints the JSON response and, if possible, a convenient reminder of follow up commands, for example:

[JOB CREATED]
{
  "job_id": "7f3f696c-8052-43f8-a5c5-08b3767b030e",
  "status": "queued",
  "total_files": 123,
  ...
}

You can now run:
  uhmbrella-api jobs status --job-id 7f3f696c-8052-43f8-a5c5-08b3767b030e
  uhmbrella-api jobs results --job-id 7f3f696c-8052-43f8-a5c5-08b3767b030e --output-dir ./results

Uploads use tqdm to show total bytes sent.

HTTP

curl -X POST "https://api.uhmbrella.io/v1/jobs" -H "x-api-key: YOUR_API_KEY" -F "files=@/path/to/track1.wav" -F "files=@/path/to/track2.wav"

The HTTP response includes at least:

• job_id
• status
• total_files
• fields relating to billed and remaining seconds

---

4. Job status

Check the status and progress of a previously created job.

CLI

uhmbrella-api jobs status --job-id JOB_ID --api-key YOUR_API_KEY

The CLI prints the JSON returned by the API.

HTTP

curl "https://api.uhmbrella.io/v1/jobs/JOB_ID/status" -H "x-api-key: YOUR_API_KEY"

The response includes fields such as:

• job_id
• status (for example queued, processing, done, error, cancelling, cancelled)
• total_files
• counts per status
• quota and usage information

---

5. Job results

Fetch per file results for a job. The CLI can either print the full JSON or write individual result files to disk.

CLI

uhmbrella-api jobs results --job-id JOB_ID --output-dir "./results" --api-key YOUR_API_KEY

Behaviour:

• Always prints a summary to stdout:
  • job_id
  • status
  • results_count
• If --output-dir is omitted:
  • prints the full raw JSON to stdout and exits.
• If --output-dir is provided:
  • creates the directory if needed
  • for each item in results:
    • if status == "done", writes <filename>.analysis.json
    • otherwise, writes <filename>.error.json

This lets you separate successful analyses from errors.

HTTP

curl "https://api.uhmbrella.io/v1/jobs/JOB_ID/results" -H "x-api-key: YOUR_API_KEY"

The response JSON includes:

• overall job_id and status
• results: a list where each item contains:
  • filename
  • status
  • possibly error
  • result (same shape as /v1/analyze) when status is done

---

6. Cancel job

Request cooperative cancellation of a long running job. The worker finishes the current file then stops.

CLI

uhmbrella-api jobs cancel --job-id JOB_ID --api-key YOUR_API_KEY

The CLI prints the JSON response from the API.

HTTP

curl -X POST "https://api.uhmbrella.io/v1/jobs/JOB_ID/cancel" -H "x-api-key: YOUR_API_KEY"

Typical responses:

If cancellation is accepted:

{
  "job_id": "JOB_ID",
  "status": "cancelling"
}

If the job has already finished or been cancelled, you get its current status instead, for example:

{
  "job_id": "JOB_ID",
  "status": "done"
}

or

{
  "job_id": "JOB_ID",
  "status": "cancelled"
}

---

7. Environment helper

The env subcommand prints OS specific commands for setting your API key in the environment.

CLI

uhmbrella-api env --api-key YOUR_API_KEY