Hochladen von Videos über die API

Das Hochladen von Videos ist der entscheidende erste Schritt im AiKYNETIX Video-Upload- und Verarbeitungs-Workflow.

Überblick

Die AiKYNETIX-API ermöglicht es sowohl regulären Benutzern als auch Administratoren, Videoverarbeitungssitzungen zu initiieren. Ob Sie für eine persönliche Analyse hochladen oder im Namen eines anderen Benutzers handeln, die API bietet dedizierte Endpunkte für jeden Aktivitätstyp (Laufen, Springen und Gewichtheben). Sobald ein Video hochgeladen ist, erstellt das System eine Sitzungsressource, die die Verarbeitungspipeline auslöst.

Voraussetzungen

Stellen Sie vor dem Hochladen eines Videos sicher, dass Sie Folgendes haben:

• Gültige API-Zugangsdaten: Alle Anfragen müssen einen gültigen Token im API-KEY-Header enthalten. Zum Beispiel:

API-KEY: <YOUR_API_TOKEN>

• Entsprechende Berechtigungen:

  • Reguläre Benutzer: Können Videos direkt hochladen, um ihre eigene Sitzung zu erstellen.

  • Administratoren/Sub-Admins: Können im Namen eines anderen Benutzers hochladen. In diesen Fällen muss die Anfrage einen zusätzlichen user_id-Parameter enthalten.

• Multipart/Form-Data-Format: Video-Uploads erfolgen über eine multipart/form-data POST-Anfrage. Ihre Anfrage sollte die rohe Videodatei sowie alle zusätzlichen Parameter enthalten, die vom Endpunkt benötigt werden.

---

Überblick über die Upload-Endpunkte

Verwenden Sie je nach Aktivitätstyp und Benutzerrolle einen der folgenden Endpunkte:

Laufsitzungen

• Upload für reguläre Benutzer: Endpunkt: POST /running/sessions/ Parameter:

  • video (Datei, erforderlich): Die zu verarbeitende Videodatei.

  • session_name (String, optional): Ein benutzerdefinierter Titel für die Sitzung.

  • incline_degree (String/Nummer, optional): Gibt die Neigung des Laufbands an (falls zutreffend).

• Admin-Upload (im Namen eines anderen Benutzers): Endpunkt: POST /running/management/sessions/ Parameter:

  • user_id (String, erforderlich): Die ID des Benutzers, für den diese Sitzung erstellt wird.

  • video (Datei, erforderlich)

  • session_name (String, optional)

  • incline_degree (String/Nummer, optional)

Sprungsitzungen

• Upload für reguläre Benutzer: Endpunkt: POST /jumping/sessions/ Parameter:

  • video (Datei, erforderlich)

  • session_name (String, optional)

  • incline_degree (String/Nummer, optional)

• Admin-Upload (im Namen eines anderen Benutzers): Endpunkt: POST /jumping/management/sessions/ Parameter:

  • user_id (String, erforderlich)

  • video (Datei, erforderlich)

  • session_name (String, optional)

  • incline_degree (String/Nummer, optional)

Gewichthebungssitzungen

• Upload für reguläre Benutzer: Endpunkt: POST /weightlifting/sessions/ Parameter:

  • video (Datei, erforderlich)

  • exercise_name (String, erforderlich): Muss entweder snatch, clean oder clean_and_jerk sein.

  • session_name (String, optional)

  • barbell_mass (String, optional): Gewicht der Hantel. Wenn nicht angegeben, wird ein Standardwert von 100 kg (oder 220 lb) zugewiesen.

• Admin-Upload (im Namen eines anderen Benutzers): Endpunkt: POST /weightlifting/management/sessions/ Parameter:

  • user_id (String, erforderlich)

  • video (Datei, erforderlich)

  • exercise_name (String, erforderlich)

  • session_name (String, optional)

  • barbell_mass (String, optional)

---

Anfrage-Payload & Multipart/Form-Data-Anforderungen

Stellen Sie beim Erstellen Ihrer Upload-Anfrage sicher, dass Sie:

• Den Content-Type-Header auf multipart/form-data setzen.

• Die Videodatei als binäres Feld einfügen.

• Zusätzliche Parameter als Formularfelder übergeben:

  • Für Admin-initiierte Uploads fügen Sie das user_id-Feld hinzu.

  • Für Gewichthebungssitzungen fügen Sie exercise_name (und optional barbell_mass) hinzu.

  • Optional fügen Sie einen beschreibenden session_name hinzu, um Ihre Sitzung zu identifizieren.

Beispiel-cURL-Befehl (Admin-Upload für eine Sprungsitzung)

curl -X POST \
     -H 'Content-Type: multipart/form-data' \
     -H 'API-KEY: <YOUR_ADMIN_TOKEN>' \
     -F 'user_id=someUserId123' \
     -F 'video=@/path/to/video.mp4' \
     -F 'session_name=Custom Jump Session' \
     -F 'incline_degree=5' \
     https://aikpy-nsz2.onrender.com/jumping/management/sessions/

---

Workflow-Abfolge

1. Authentifizierung: Der Client sendet die Anfrage mit einem gültigen API-KEY-Token. Für Admin-Uploads wird zusätzlich die user_id angegeben.

2. Datei-Upload & Sitzungserstellung: Die Videodatei wird zusammen mit zusätzlichen Formulardaten an den Server übertragen. Die API erstellt dann eine neue Verarbeitungssitzung für das Video.

3. Serverantwort: Bei Erfolg antwortet die API mit einem JSON-Objekt, das Folgendes enthält:

   • session_id: Ein eindeutiger Identifikator für die neue Sitzung.

   • title: Der Sitzungstitel (entweder benutzerdefiniert oder ein Standardwert).

4. Nächste Schritte: Die zurückgegebene session_id kann verwendet werden, um:

   • Den Verarbeitungsstatus abzufragen.

   • Das analysierte Video abzurufen.

   • Detaillierte Sitzungsmetriken und Analyseberichte über nachfolgende API-Aufrufe abzurufen.

---

Umgang mit der Antwort

Eine erfolgreiche Upload-Antwort ähnelt dem folgenden JSON:

{
  "session_id": "abcd1234efgh5678",
  "title": "Custom Session"
}

Falls der Upload aufgrund fehlender Felder, eines ungültigen Tokens oder unzureichender Berechtigungen fehlschlägt, enthält die Antwort ein error-Feld mit einer entsprechenden Nachricht

Hinweis: Für Details zu Parametern, Anfrage-/Antwortformaten und Fehlerbehandlung siehe die entsprechenden Abschnitte in unserer API-Referenz.