Admin Panel: Video Management and Model Training API

The endpoints documented here form the back-office API for Signia’s machine learning pipeline and sign video library. They sit under the /reconocimientos/admin-videos/ URL prefix and are intended for use from the admin panel UI. All endpoints are decorated with @csrf_exempt and follow a consistent {"ok": true/false, ...} JSON envelope.

These endpoints have no built-in authentication or authorisation checks in the view code — they are not protected by @login_required or any superuser guard. They must only be reachable from trusted networks. In production, Signia is deployed behind Railway’s HTTPS termination; ensure DEBUG=False and ALLOWED_HOSTS are configured correctly, and the admin routes are not publicly exposed without additional network-level protection.

Recognition Video Endpoints

These endpoints manage the raw training video library (VideoSeña model). Videos uploaded here are consumed by the training job — after a successful training run, all processed videos are automatically deleted from the database and disk.

Upload a recognition video

POST

string

/reconocimientos/admin-videos/reconocimiento/subir/

Stores a new sign video in the training dataset. The video is not processed immediately; it queues for the next training run triggered via /reconocimientos/admin-videos/entrenar/. Request body — multipart/form-data

label

string

required

The sign gloss this video represents (e.g. "HOLA", "GRACIAS"). Used as the class label during model training. Case is preserved but should be uppercase for consistency.

video

file

required

The video file containing the sign demonstration. Common formats (MP4, WebM, AVI) are supported. Files are stored under the media/ directory.

Response

boolean

true on success.

video

object

Show video object fields

integer

Database primary key of the newly created record.

label

string

The sign gloss label as stored.

creado

string

Creation timestamp formatted as DD/MM/YYYY HH:MM.

{
  "ok": true,
  "video": {
    "id": 12,
    "label": "HOLA",
    "creado": "15/06/2025 10:42"
  }
}

Error responses

Status	Condition
`400`	`label` or `video` field is missing from the request

Update a recognition video label

PUT

string

/reconocimientos/admin-videos/reconocimiento/editar/{video_id}/

Renames the label of an existing recognition video. Only the label is mutable; to replace the video file itself, delete the record and re-upload. Path parameters

video_id

integer

required

Primary key of the VideoSeña record to update.

Request body — application/json or application/x-www-form-urlencoded

label

string

required

The new sign gloss label. Must be a non-empty string.

Response

boolean

true on success.

label

string

The updated label as stored in the database.

{ "ok": true, "label": "BUENOS_DIAS" }

Error responses

Status	Condition
`400`	`label` is empty or missing
`404`	No `VideoSeña` record with the given `video_id`

Delete a recognition video

DELETE

string

/reconocimientos/admin-videos/reconocimiento/eliminar/{video_id}/

Permanently removes a recognition video record from the database and deletes the corresponding file from disk. Path parameters

video_id

integer

required

Primary key of the VideoSeña record to delete.

Response

boolean

true on success.

{ "ok": true }

Error responses

Status	Condition
`404`	No `VideoSeña` record with the given `video_id`

Translator Video Endpoints

These endpoints manage the sign video library that powers the text-to-LSC translator (VideoTraductor model). Unlike recognition videos, translator videos persist indefinitely and are looked up by nombre at translation time.

Upload a translator video

POST

string

/reconocimientos/admin-videos/traductor/crear/

Adds a new sign video to the translator vocabulary. The nombre field is the token that the LSC grammar layer will look up when translating Spanish text containing that sign. Request body — multipart/form-data

nombre

string

required

The token name for this sign (e.g. "HOLA", "POR_FAVOR"). Must be unique (case-insensitive). Duplicate names are rejected with HTTP 400.

video

file

required

The sign demonstration video file. Stored under media/ and served via the video_url field.

Response

boolean

true on success.

video

object

Show video object fields

integer

Database primary key of the new translator video record.

nombre

string

The token name as stored.

video_url

string

