Create Analysis

Start a new analysis on an uploaded video.

Request

POST /videos/{video_id}/analysis

Path Parameters

Parameter	Type	Required	Description
`video_id`	integer	Yes	The video ID to analyze

Request Body

The request body is optional. Default parameters are used if not provided.

{
  "fps": 25
}

Prerequisites

Before creating an analysis:

Video duration must be at least 10 minutes
You must have permission to access the video

The video does not need to be available yet — you can create an analysis immediately after creating the video. The analysis remains in the waiting_for_video status until the video is ready, then starts automatically.

Response

{
  "data": {
    "id": 1247,
    "video_id": 789,
    "status": "init",
    "algorithm_version": "0.4.98",
    "parameters": {
      "fps": 25
    },
    "created_at": "2025-01-16T14:35:00Z",
    "results_available": false,
    "progress": 0,
    "video": {
      "id": 789,
      "title": "Team A vs Team B"
    }
  }
}

Response Fields

Field	Type	Description
`id`	integer	Analysis ID
`video_id`	integer	Associated video ID
`status`	string	Processing status
`algorithm_version`	string	Algorithm version used
`parameters`	object	Analysis parameters
`results_available`	boolean	True when results can be queried
`progress`	number	Estimated completion (0-100)
`video`	object	Video metadata

Analysis Status

Analyses progress through these statuses:

Status	Description
`init`	Analysis created, initializing
`waiting_for_video`	Waiting for video to be ready
`running`	Actively processing video
`done`	Complete, results available
`error`	Processing failed
`ignored`	Analysis was ignored and will not be processed
`no_match_detected`	No soccer match was detected in the video; the analysis will not run
`needs_attention`	Processing paused, pending manual review

Example

cURLPythonJavaScript

curl -X POST "https://aiontheball.nl/api/v1/videos/789/analysis" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{}'

import requests

# Create analysis
response = requests.post(
    f'https://aiontheball.nl/api/v1/videos/{video_id}/analysis',
    headers={'Authorization': f'Bearer {token}'},
    json={}
)
analysis = response.json()['data']
print(f"Created analysis {analysis['id']}")

const response = await fetch(`https://aiontheball.nl/api/v1/videos/${videoId}/analysis`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({})
});
const { data: analysis } = await response.json();
console.log(`Created analysis ${analysis.id}`);

Monitoring Progress

After creating an analysis, either use webhooks to receive updates, or poll the Get Analysis endpoint to monitor progress.

Complete Workflow

Here's a complete example of uploading a video and creating an analysis:

import time
import requests

BASE_URL = 'https://aiontheball.nl/api/v1'
TOKEN = 'YOUR_API_TOKEN'

headers = {
    'Authorization': f'Bearer {TOKEN}',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

# 1. Create video
video_response = requests.post(
    f'{BASE_URL}/videos',
    headers=headers,
    json={
        'video_file_url': 'https://example.com/match.mp4',
        'title': 'Team A vs Team B',
        'home_team_name': 'Team A',
        'away_team_name': 'Team B'
    }
)
video = video_response.json()['data']
print(f"Created video {video['id']}")

# 2. Create analysis (no need to wait for the video —
#    the analysis waits in `waiting_for_video` until the video is ready)
analysis_response = requests.post(
    f"{BASE_URL}/videos/{video['id']}/analysis",
    headers=headers,
    json={}
)
analysis = analysis_response.json()['data']
print(f"Created analysis {analysis['id']}")

# 3. Wait for analysis to complete
while True:
    response = requests.get(
        f"{BASE_URL}/analyses/{analysis['id']}",
        headers=headers
    )
    analysis = response.json()['data']

    if analysis['status'] == 'done':
        print("Analysis complete!")
        break
    elif analysis['status'] == 'error':
        raise Exception('Analysis failed')

    print(f"Analysis status: {analysis['status']}, progress: {analysis.get('progress', 0)}%")
    time.sleep(30)

# 4. Fetch results
events = requests.get(
    f"{BASE_URL}/analyses/{analysis['id']}/events",
    headers=headers
).json()

print(f"Found {len(events)} events")

Error Responses

Status	Description
400	Video too short
401	Authentication required
403	No permission to access video
404	Video not found

{
  "message": "Video must be at least 10 minutes long"
}