Docs

BeatSync API documentation

BeatSync API accepts direct audio uploads and returns structured rhythm data for short-form video automation: BPM, beat timestamps, downbeats, cut points, and timeline segments. Public requests must use multipart/form-data with a file field. Uploads are temporarily stored for analysis and are limited to 50 MB.

curl --request POST \
  --url https://beatsyncapi.p.rapidapi.com/v1/analyze-sync \
  --header "X-RapidAPI-Key: $RAPIDAPI_KEY" \
  --header "X-RapidAPI-Host: beatsyncapi.p.rapidapi.com" \
  --form "mode=beat_sync" \
  --form "file=@/path/to/clip.mp3;type=audio/mpeg"

Endpoint

Multipart upload

curl --request POST \
  --url https://beatsyncapi.p.rapidapi.com/v1/analyze-sync \
  --header "X-RapidAPI-Key: $RAPIDAPI_KEY" \
  --header "X-RapidAPI-Host: beatsyncapi.p.rapidapi.com" \
  --form "mode=beat_sync" \
  --form "file=@/path/to/clip.mp3;type=audio/mpeg"

• Use the form field name file.
• mode currently supports beat_sync.
• The uploaded audio file must be 50 MB or smaller.
• Multipart uploads are temporarily stored before analysis; processing services receive only an internal file reference.

Successful response

{
  "duration": 34.12,
  "bpm": 99.4,
  "beats": [
    { "time": 0.61, "confidence": 0.92 }
  ],
  "downbeats": [
    { "time": 0.61, "bar": 1, "confidence": 0.86 }
  ],
  "cut_points": [
    { "time": 4.84, "score": 0.88, "type": "beat" }
  ],
  "segments": [
    { "start": 0.0, "end": 7.28, "type": "measure" }
  ],
  "meta": {
    "request_id": "req_...",
    "processing_ms": 2841,
    "audio_duration": 34.12
  }
}

Times are returned in seconds. Use beats for beat-grid alignment, downbeats for stronger musical anchors, and cut_points for edit decisions when you need fewer, higher-confidence timing marks.

Error examples

Request validation error

{
  "error": {
    "code": "invalid_request",
    "message": "Multipart upload requires a file field named file."
  }
}

{
  "error": {
    "code": "file_too_large",
    "message": "Uploaded audio file exceeds the 50 MB limit."
  }
}

Analysis error

{
  "error": {
    "code": "AUDIO_TOO_LONG",
    "message": "Audio duration exceeds the 120 second limit for synchronous analysis.",
    "request_id": "req_..."
  }
}

Timeout or service unavailable

{
  "error": {
    "code": "ANALYSIS_TIMEOUT",
    "message": "Analysis did not finish before the synchronous response timeout.",
    "request_id": "req_..."
  },
  "task_id": "atsk_..."
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Analysis service is unavailable.",
    "request_id": "req_..."
  },
  "task_id": "atsk_..."
}

Plan limits

The API is optimized for short-form media workflows. For long audio, batch processing, or guaranteed throughput, contact us before relying on production volume.