Relative URL to the stored video file (e.g. /media/videos/hola.mp4).

{
  "ok": true,
  "video": {
    "id": 7,
    "nombre": "HOLA",
    "video_url": "/media/videos/hola.mp4"
  }
}

Error responses

Status	Condition
`400`	`nombre` or `video` is missing, or a video with the same `nombre` already exists

Update a translator video

PUT

string

/reconocimientos/admin-videos/traductor/editar/{video_id}/

Updates the nombre, the video file, or both for an existing translator video. Fields that are omitted from the request body are left unchanged. Path parameters

video_id

integer

required

Primary key of the VideoTraductor record to update.

Request body — multipart/form-data

nombre

string

New token name. Optional — omit to leave the current name unchanged.

video

file

Replacement video file. Optional — omit to keep the existing file. When provided, the old file is deleted from disk before the new one is saved.

Response

boolean

true on success.

video

object

Show video object fields

integer

Database primary key of the updated record.

nombre

string

Token name after the update.

video_url

string

URL to the (possibly replaced) video file.

{
  "ok": true,
  "video": {
    "id": 7,
    "nombre": "HOLA",
    "video_url": "/media/videos/hola_v2.mp4"
  }
}

Error responses

Status	Condition
`404`	No `VideoTraductor` record with the given `video_id`

Delete a translator video

DELETE

string

/reconocimientos/admin-videos/traductor/eliminar/{video_id}/

Permanently removes a translator video record from the database and deletes the corresponding file from disk. Path parameters

video_id

integer

required

Primary key of the VideoTraductor record to delete.

Response

boolean

true on success.

{ "ok": true }

Error responses

Status	Condition
`404`	No `VideoTraductor` record with the given `video_id`

Model Training Endpoints

These endpoints control the RandomForest classifier that powers live sign recognition. Training is computationally intensive: it extracts MediaPipe landmarks from every queued VideoSeña record, generates up to 8 augmented variations per sample (noise, scale, speed, horizontal mirror, translation, etc.), then fits a 500-tree RandomForest with balanced class weights. The trained model and accumulated dataset are persisted to .pkl and .npy files on disk.

Training runs in a daemon thread inside the Django process. On Railway (single-dyno deployments), avoid restarting the dyno while {"activo": true}. After training completes, all source VideoSeña records are deleted from the database and disk automatically.

Trigger model training

POST

string

/reconocimientos/admin-videos/entrenar/

Starts the training job in a background thread and returns immediately. If training is already in progress, the request is rejected rather than queued — only one training job can run at a time. Poll /reconocimientos/admin-videos/entrenar/estado/ to track progress. Request body No body required. Response

boolean

true when training was successfully started; false if a job is already running.

error

string

Present only when ok is false. Describes why the request was rejected.

Success response (training started)

{ "ok": true }

Conflict response (already training)

{ "ok": false, "error": "Ya hay un entrenamiento en curso" }

Poll training status

GET

string

/reconocimientos/admin-videos/entrenar/estado/

Returns whether the background training thread is currently active. Poll this endpoint (e.g. every 2 seconds) after triggering a training run to know when it finishes. Response

activo

boolean

true while training is in progress; false when idle (whether training has never started, completed, or failed).

{ "activo": false }

List trained signs

GET

string

/reconocimientos/admin-videos/senas-entrenadas/

Returns all sign classes present in the current model along with a per-class effectiveness score. Effectiveness is derived from the leaf purity of the RandomForest: for each class, the server averages the dominant-class fraction across all decision-tree leaves that predominantly predict that class, then linearly rescales the results to the 55–99 % range for human readability. Response

boolean

true when a trained model is loaded; false when no model exists.

clases

array

Array of sign objects, sorted by efectividad descending.

Show sign object fields

clase

string

The sign gloss label (e.g. "HOLA").

efectividad

number

Effectiveness score in the 55–99 % range (one decimal place), derived from RandomForest leaf purity.

