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:

1. Video status must be available
2. Video duration must be at least 10 minutes
3. You must have permission to access the video

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
aggregating	Combining segment results
done	Complete, results available
error	Processing failed

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. Wait for video to be available
while True:
    response = requests.get(
        f"{BASE_URL}/videos/{video['id']}",
        headers=headers
    )
    video = response.json()['data']

    if video['status'] == 'available':
        print("Video ready!")
        break
    elif video['status'] == 'error':
        raise Exception('Video processing failed')

    print(f"Video status: {video['status']}")
    time.sleep(10)

# 3. Create analysis
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']}")

# 4. 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)

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

print(f"Found {len(events.get('data', []))} events")

Error Responses

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

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