Referencia de la API · v1

Entrenamientos

Entrenar por API en XEYE: estimar el precio, relanzar una lista, sondear el estado hasta completed y elegir el modelo de embedding.

Actualizado el 14 de octubre de 2026

Cómo funciona un entrenamiento

Entrenar calcula los embeddings de todos los elementos de la lista (y, si la lista lo permite, genera descripciones con IA para los que no las tienen) y deja ese modelo en uso para la búsqueda. Lo lanzas tú: las ediciones solo dejan un entrenamiento pendiente por lista. Consume crédito; la estimación te dice cuánto antes de lanzar.

Estados

Estado	Significado
pending	Hay cambios sin entrenar; esperando a que lo lances.
queued	Lanzado, en la cola (queue_position = 1 es el siguiente).
initialized	Entregado al worker; arrancando.
optimizing	Generando descripciones con IA (si procede).
training	Calculando embeddings.
completed	Terminado: el modelo está en uso (in_use) y la búsqueda ya lo sirve.
failed	Falló o se estancó; error dice por qué. El crédito se devuelve y la lista sigue pendiente.

Si el saldo no alcanza, lanzar responde 402 INSUFFICIENT_CREDIT con details.required y details.balance, y el pendiente se conserva. Recarga crédito desde la consola.

Endpoints

Estimar el precio

GEThttps://api.xeye.es/v1/lists/{listId}/trainings/estimateÁmbito: trainings:read

Precio de lanzar ahora: fijo más el enriquecimiento de los elementos sin descripción cacheada; sufficient indica si el saldo alcanza.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
regenerate_descriptions	query	boolean	no	Regenerar las descripciones con IA de todos los elementos aunque estén cacheadas (más caro). Por defecto false.
no_descriptions	query	boolean	no	Entrenar sin descripciones con IA; gana a regenerate_descriptions y es lo más barato. Por defecto false.

Petición

bash

curl -X GET https://api.xeye.es/v1/lists/42/trainings/estimate \
  -H "X-API-Key: $XEYE_API_KEY"

Respuesta

200 OK · application/json

{
  "descriptions_to_generate": 250,
  "fixed": 0.3,
  "enrichment": 1.325,
  "total": 1.625,
  "balance": 5.0,
  "sufficient": true
}

Reentrenar la lista

POSThttps://api.xeye.es/v1/lists/{listId}/trainingsÁmbito: trainings:write

Encola el entrenamiento de la lista (reutiliza el pendiente o crea uno) y cobra su precio. La respuesta trae el run tal como queda; sondea GET /trainings/{id} hasta completed o failed.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
embedding_model	cuerpo	string	no	Uno de GET /trainings/embedding-models; ausente = el por defecto.
regenerate_descriptions	cuerpo	boolean	no	Regenerar las descripciones con IA de todos los elementos aunque estén cacheadas (más caro). Por defecto false.
no_descriptions	cuerpo	boolean	no	Entrenar sin descripciones con IA; gana a regenerate_descriptions y es lo más barato. Por defecto false.

Petición

bash

curl -X POST https://api.xeye.es/v1/lists/42/trainings \
  -H "X-API-Key: $XEYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "no_descriptions": false
  }'

Respuesta

200 OK · application/json

{
  "id": 310,
  "list_id": 42,
  "status": "queued",
  "embedding_model": "intfloat/multilingual-e5-small",
  "element_count": 250,
  "described_count": null,
  "in_use": false,
  "has_embeddings": false,
  "usable": false,
  "queue_position": 1,
  "error": null,
  "cost": { "fixed": 0.3, "enrichment": 1.325, "total": 1.625 },
  "time": null,
  "last_heartbeat_at": null,
  "created_at": "2026-10-14T09:20:00Z",
  "updated_at": "2026-10-14T09:20:00Z"
}

Estado de un entrenamiento

GEThttps://api.xeye.es/v1/trainings/{id}Ámbito: trainings:read

Estado de un entrenamiento. Es el endpoint de sondeo: cada pocos segundos basta.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
id	ruta	integer	sí	Id del entrenamiento.

Petición

bash

curl -X GET https://api.xeye.es/v1/trainings/310 \
  -H "X-API-Key: $XEYE_API_KEY"

Respuesta

200 OK · application/json

