Skip to main content
This guide walks through the complete analysis lifecycle: uploading a video, monitoring progress, and retrieving different levels of result data.

​
Video requirements

Before uploading, make sure your video meets these constraints:
ConstraintRequirement
File size30 MB maximum
Duration10 seconds maximum
FormatMP4, MOV, AVI, or WEBM
Resolution1080p recommended (max 1080p height)
Frame rate30 fps minimum, 60 fps recommended

​
Orientation

The required orientation depends on the analysis type and running condition. Submitting a video with the wrong orientation will produce poor results or cause the analysis to fail.
Analysis typeConditionOrientationTypical resolution
Side viewOverground (treadmill=false)Landscape (16:9)1920 x 1080
Side viewTreadmill (treadmill=true)Portrait (9:16)1080 x 1920
Back viewAnyPortrait (9:16)1080 x 1920
Record at 30 fps or higher for best results. The runner should be clearly visible and occupy a significant portion of the frame. See example videos for reference clips.

​
Analysis types

Choose the analysis type based on the camera position:
Camera is positioned to the side of the runner. Set analysis_type=side_view.Produces:
  • Overall biomechanical score (0 — 1)
  • Running metrics: speed, step length, cadence, ground contact time, time of flight, duty factor
  • Overstride analysis with angle and score
  • Foot landing classification per step (rearfoot, midfoot, forefoot)
  • Joint angles: ankle, knee, hip, shoulder, elbow
  • Running style classification with confidence percentage
See example videos for sample input and output videos of each analysis type.

​
Parameters

ParameterTypeRequiredDefaultDescription
videofileYes—Video file to analyze
analysis_typestringYesside_viewside_view or back_view
heightnumberNo1.70Runner height in meters
weightnumberNo70Runner weight in kilograms
pacestringConditional—Running pace MM:SS. Required when treadmill=true. Auto-calculated for overground running.
languagestringNoenResult language: en, fr, de, zh, ko, pt, es, it, ja
treadmillbooleanNofalseWhether the runner is on a treadmill
full_bodybooleanNotrueFull body analysis (back view only). Set false for pronation only.
subject_idstringNo—Subject ID to link the analysis to. See subject management.

​
Lifecycle

​
Status progression

StatusHTTP codeMeaning
pending200Analysis is queued, waiting for a processing slot.
analyzing202Processing is underway. The percentage field shows progress.
success200Analysis is complete. Full results are available.
failed400Analysis could not be completed. No results available.

​
Polling strategy

Poll the results endpoint every 3 — 5 seconds. Most analyses complete within 10 — 30 seconds depending on video length and server load. 
import time
import requests

def wait_for_analysis(video_id: str, api_key: str, interval: float = 3.0) -> dict:
    """Poll until analysis completes or fails."""
    url = f"https://partner-api.ochy-prod.com/analysis/{video_id}/results"
    while True:
        response = requests.get(url, params={"apiKey": api_key})
        data = response.json()

        if data["status"] in ("success", "failed"):
            return data

        time.sleep(interval)

​
Webhooks (optional)

You can register an HTTPS endpoint and enable notifications per analysis to receive progress and completion events without polling. See Analysis webhooks

​
Result levels

Once the status is success, you can access three levels of data:
The results endpoint returns everything in a single call: status, signed URLs (thumbnail and annotated video), and the biomechanical_analysis object containing scores, metrics, and classifications.Use this when you need a complete snapshot of the analysis.
Structured numerical metrics without media URLs. Ideal when you need to process or display specific values.Side view includes: metrics, overstride, foot_landing, joint_angles, running_styles, and total_score.Back view includes: gait_cycle with stance means per leg (pronation, knee adduction, pelvic drop) and step-by-step data.
Frame-by-frame position data for every anatomical landmark detected. Includes video_input_information (resolution, FPS, duration) and a frames object keyed by frame number.Use this for custom visualizations, overlays, or your own biomechanical models.

​
Error handling

Common errors during the analysis workflow:
ErrorCodeStatusWhen
File too largefile_too_large413Video exceeds 30 MB
Video too long—400Video exceeds 10 seconds
Invalid file typeinvalid_file_type400Unsupported extension (not MP4, MOV, AVI, or WEBM)
Not completed—400Requesting calculated/raw data before success
Insufficient creditsinsufficient_credits402No credits remaining
Not found—404Invalid analysis_id