API Overview
The Sheet Music Manager API provides programmatic access to our optical music recognition (OMR) technology. Convert sheet music images and PDFs to MusicXML and MIDI formats using simple HTTP requests.
Base URL
https://api.sheetmusicmanager.com/v1
Key Features
- High Accuracy: 98% accuracy on high-quality sheet music
- Multiple Formats: Support for PDF, JPEG, PNG, HEIC, and HEIF
- Fast Processing: Typical conversion times under 2 minutes
- Flexible Output: MusicXML and MIDI format support
- Batch Processing: Process multiple files simultaneously
- Real-time Status: Track job progress with webhooks
Authentication
The API uses API key authentication. Include your API key in the request headers:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
You can obtain an API key by creating an account and visiting your dashboard. Free tier includes 10 conversions per month.
Available Endpoints
POST
/upload
Upload and Process Sheet Music
Upload a sheet music file for optical music recognition processing.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| file | file | Required | Sheet music file (PDF, JPEG, PNG, HEIC, HEIF) |
| format | string | Optional | Output format: "musicxml" (default) or "both" |
| webhook_url | string | Optional | URL to receive completion notification |
Example Request
curl -X POST https://api.sheetmusicmanager.com/v1/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@sheet-music.pdf" \
-F "format=both"
Response
{
"success": true,
"message": "File processed successfully",
"data": {
"filename": "sheet-music.pdf",
"musicXML": "<?xml version=\"1.0\"?>...",
"processingTime": 45.2,
"pages": 2
},
"requestId": "req_123456789"
}
Status Codes
200 OK File processed successfully
400 Bad Request Invalid file format or missing parameters
500 Internal Server Error Processing failed
POST
/convert-to-midi
Convert MusicXML to MIDI
Convert a MusicXML file to MIDI format.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| musicxml | file | Required | MusicXML file to convert |
Example Request
curl -X POST https://api.sheetmusicmanager.com/v1/convert-to-midi \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "musicxml=@output.musicxml" \
--output output.mid
200 OK Returns MIDI file as binary data
POST
/api/batch-upload
Batch File Processing
Process multiple sheet music files in a single request (up to 10 files).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| files | file[] | Required | Array of sheet music files (max 10) |
Example Response
{
"success": true,
"batchId": "batch_123456",
"results": [
{
"filename": "song1.pdf",
"success": true,
"jobId": "job_789",
"data": { /* MusicXML data */ }
}
],
"summary": {
"total": 5,
"successful": 4,
"failed": 1
}
}
GET
/status/{jobId}
Get Job Status
Check the status of a processing job.
Example Response
{
"success": true,
"job": {
"id": "job_123456",
"status": "completed",
"progress": 100,
"result": { /* Processing result */ }
}
}
Error Handling
The API returns standard HTTP status codes and detailed error messages:
{
"error": "Invalid file type",
"message": "Please upload a valid sheet music file (PDF, JPEG, PNG, HEIC, or HEIF)",
"requestId": "req_123456789",
"timestamp": "2024-01-01T12:00:00Z"
}
Common Error Codes
- 400 Bad Request: Invalid parameters or file format
- 401 Unauthorized: Invalid or missing API key
- 413 Payload Too Large: File exceeds 50MB limit
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Processing failed
Rate Limits
To ensure fair usage, the API implements the following rate limits:
| Endpoint | Limit | Window |
|---|---|---|
| General requests | 100 requests | 15 minutes |
| File uploads | 5 uploads | 1 minute |
| Heavy processing | 10 requests | 5 minutes |
Rate limit headers are included in responses:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
Code Examples
JavaScript/Node.js
const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');
async function convertSheetMusic(filePath) {
const form = new FormData();
form.append('file', fs.createReadStream(filePath));
try {
const response = await axios.post(
'https://api.sheetmusicmanager.com/v1/upload',
form,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
...form.getHeaders()
}
}
);
console.log('Conversion successful:', response.data);
return response.data;
} catch (error) {
console.error('Conversion failed:', error.response.data);
}
}
// Usage
convertSheetMusic('./sheet-music.pdf');
Python
import requests
def convert_sheet_music(file_path):
url = 'https://api.sheetmusicmanager.com/v1/upload'
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
with open(file_path, 'rb') as file:
files = {'file': file}
response = requests.post(url, headers=headers, files=files)
if response.status_code == 200:
return response.json()
else:
raise Exception(f'API request failed: {response.text}')
# Usage
result = convert_sheet_music('sheet-music.pdf')
print(result)
PHP
<?php
function convertSheetMusic($filePath) {
$url = 'https://api.sheetmusicmanager.com/v1/upload';
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_KEY'
],
CURLOPT_POSTFIELDS => [
'file' => new CURLFile($filePath)
]
]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($httpCode === 200) {
return json_decode($response, true);
} else {
throw new Exception('API request failed: ' . $response);
}
}
// Usage
$result = convertSheetMusic('sheet-music.pdf');
print_r($result);
?>
Official SDKs
We provide official SDKs to make integration easier:
JavaScript/Node.js
Official SDK for JavaScript and Node.js applications
npm install @sheetmusicmanager/sdk
Python
Official Python SDK with async support
pip install sheetmusicmanager
PHP
Composer package for PHP applications
composer require sheetmusicmanager/php-sdk