{
  "id": 310,
  "list_id": 42,
  "status": "completed",
  "embedding_model": "intfloat/multilingual-e5-small",
  "element_count": 250,
  "described_count": 250,
  "in_use": true,
  "has_embeddings": true,
  "usable": true,
  "queue_position": null,
  "error": null,
  "cost": { "fixed": 0.3, "enrichment": 1.325, "total": 1.625 },
  "time": { "optimizing_seconds": 12, "training_seconds": 95, "total_seconds": 107 },
  "last_heartbeat_at": null,
  "created_at": "2026-10-14T09:20:00Z",
  "updated_at": "2026-10-14T09:20:00Z"
}

Historial de entrenamientos

GEThttps://api.xeye.es/v1/lists/{listId}/trainingsÁmbito: trainings:read

Historial de la lista, los más recientes primero.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
offset	query	integer	no	Primer elemento de la página, desde 0.
limit	query	integer	no	Tamaño de página, de 1 a 200 (50 por defecto).

Petición

bash

curl -X GET https://api.xeye.es/v1/lists/42/trainings \
  -H "X-API-Key: $XEYE_API_KEY"

Respuesta

200 OK · application/json

{
  "items": [ {
      "id": 310,
      "list_id": 42,
      "status": "queued",
      "embedding_model": "intfloat/multilingual-e5-small",
      "element_count": 250,
      "described_count": null,
      "in_use": false,
      "has_embeddings": false,
      "usable": false,
      "queue_position": 1,
      "error": null,
      "cost": { "fixed": 0.3, "enrichment": 1.325, "total": 1.625 },
      "time": null,
      "last_heartbeat_at": null,
      "created_at": "2026-10-14T09:20:00Z",
      "updated_at": "2026-10-14T09:20:00Z"
    } ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

Lanzar un entrenamiento pendiente

POSThttps://api.xeye.es/v1/trainings/{id}/launchÁmbito: trainings:write

Lanza un entrenamiento concreto en estado pending (equivale a relanzar la lista cuando ya conoces su id).

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
id	ruta	integer	sí	Id del entrenamiento.
embedding_model	cuerpo	string	no	Uno de GET /trainings/embedding-models; ausente = el por defecto.
regenerate_descriptions	cuerpo	boolean	no	Regenerar las descripciones con IA de todos los elementos aunque estén cacheadas (más caro). Por defecto false.
no_descriptions	cuerpo	boolean	no	Entrenar sin descripciones con IA; gana a regenerate_descriptions y es lo más barato. Por defecto false.

Petición

bash

curl -X POST https://api.xeye.es/v1/trainings/310/launch \
  -H "X-API-Key: $XEYE_API_KEY"

Respuesta

200 OK · application/json

{
  "id": 310,
  "list_id": 42,
  "status": "queued",
  "embedding_model": "intfloat/multilingual-e5-small",
  "element_count": 250,
  "described_count": null,
  "in_use": false,
  "has_embeddings": false,
  "usable": false,
  "queue_position": 1,
  "error": null,
  "cost": { "fixed": 0.3, "enrichment": 1.325, "total": 1.625 },
  "time": null,
  "last_heartbeat_at": null,
  "created_at": "2026-10-14T09:20:00Z",
  "updated_at": "2026-10-14T09:20:00Z"
}

Modelos de embedding

GEThttps://api.xeye.es/v1/trainings/embedding-modelsÁmbito: trainings:read

Modelos de embedding admitidos en embedding_model. El primero es el que se usa si no indicas ninguno.

Petición

bash

curl -X GET https://api.xeye.es/v1/trainings/embedding-models \
  -H "X-API-Key: $XEYE_API_KEY"

Respuesta

200 OK · application/json

{
  "models": ["intfloat/multilingual-e5-small", "intfloat/multilingual-e5-base"],
  "default_model": "intfloat/multilingual-e5-small"
}

Una lista solo admite un entrenamiento en cola o en marcha a la vez: un segundo lanzamiento responde 409 CONFLICT hasta que termine el primero. La lista debe tener elementos (400 si está vacía).

Sondea cada 5–10 segundos: un entrenamiento tarda desde menos de un minuto hasta varios, según el tamaño de la lista y las descripciones a generar. No repitas el POST si no recibes respuesta: consulta antes el historial.

Siguiente: Búsqueda