Python SDK

AI-MIDI Python SDK

Use the Python SDK to convert MP3 and audio files into editable MIDI.

The aimidi package keeps the workflow simple: provide a local audio file, choose a model, and save the MIDI result.

Install

The PyPI package becomes available with the public production SDK release. Until then, use the reviewed repository source for staging verification.

shell

1python -m pip install ai-midi

API Key

Set your staging API key and the staging API URL before calling AI-MIDI. Keep the key on your server or local machine. Do not put it in browser JavaScript, mobile app bundles, or public notebooks.

shell

1export AIMIDI_API_KEY="YOUR_STAGING_API_KEY"2export AIMIDI_BASE_URL="https://staging-api.ai-midi.com"

python code

1import aimidi2 3aimidi.api_key = "YOUR_STAGING_API_KEY"4aimidi.base_url = "https://staging-api.ai-midi.com"

Usage Rules

These rules apply when your code uploads audio and starts a conversion through the API.

Credit charge

1 credit covers 5 seconds of audio. Each conversion has a 12 credits minimum.

Failed jobs

System failures return held credits. Files rejected before processing do not spend credits.

Rights

Do not upload copyrighted recordings unless you have the rights or permission to process them.

Credit status

The API account page shows the authoritative available credit balance.

Credit validity

Paid credits expire 12 months after purchase. Credits with the earliest expiration date are used first.

File retention

API audio and generated files are processed temporarily and deleted within 24 hours. Store the MIDI response you need to keep.

Credit limits

Credits are not cash, e-money, stored-value payment instruments, or securities.

Price changes

Existing credit counts remain. Future credit consumption rates may change with notice.

MP3 to MIDI with Python code

Use aimidi.convert() for the common case. It waits for the conversion to finish and returns a MIDI result.

python code

1import aimidi2 3aimidi.api_key = "YOUR_STAGING_API_KEY"4aimidi.base_url = "https://staging-api.ai-midi.com"5 6midi = aimidi.convert("song.mp3", model="piano")7midi.save("song.mid")

Guitar Conversion

Choose model="guitar"when the source is guitar-focused.

python code

1midi = aimidi.convert("guitar-riff.wav", model="guitar")2midi.save("guitar-riff.mid")

Save During Conversion

Pass output_path if you already know where the MIDI file should be written.

python code

1midi = aimidi.convert(2    "song.mp3",3    model="piano",4    output_path="song.mid",5)

Reuse A Client

For applications or batch jobs, create one client and reuse it. This keeps your API key and configuration in one place.

python code

1import aimidi2 3client = aimidi.Client(4    api_key="YOUR_STAGING_API_KEY",5    base_url="https://staging-api.ai-midi.com",6)7 8midi = client.convert("take-01.wav", model="piano")9midi.save("take-01.mid")

Check Usage

Use client.usage() to check the current usage status for the API key before starting a larger batch.

python code

1usage = client.usage()2 3print(usage)

Result Object

job_idThe conversion job identifier.

modelThe model used for this conversion.

contentThe generated MIDI file as bytes.

statusConversion metadata returned with the completed result.

save(path)Write the MIDI bytes to a file and return the saved path.

Reference API

This section lists the public Python code objects exposed by aimidi.

Configuration

aimidi.api_keyAPI key used by package-level helpers.

aimidi.base_urlAPI base URL used by package-level helpers. Set it for your environment when needed.

Functions

aimidi.convert()Convert one local audio file into a MIDI result.

Classes

aimidi.ClientReusable client for repeated conversions and usage checks.

aimidi.MidiResultCompleted conversion result containing MIDI bytes and metadata.

Client Methods

Client.convert()Convert one local audio file with the client configuration.

Client.usage()Read the current usage status for the API key.

Detailed Reference

aimidi.convert

python code

1aimidi.convert(2    audio_path: str,3    *,4    model: str = "piano",5    output_path: str | None = None,6    timeout_seconds: float = 900.0,7) -> MidiResult

Convert a local audio file into MIDI. This helper waits for the conversion response and returns a MidiResult containing MIDI bytes.

audio_pathRequired. Path to a local audio file.

modelOptional. "piano" or "guitar". Default is "piano".

output_pathOptional. Path where the MIDI file should be written.

timeout_secondsOptional. Maximum time to wait for one conversion. Default is 900 seconds.

aimidi.Client

python code

1aimidi.Client(2    *,3    api_key: str,4    base_url: str = "...",5    timeout_seconds: float = 60.0,6)

Create a reusable client. Use this form for applications, batch scripts, or any code that performs more than one operation.

api_keyRequired. API key for the AI-MIDI account.

base_urlOptional. API base URL.

timeout_secondsOptional. Network request timeout. Default is 60 seconds.

Client.convert

python code

1client.convert(2    audio_path: str,3    *,4    model: str = "piano",5    output_path: str | None = None,6    timeout_seconds: float = 900.0,7) -> MidiResult

Convert a local audio file using the client configuration. Arguments match aimidi.convert().

audio_pathRequired. Path to a local audio file.

modelOptional. "piano" or "guitar". Default is "piano".

output_pathOptional. Path where the MIDI file should be written.

timeout_secondsOptional. Maximum time to wait for one conversion. Default is 900 seconds.

Client.usage

python code

1client.usage() -> dict

Return usage information for the API key. Use this before larger batches when you want to check available usage.

credits_totalTotal credits assigned to the API account.

credits_remainingCredits available for new conversions.

credits_usedCredits already charged by successful API jobs.

billing_debt_creditsCredits awaiting billing reconciliation.

billing_risk_hold_creditsCredits temporarily held during a dispute warning.

used_percentUsed portion of the starting balance.

MidiResult

python code

1MidiResult(2    job_id: str,3    model: str,4    content: bytes,5    status: dict,6)

Completed conversion result. Use save(path) to write the generated MIDI file.

job_idThe conversion job identifier.

modelThe model used for this conversion.

contentThe generated MIDI file as bytes.

statusConversion metadata returned with the completed result.

save(path)Write the MIDI bytes to a file and return the saved path.

Error Handling

Catch specific errors when you want user-friendly messages or retry behavior.

python code

1try:2    midi = aimidi.convert("song.mp3", model="piano")3    midi.save("song.mid")4except aimidi.InsufficientCreditsError:5    print("Add credits in your AI-MIDI dashboard.")6except aimidi.InvalidApiKeyError:7    print("Check your API key.")8except aimidi.InvalidAudioError:9    print("Upload a supported audio file.")10except aimidi.ServerUnavailableError:11    print("AI-MIDI API is unavailable. Try again later.")

InvalidApiKeyErrorThe API key is missing or invalid.

InsufficientCreditsErrorThe account does not have enough credits.

InvalidModelErrorThe requested model is not supported.

AudioFileNotFoundErrorThe local audio path does not exist.

InvalidAudioErrorThe file cannot be read as supported audio.

FileTooLargeErrorThe uploaded file is too large.

ConversionFailedErrorThe conversion failed after it started.

ConversionTimeoutErrorThe conversion did not finish before the timeout.

ServerUnavailableErrorThe service cannot be reached or timed out.