{
  "ok": true,
  "clases": [
    { "clase": "HOLA",    "efectividad": 97.2 },
    { "clase": "GRACIAS", "efectividad": 91.5 },
    { "clase": "BIEN",    "efectividad": 87.3 }
  ]
}

No model loaded

{ "ok": false, "clases": [] }

Remove a sign from the model

DELETE

string

/reconocimientos/admin-videos/sena/eliminar/{nombre}/

Removes all samples for the named sign from the accumulated .npy dataset, then synchronously retrains the RandomForest on the remaining data and saves the updated model. Unlike /entrenar/, this operation is not asynchronous — the response is returned only after the retrain completes. If removing the sign would leave no samples at all, the model, encoder, and dataset files are deleted entirely and the in-memory model is reset to None.

This endpoint retrains the model synchronously in the request thread. On large datasets this may take tens of seconds. Avoid calling it during peak traffic hours.

Path parameters

nombre

string

required

The exact sign gloss to remove (e.g. "HOLA"). Must match a label present in the accumulated dataset.

Response

boolean

true on success.

clases

array

Alphabetically sorted list of the sign glosses that remain in the retrained model.

{
  "ok": true,
  "clases": ["BIEN", "GRACIAS", "POR_FAVOR"]
}

Error responses

Status	Condition
`404`	The named sign was not found in the accumulated dataset, or no dataset files exist
`500`	Unhandled exception during retraining

Full Example: Uploading a Video and Training

The following Python script demonstrates a complete admin workflow: upload a recognition video, trigger training, and poll until the model is ready.

import requests
import time

session = requests.Session()

# 1. Upload a recognition video
with open('hola.mp4', 'rb') as f:
    response = session.post(
        'http://localhost:8000/reconocimientos/admin-videos/reconocimiento/subir/',
        data={'label': 'HOLA'},
        files={'video': f}
    )
print(response.json())
# {"ok": true, "video": {"id": 1, "label": "HOLA", "creado": "15/06/2025 11:00"}}

# 2. Trigger training
session.post('http://localhost:8000/reconocimientos/admin-videos/entrenar/')

# 3. Poll until training finishes
while True:
    status = session.get(
        'http://localhost:8000/reconocimientos/admin-videos/entrenar/estado/'
    ).json()
    if not status['activo']:
        print('Training complete.')
        break
    print('Still training…')
    time.sleep(2)

# 4. Verify trained signs
clases = session.get(
    'http://localhost:8000/reconocimientos/admin-videos/senas-entrenadas/'
).json()
print(clases)
# {"ok": true, "clases": [{"clase": "HOLA", "efectividad": 97.2}]}

Architecture

API Endpoints

Admin Panel: Video Management and Model Training API

Recognition Video Endpoints

Upload a recognition video

Update a recognition video label

Delete a recognition video

Translator Video Endpoints

Upload a translator video

Update a translator video

Delete a translator video

Model Training Endpoints

Trigger model training

Poll training status

List trained signs

Remove a sign from the model

Full Example: Uploading a Video and Training

Build docs developers (and LLMs) love

Architecture

API Endpoints

Documentation Index

​Recognition Video Endpoints

​Upload a recognition video

​Update a recognition video label

​Delete a recognition video

​Translator Video Endpoints

​Upload a translator video

​Update a translator video

​Delete a translator video

​Model Training Endpoints

​Trigger model training

​Poll training status

​List trained signs

​Remove a sign from the model

​Full Example: Uploading a Video and Training

Build docs developers (and LLMs) love

Recognition Video Endpoints

Upload a recognition video

Update a recognition video label

Delete a recognition video

Translator Video Endpoints

Upload a translator video

Update a translator video

Delete a translator video

Model Training Endpoints

Trigger model training

Poll training status

List trained signs

Remove a sign from the model

Full Example: Uploading a Video and Training