Listening

El motor no genera ni transcribe audio. El cliente provee audioUrl, transcript y questions ya resueltos (por ejemplo, ejecutando su propio pipeline de Speech-to-Text antes de llamar a esta API — ver Integración STT recomendada).

Forma del contenido

{
  "audioUrl": "https://cdn.example.com/audio/lesson-12.mp3",
  "transcript": "John lives in London and works as a teacher.",
  "title": "Where does John live?",
  "durationSeconds": 34,
  "questions": [
    {
      "id": "q1",
      "type": "multiple_choice",
      "question": "Where does John live?",
      "options": ["Paris", "London", "Madrid"],
      "correctAnswer": "London"
    }
  ]
}

title y durationSeconds son opcionales. Solo se soportan preguntas multiple_choice por ahora.

Crear (validar + sanear)

POST /exercises

{
  "type": "listening_multiple_choice",
  "content": { "...como arriba, con correctAnswer..." }
}

Respuesta (correctAnswer eliminado de cada pregunta — el cliente debe conservar el contenido original para evaluarlo despues):

{
  "id": "generated-uuid",
  "type": "listening_multiple_choice",
  "group": "LISTENING",
  "subgroup": "MULTIPLE_CHOICE",
  "content": {
    "audioUrl": "https://cdn.example.com/audio/lesson-12.mp3",
    "transcript": "John lives in London and works as a teacher.",
    "title": "Where does John live?",
    "durationSeconds": 34,
    "questions": [
      { "id": "q1", "type": "multiple_choice", "question": "Where does John live?", "options": ["Paris", "London", "Madrid"] }
    ]
  },
  "metadata": { "difficulty": "easy", "tags": [], "language": "en" }
}

Devuelve 400 si audioUrl falta/es invalida, transcript esta vacio, questions esta vacio, un correctAnswer no esta en sus options, o hay ids/opciones duplicadas.

Evaluar

POST /exercises/evaluate

El motor es stateless hoy — no guarda el ejercicio creado arriba. Reenvia el content completo, incluido correctAnswer:

{
  "exerciseId": "ex_001",
  "area": "listening",
  "type": "listening_multiple_choice",
  "content": { "...ListeningContent completo, con correctAnswer..." },
  "answer": "{\"q1\":\"London\"}"
}

{
  "correct": true,
  "score": 10,
  "feedback": "Correct! You understood the audio.",
  "metadata": { "area": "listening", "type": "listening_multiple_choice" }
}

Ver ADR 0001 para entender por que el contrato funciona asi hoy y como evolucionara.