Understanding Analysis Jobs
The Essentia API is designed for asynchronous processing. Instead of waiting for an analysis to complete, you submit a job and then poll for the results. This is the most robust way to handle large files and complex analyses.
How It Works: A 3-Step Process
The entire workflow can be broken down into three simple steps:
Step 1:
First, you upload a local audio file or URL by submitting a POST request to the /v1/audio endpoint.
curl -X POST "https://api.essentia.upf.edu/v1/audio" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "audio_url=https://cdn.freesound.org/previews/806/806702_5287430-lq.mp3"
This will return an unique asset_id for your audio file which you can use to do any subsequent analysis jobs, metadata updates etc.
Step 2: Submit an Analysis Job
Next, you can submit an analysis job for your uploaded asset by specifying the asset id and list of analysis algorithms that you want to run.
curl -X POST "https://api.essentia.upf.edu/v1/analysis/job" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"asset_id": "<asset-id-from-step-1>",
"models": ["genre_discogs_400", "engagement", "approachability", "timbre"]
}'
Step 3: Poll for job status and task results
The analysis job request from above step immediately respond with a job_id and a list of task_id corresponding to the feature extraction for each analysis algorithm you specified in the job request.
This ID is your unique reference to this analysis job. You can use identifiers to poll for status using GET requests to the /v1/analysis/{job_id} endpoint.
Once the status field changes to SUCCESS, you can also use individual task_id to retrieve the results using GET requests to /v1/analysis/{job_id}/{task_id} endpoint.
For most jobs, polling every 5-10 seconds is a good starting point. For very large files, you can reduce the frequency.
➡️ See the full API reference for getting job status.
Supported Formats
Internally, Essentia relies on FFmpeg for decoding audio, so we accept most formats supported by this library. Only audio with up to two channels is supported.
Limitations
- Input files are limited to 200MB.
- Audio duration is limited to 20 minutes. For files longer than this, only the first 20 minutes will be analyzed.
Contact us for custom extended limit requests.