EzStems API Documentation

Overview

The EzStems API allows premium subscribers to programmatically upload audio files and generate stems using Spleeter technology. This API supports multiple audio formats and provides various endpoints for managing the stem separation process.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Obtaining an API Key

1. Log in to your EzStems account
2. Navigate to the API section in your dashboard
3. Generate a new API key using the /api/v1/keys.php endpoint

Managing API Keys

You can list and manage your API keys using the following endpoints:

{
    "success": true,
    "data": [
        {
            "id": 1,
            "api_key": "********abcd1234",
            "is_active": 1,
            "rate_limit": 100,
            "calls_count": 50,
            "created_at": "2025-11-08 12:00:00",
            "last_used_at": "2025-11-08 12:30:00"
        }
    ]
}

{
    "success": true,
    "message": "API key deactivated successfully"
}

Endpoints

{
    "success": true,
    "data": {
        "api_key": "your-api-key-here",
        "message": "Store this API key securely. It won't be shown again."
    }
}

{
    "success": true,
    "data": {
        "id": "1699567234_2",
        "filename": "1699567234_2_12345.mp3",
        "status": "queued",
        "stems": "2",
        "check_status_endpoint": "/api/v1/status.php?id=1699567234_2"
    }
}

{
    "success": true,
    "data": {
        "id": "1699567234_2",
        "status": "completed",
        "queue_position": 0,
        "stems": 2,
        "created_at": "2025-11-09 14:30:34",
        "download_url": "/api/v1/download.php?id=1699567234_2"
    }
}

curl -X POST https://ezstems.com/api/v1/upload.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@song.mp3" \
  -F "stems=4"

curl -X GET "https://ezstems.com/api/v1/download.php?id=1699456789_4" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output stems.zip

Error Handling

Error responses include a JSON object with error details:

{
    "error": "Error message here",
    "message": "Additional error details when available"
}

Best Practices

• Use simple filenames without special characters
• Keep original file extensions
• Implement exponential backoff for retries
• Monitor your API usage through the dashboard
• Poll status endpoint at reasonable intervals (15-30 seconds)
• Implement timeouts for long-running processes
• Keep your API key secure
• Use HTTPS for all requests
• Implement proper error handling

Code Examples

import requests

API_KEY = 'your-api-key'
API_BASE = 'https://ezstems.com/api/v1'

# Upload file
with open('song.mp3', 'rb') as f:
    response = requests.post(
        f'{API_BASE}/upload.php',
        headers={'Authorization': f'Bearer {API_KEY}'},
        files={'file': f},
        data={'stems': 4}
    )
    
process_id = response.json()['data']['id']

# Check status
status_response = requests.get(
    f'{API_BASE}/status.php',
    headers={'Authorization': f'Bearer {API_KEY}'},
    params={'id': process_id}
)

# Download when ready
if status_response.json()['data']['status'] == 'completed':
    download_response = requests.get(
        f'{API_BASE}/download.php',
        headers={'Authorization': f'Bearer {API_KEY}'},
        params={'id': process_id},
        stream=True
    )
    with open('stems.zip', 'wb') as f:
        for chunk in download_response.iter_content(chunk_size=8192):
            f.write(chunk)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const API_KEY = 'your-api-key';
const API_BASE = 'https://ezstems.com/api/v1';

async function processSong() {
    try {
        // Upload file
        const form = new FormData();
        form.append('file', fs.createReadStream('song.mp3'));
        form.append('stems', '4');
        
        const uploadResponse = await axios.post(`${API_BASE}/upload.php`, form, {
            headers: {
                ...form.getHeaders(),
                'Authorization': `Bearer ${API_KEY}`
            }
        });
        
        const processId = uploadResponse.data.data.id;
        
        // Check status
        const statusResponse = await axios.get(`${API_BASE}/status.php`, {
            params: { id: processId },
            headers: { 'Authorization': `Bearer ${API_KEY}` }
        });
        
        // Download when ready
        if (statusResponse.data.data.status === 'completed') {
            const writer = fs.createWriteStream('stems.zip');
            const downloadResponse = await axios.get(`${API_BASE}/download.php`, {
                params: { id: processId },
                headers: { 'Authorization': `Bearer ${API_KEY}` },
                responseType: 'stream'
            });
            
            downloadResponse.data.pipe(writer);
        }
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
}

processSong();

Support

For API support or questions, contact us at:

• Email: api@ezstems.com
• Documentation: https://ezstems.com/api/docs
• Status Page: https://status.ezstems.com