Skip to main content

Ondemand Analysis Stream

POST 
/v1/analysis/stream

Streaming endpoint for analyzing music audio from an audio file/URL input using multiple ML models simultaneously. The uploaded audio file and results are not stored in our servers.

The response is a stream of JSON events using Server-Sent Events (SSE) protocol.

Payload (bytes, None): Audio file as binary data or an empty string if audio URL is provided as header.

Query params: models (str): Comma-separated model specifications with name and version separated by colon. Format: "model_name:version" or just "model_name" for default version. Example: "key:1,bpm_degara,loudness-ebur128"

Headers: audio-url (str, optional): URL encoded string of an audio file on CDN filename (str, optional): Filename of the binary audio payload

Response Format (Server-Sent Events):

Each event is a JSON object with the following structure:

Started Event:

{"status": "started", "total_models": 3}

Completed Event (for each model):

{
  "status": "completed",
  "result": {
    "model_name": "key",
    "model_version": "1",
    "correlation_id": "uuid",
    "results": {...}
  }
}

Error Event:

{"status": "error", "error": "error message"}

Finished Event:

{"status": "finished", "total_models": 3}

Examples:

Using local audio file with multiple models:

curl -X POST "http://$API_DNS/v1/analysis/stream?models=key:1,bpm_degara" \
    -H "filename: track.mp3" \
    -H "Accept: text/event-stream" \
    -H "Cache-Control: no-cache" \
    -H "X-Accel-Buffering: no" \
    --data-binary @/path/to/track.mp3

Using audio file from URL with multiple models:

curl -X POST "http://$API_DNS/v1/analysis/stream?models=key:1,loudness-ebur128" \
    -H "audio-url: https://cdn.freesound.org/previews/806/806702_5287430-lq.mp3" \
    -H "Accept: text/event-stream" \
    -H "Cache-Control: no-cache" \
    -H "X-Accel-Buffering: no"

Notes:

  • Results are streamed as they become available
  • The connection remains open until all models complete
  • Use "Accept: text/event-stream" header for proper SSE handling
  • Either provide binary audio data OR audio_url header (not both)

Request​

Responses​

Successful Response