Analysis workflow

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:

Constraint	Requirement
File size	30 MB maximum
Duration	10 seconds maximum
Format	MP4, MOV, AVI, or WEBM
Resolution	1080p recommended (max 1080p height)
Frame rate	30 fps minimum, 60 fps recommended

Orientation

Required orientation depends on the analysis type and running condition (see the treadmill parameter below). Submitting a video with the wrong orientation will produce poor results or cause the analysis to fail.

See example videos for the full orientation matrix, typical resolutions, and reference input/output clips per scenario.

Analysis types

Choose the analysis type based on the camera position:

Side view
Back view

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

Camera is positioned behind the runner. Set analysis_type=back_view.Produces:

Gait cycle analysis with stance phase means per leg
Pronation / supination per foot
Pelvic drop
Knee adduction
Step-by-step landing data with frame timestamps

See example videos for sample input and output videos of each analysis type.

Parameters

Parameter	Type	Required	Default	Description
`video`	file	Yes	—	Video file to analyze
`analysis_type`	string	Yes	`side_view`	`side_view` or `back_view`
`height`	number	No	1.70	Runner height in meters
`weight`	number	No	70	Runner weight in kilograms
`pace`	string	Conditional	—	Running pace `MM:SS`. Required when `treadmill=true`. Auto-calculated for overground running.
`language`	string	No	`en`	Result language: `en`, `fr`, `de`, `zh`, `ko`, `pt`, `es`, `it`, `ja`
`treadmill`	boolean	No	`false`	Whether the runner is on a treadmill
`subject_id`	string	No	—	Subject ID to link the analysis to. See subject management.

Lifecycle

Status progression

Status	HTTP code	Meaning
`pending`	200	Analysis is queued, waiting for a processing slot.
`analyzing`	202	Processing is underway. The `percentage` field shows progress.
`success`	200	Analysis is complete. Full results are available.
`failed`	400	Analysis 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, headers={"Authorization": f"Bearer {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 API keys and webhooks

Result levels

Once the status is success, you can access three levels of data:

Full results (GET /analysis/{id}/results)

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. Each segment’s texts object includes recap, consequences, and correction for both side view and back view (side view may also include coach_tips).Each biomechanical segment includes score_number, measured_value, and score ranges such as range_good, range_okay, and sometimes range_bad. measured_value and all range values are expressed in degrees. Range boundaries can overlap: for example, with range_good: [0, 102] and range_okay: [102, 111], values up to 102 are good and values strictly greater than 102 are okay.For side view, total_score is a weighted calculation, not a simple average of the segment scores.

Need to render a gauge or scale? See measurement scales for the full min/max boundaries and display recommendations for each segment.

Use this when you need a complete snapshot of the analysis.

Calculated data (GET /analysis/{id}/results/calculated_data)

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.

Raw data (GET /analysis/{id}/results/raw_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:

Error	Code	Status	When
File too large	`file_too_large`	413	Video exceeds 30 MB
Video too long	—	400	Video exceeds 10 seconds
Invalid file type	`invalid_file_type`	400	Unsupported extension (not MP4, MOV, AVI, or WEBM)
Not completed	—	400	Requesting calculated/raw data before `success`
Insufficient credits	`insufficient_api_credits`	424	No credits remaining
Not found	—	404	Invalid `analysis_id`

Getting started

Guides

Video requirements

Orientation

Analysis types

Parameters

Lifecycle

Status progression

Polling strategy

Webhooks (optional)

Result levels

Error handling

​Video requirements

​Orientation

​Analysis types

​Parameters

​Lifecycle

​Status progression

​Polling strategy

​Webhooks (optional)

​Result levels

​Error handling

Video requirements

Orientation

Analysis types

Parameters

Lifecycle

Status progression

Polling strategy

Webhooks (optional)

Result levels

Error handling