Docs

BeatSync API documentation

BeatSync API accepts a public audio_url and returns structured rhythm data for short-form video automation: BPM, beat timestamps, downbeats, cut points, and timeline segments.

You can send audio in two ways: provide a public audio URL for production pipelines, or upload a file directly with multipart/form-data. Direct uploads are stored in R2 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" \
  --header "Content-Type: application/json" \
  --data '{
    "audio_url": "https://example.com/audio.mp3",
    "mode": "beat_sync"
  }'

Endpoint

JSON request body

{
  "audio_url": "https://example.com/audio.mp3",
  "mode": "beat_sync"
}

• audio_url must be a public HTTPS URL to an audio file.
• mode currently supports beat_sync.
• Keep files short and directly downloadable. Web pages, redirects that hide files, and private URLs may fail validation.

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=@clip.mp3;type=audio/mpeg"

• Use the form field name file.
• The uploaded audio file must be 50 MB or smaller.
• Multipart uploads are stored in R2 before analysis; the AWS worker receives only an R2 object 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": "intro" }
  ],
  "meta": {
    "engine": "beat_this",
    "engine_version": "0.1.0",
    "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

{
  "error": {
    "code": "INVALID_AUDIO_URL",
    "message": "audio_url must be a public HTTP or HTTPS audio file.",
    "request_id": "req_..."
  }
}

{
  "error": {
    "code": "AUDIO_TOO_LONG",
    "message": "Audio duration exceeds the plan limit.",
    "request_id": "req_..."
  }
}

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.