Preguntas Frecuentes

¿Dónde puedo encontrar detalles sobre el uso de la API y los endpoints?

Consulte la sección de endpoints de la API en nuestra documentación para obtener información detallada.

¿Qué configuraciones de red y certificados se requieren?

La autenticación es token-based. Puede encontrar todos los detalles sobre el nombre de host y cómo usar la API en nuestra documentación.

Ejemplo:

curl -X POST 'https://api.elsanow.io/api/v1/score_audio_plus' \
     -H 'Content-Type: multipart/form-data' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer <TOKEN>' \
     -F 'api_plan="premium"' \
     -F 'return_json="true"' \
     -F 'audio_file=@"/path/to/file"'

Hay ejemplos adicionales disponibles en la sección de API de la documentación.

¿Cómo obtengo y uso la clave o token de API?

El API token será generado por nosotros una vez que se firme el NDA. Por favor, infórmenos cuando esto esté completado y le proporcionaremos el token. Las instrucciones de uso están descritas en la documentación.

¿Cuál es la estructura y los límites de las solicitudes y respuestas de la API?

Puede encontrar estructuras detalladas de solicitudes y respuestas, incluidos parameters y limitations, en la documentación de la API.

¿Hay un entorno sandbox disponible y necesito una cuenta de prueba?

Actualmente no ofrecemos un entorno de staging.

¿Hay un panel de control o registros para monitoreo y depuración?

Hay un panel de control customer-facing disponible para proporcionar visibilidad sobre las solicitudes y la actividad. Esta interfaz basada en Retool permite a los usuarios hacer seguimiento de su uso tanto para llamadas de API API con guión como sin guión.

¿Nuestra API admite actualmente, o puede integrarse con, una solución RAG?

Aunque nuestra API no implementa una solución RAG (Retrieval-Augmented Generation) de forma nativa, ciertamente puede integrarse en flujos de trabajo RAG. Nuestros servicios se centran en el análisis de flujos de audio, y los resultados pueden usarse como entrada para sistemas RAG u otras canalizaciones que se beneficien de un contexto enriquecido derivado del audio. Para proporcionar una respuesta más personalizada o sugerir un enfoque de integración óptimo, comparta más detalles sobre el caso de uso previsto por el cliente o su arquitectura.

¿Qué ancho de banda se necesita para las funciones de habla con IA sin interrupciones?

Por ahora, los únicos requisitos relacionados con el ancho de banda que proporcionamos son los indicados en nuestra documentación de la API. Estos aplican independientemente de cómo se utilicen o integren las funciones de habla con IA. Si puede compartir un poco más sobre su caso de uso específico, estaremos encantados de dar una recomendación más precisa.

¿Es posible identificar desde qué dirección IP se envió cada fragmento?

En este momento, no conservamos ninguna información sobre el origen de las solicitudes de API, como las direcciones IP. Esto significa que no podemos determinar desde qué IP se envió cada fragmento. Nuestros registros se centran en los metadatos de la solicitud relevantes para la funcionalidad del servicio, pero no incluyen detalles de red a nivel origin-level.

¿Cuáles son los parámetros de la sección de respuesta "utterance"?

Los parámetros de la sección de respuesta utterance son:

nativeness_score: La puntuación de naturalidad obtenida por el usuario para la enunciación completa, en una escala de 0–100.
nativeness_score_partial: Esta puntuación refleja la naturalidad del usuario en el subconjunto de palabras que realmente pronunció, con una puntuación mínima de 25%.
decision: Una cadena que indica el nivel de competencia del usuario al pronunciar la enunciación, basada en nativeness_score. Valores posibles: correct, almost_correct o incorrect.

Nota: Mientras que nativeness_score considera todas las palabras en la enunciación (incluidas las que el usuario no dijo), nativeness_score_partial se enfoca únicamente en las palabras pronunciadas por el usuario, incluso si tienen una puntuación baja.

Ejemplo: Si la enunciación es "Hello ELSA" y el usuario solo dice "Hello," nativeness_score_partial considerará únicamente la puntuación de "Hello" (asumiendo que supera el 25%), mientras que nativeness_score tendrá en cuenta todas las palabras, incluyendo las no pronunciadas (p. ej., "ELSA," con una puntuación baja o cero).

Para más detalles, consulte la documentación de la API.

¿Cuáles son los parámetros de la sección de respuesta "words"?

Los parámetros de la sección de respuesta words son:

nativeness_score: La puntuación de naturalidad (0–100) para la pronunciación de la palabra individual.
decision: Evaluación de competencia basada en nativeness_score, con valores posibles de correct, almost_correct o incorrect.

Para más detalles, consulte la documentación de la API.

¿Cuáles son los parámetros de la sección de respuesta "word_stress"?

Los parámetros de la sección de respuesta word_stress son:

decision: Indica si el usuario enfatizó correctamente la sílaba, con valores posibles correct o incorrect.

Para más detalles, consulte la documentación de la API.

¿Cuáles son los parámetros de la sección de respuesta "phonemes"?

Los parámetros de la sección de respuesta phonemes son:

nativeness_score: La puntuación para los fonemas en esta entrada, en una escala de 0–100.
decision: Indica la precisión de la pronunciación del fonema, con valores posibles correct, warning o error.

Para más detalles, consulte la documentación de la API.

Cómo funciona el cálculo de fragmentos

Un fragmento tiene una duración de 15 seconds. Sin embargo, el número real de fragmentos se calcula usando la fórmula:

num_chunks = ceil(duration / chunk_size)

Así, por ejemplo, una entrada de audio de 17-second da como resultado 2 fragmentos (no 1.13), debido a la operación de techo.

Además:

Si la duración total supera ligeramente la duración máxima permitida por la API, se trunca para ajustarse a los límites. Esto evita que se genere una segunda solicitud por tan solo unos pocos fotogramas adicionales.
También eliminamos el silencio y el ruido al inicio o al final del audio cuando corresponde, lo que puede afectar aún más el recuento final de fragmentos.

Estos factores explican por qué num_standard_chunks puede no coincidir exactamente con num_secs / 15.

¿Cómo detecta Speech Analyzer los errores gramaticales?

Detectamos errores gramaticales, pero solo corregimos aquellos en los que tenemos una alta confianza en el contexto. Específicamente, una corrección propuesta debe tener al menos un puntaje de confianza de 80% antes de ser aplicada. Este enfoque garantiza que evitemos sugerir cambios irrelevantes en casos de ambigüedad gramatical.

¿Cuáles son los límites máximos de carga de archivos de audio?

Bytes

El tamaño máximo de archivo permitido para la carga es de 100MB. Si necesita cargar archivos de mayor tamaño, comuníquese con nuestro equipo de soporte para obtener ayuda.

Minutos

La duración máxima del archivo de audio para solicitudes sin guión con el indicador sync configurado en True permitida para la carga es de 15 minutes.

Con guión: Sin límite
Sin guión:
- sync = True => 15 minutos
- sync = False => 12 minutos

¿Están relacionadas las puntuaciones de pronunciación y entonación?

No existe una dependencia directa entre pronunciation_score e intonation_score. Sin embargo, normalmente solo calculamos el intonation_score para entradas más largas, como oraciones completas. Como resultado, los usuarios que son principiantes absolutos y tienden a producir enunciaciones muy cortas o incompletas pueden no recibir un intonation_score. Esto puede dar la impresión de que hay una relación, pero refleja más bien la longitud y calidad de la entrada que una dependencia entre las puntuaciones en sí.

¿Cómo se evalúan las decisiones de pronunciación y entonación?

Estos atributos de decisión se basan en las puntuaciones correspondientes de nivel CEFR-level (p. ej., pronunciation_cefr, intonation_cefr). Un ejemplo de mapeo es el siguiente:

Correcto: Nivel CEFR C1 o C2
Advertencia: Nivel CEFR B1 o B2
Incorrecto: Nivel CEFR A1 o A2

¿Por qué algunas llamadas de API sin guión no tienen puntuaciones EPS o transcripciones?

Para obtener resultados con métricas, asegúrese de que la duración del audio supere los 20 seconds.

¿El nivel de pronunciación está mapeado a un acento nativo de EE. UU./Reino Unido?

Nos adherimos a estándares globales (CEFT, IELTS, TOEFL), donde no penalizamos a las personas por hablar con su acento nativo, sino que nos centramos en la claridad del habla. Aunque puede haber ligeras variaciones para usuarios con acentos más marcados, las diferencias suelen permanecer dentro de la misma banda.

¿Por qué faltan métricas de gramática y vocabulario en los resultados de la API sin guión?

Estas métricas tienen un umbral mínimo. Si desea obtener resultados para las métricas de gramática y vocabulario en la API sin guión a pesar de este umbral mínimo, simplemente añada el indicador -F force_grammar_vocab=True. Sin embargo, es importante tener en cuenta que estos resultados pueden no ser tan precisos como los que cumplen con el umbral mínimo.

¿Qué estándar usamos para la explicabilidad?

Nuestros modelos son propietarios y no divulgamos las arquitecturas exactas ni los mecanismos internos. Si bien priorizamos la transparencia en términos de calidad de salida y benchmarks de rendimiento, actualmente no seguimos un estándar público para la explicabilidad del modelo.

¿Cómo calculamos la puntuación general?

La puntuación general es una combinación de las cinco métricas: pronunciation, intonation, fluency, grammar y vocabulary. En ocasiones, si no proporcionamos puntuaciones de vocabulario o gramática porque la grabación fue corta, aún podemos proporcionar una puntuación general basada en las otras métricas disponibles.

¿Cómo se calcula la puntuación?

La forma en que calculamos el ELSA Score y lo mapeamos a IELTS se desarrolla internamente. Los parámetros para calcular la puntuación de ELSA pueden cambiar con el tiempo, y también puede hacerlo el mapeo a IELTS. De vez en cuando lo reevaluamos y lo ajustamos ligeramente.

¿Cómo se ponderan el rango gramatical y los errores en la puntuación de Gramática?

La proporción de estos aspectos depende del tipo de grabación. Para el habla casual, es aproximadamente un 60% de errores gramaticales y un 40% de rango gramatical; para entornos similares a exámenes, es aproximadamente un 50% de errores gramaticales y un 50% de rango gramatical. Es importante señalar que estos números son ajustados cuando tenemos nuevos datos.

¿Cómo calculamos la puntuación de pronunciación?

La puntuación de pronunciación se basa en qué tan precisamente pronuncia los sonidos del inglés en cada palabra que fue reconocida por ELSA en su grabación. El número y la gravedad de las pronunciaciones incorrectas resaltadas contribuirán a la puntuación de pronunciación.

¿Cómo calculamos la puntuación de fluidez?

La puntuación de Fluidez es una combinación de su desempeño en Pace, Pausing y Hesitations. Mantener un buen ritmo, hacer pausas solo en lugares naturales y reducir la cantidad de palabras de relleno y repeticiones contribuirá a una buena puntuación de Fluidez.

¿Cómo calculamos la puntuación de entonación?

La puntuación de intonation tiene en cuenta las subidas y bajadas en su tono y qué tan bien enfatizó las palabras dentro de las oraciones.

¿Cómo calculamos la puntuación de vocabulario?

La puntuación de Vocabulary se basa principalmente en los niveles CEFR levels estimados de las palabras y expresiones en el habla del usuario.

Nota: Mostramos la distribución CEFR raw como retroalimentación (porcentaje de palabras en cada nivel A1-C2), pero la puntuación general se calcula mediante un algoritmo estadístico que mapea esta distribución a un valor de 0-100 (donde 100% corresponde a un uso de vocabulario similar al nativo). La puntuación de vocabulary solo se devuelve si el texto tiene (actualmente) 75 words o más.

¿Cómo calculamos la puntuación de gramática?

La puntuación de grammar se calcula basándose en los resultados del módulo de detección y corrección de errores gramaticales combinado con el rango gramatical identificado. La detección y corrección de errores gramaticales identifica errores gramaticales en el texto y genera la puntuación de error. El módulo de rango gramatical identifica todas las estructuras gramaticales y calcula la puntuación de rango basándose en las 5 estructuras de mayor nivel utilizadas con éxito en la grabación. La puntuación de grammar solo se devuelve si el texto tiene (actualmente) 50 words o más.

¿Cuál es el volumen y la diversidad de los datos de entrenamiento?

Si bien no divulgamos los detalles de implementación o las estructuras internas de nuestros modelos, estamos comprometidos a garantizar que los resultados sean interpretables y estén alineados con las expectativas del usuario. Cuando corresponde, proporcionamos score breakdowns o retroalimentación a nivel category-level que reflejan la lógica de evaluación del modelo de manera transparente y accionable para el usuario final. Internamente, seguimos prácticas de validación sólidas y evaluamos el rendimiento de referencia para garantizar la coherencia y la equidad en las decisiones del modelo.

¿Qué tan precisos son los modelos y con qué frecuencia se reentrenan?

Históricamente no hemos compartido cifras detalladas de precisión públicamente. En cambio, típicamente hemos comunicado que nuestros modelos superan a los competidores según nuestros benchmarks internos. En cuanto a la model retraining frequency, varía significativamente según el modelo. Si bien algunos modelos han permanecido sin cambios durante períodos prolongados, nuestro enfoque general ha sido consistentemente recopilar datos de usuarios (where permitted) y mejorar iterativamente el rendimiento del modelo a lo largo del tiempo.

¿Cuál es el riesgo de sesgo o discriminación?

La IA de ELSA está diseñada específicamente para apoyar a hablantes de inglés non-native. Al entrenar con miles de horas de inglés con acento, proveniente de hablantes reales de segunda lengua (L2), ELSA está en una posición única para reconocer y abordar los desafíos de pronunciación de los estudiantes. Este enfoque inclusivo ayuda a reducir el sesgo de acento y garantiza que los estudiantes se sientan reconocidos, apoyados y empoderados desde el primer día.

¿Cuál es el peso de la "entonación" en el modelo y cómo se aborda éticamente?

Ya sea que el contenido sea scripted o unscripted, la tasa de detección es de aproximadamente 20%.

En cuanto a la pregunta sobre cómo manejar esto de forma ethically, es posible que la preocupación esté relacionada con el potencial de detectar patrones de habla individuales o los riesgos en torno a la suplantación de voz.

Para aclarar: Nuestros sistemas de análisis de habla y entonación están diseñados para ser agnostic a cualquier característica identificable de la voz de un usuario. No realizamos identificación de hablantes, ni usamos datos de audio para ese propósito. Nuestro enfoque permanece exclusivamente en la evaluación de la pronunciación y la prosodia en el contexto del aprendizaje de idiomas.

¿Cómo se realiza el seguimiento del uso del servicio de API?

Ofrecemos un panel de seguimiento de uso a través de Retool que proporciona visibilidad sobre el consumo diario general de la API. Esto incluye métricas como el número de characters processed, request counts (desglosados por uso scripted y unscripted), plan tier, processing time, number of chunks y number of ASR requests. Además, proporcionamos una vista detallada per-request view, que incluye el tier, la audio length y el transcribed text para cada solicitud individual. Este panel puede servir como una forma confiable de monitorear y gestionar el uso.

¿Por qué no hay puntuaciones de gramática o vocabulario para audios cortos?

En el caso de audios cortos, es esperable que las puntuaciones de gramática y vocabulario no se generen. Nuestro sistema generalmente requiere un mínimo de alrededor de 50 words for grammar evaluation y 75 words for vocabulary para producir resultados confiables y significativos.

Para obtener mejores resultados, recomendamos enviar muestras de audio más largas. Esto permite que nuestro motor de puntuación analice patrones y proporcione retroalimentación más completa.

¿Cómo se mapean las puntuaciones?

CEFRIELTSTOEFL SpeakingPTE RangeA11.50-110-10A122-310-10A12.54-510-10A236-710-11A23.58-912-15B1410-1116-19B14.512-2320-25B1514-1526-31B25.516-1732-40B2618-1941-50B26.520-2251-60C1723-2361-70C17.524-2571-79C1826-2780-86C28.528-2987-89C2930-3090-90

Referencias:

¿Por qué fue bloqueada mi solicitud (403 Forbidden)?

Es probable que su solicitud haya sido bloqueada por Cloudflare debido a una o más verificaciones de seguridad activadas por su Managed Ruleset. Estas reglas están diseñadas para detectar y prevenir tráfico potencialmente malicioso o sospechoso, incluso si la solicitud no es dañina en su contexto específico. Algunas razones comunes por las que una solicitud puede ser bloqueada incluyen:

Nombres de archivo o extensiones sospechosas: Por ejemplo, los archivos que terminan en ".php", ".asp" u otros formatos ejecutables suelen bloquearse cuando se cargan o se referencian en una solicitud, ya que se utilizan comúnmente en intentos de explotación.
Encabezados o cargas útiles inusuales: Si el cuerpo de la solicitud o los encabezados contienen contenido inesperado (p. ej., patrones de inyección de código o datos mal formados), Cloudflare puede marcarlo como sospechoso.
Parámetros que coinciden con firmas de exploit conocidas: Por ejemplo, la solicitud puede coincidir con vulnerabilidades conocidas como:
- CVE-2018-9206: Exploits en el plugin jQuery File Upload.
- CVE-2019-17132: Vulnerabilidades de ejecución remota de código en boletines.

Incluso si su sistema no está directamente afectado por estos CVEs, una similitud en la estructura o el nombre puede provocar que la solicitud sea bloqueada como medida de precaución. El enfoque de Cloudflare es actuar con cautela: priorizar la seguridad bloqueando las solicitudes que coincidan con patrones de ataque conocidos o heurísticas, incluso si resultan ser falsos positivos.

Para resolver esto:

Puede compartir los detalles completos de la solicitud (método, encabezados, cuerpo, URL) con nosotros para que podamos analizar qué activó específicamente la regla.
Si la solicitud es legítima y corresponde a un comportamiento esperado, podemos considerar crear de forma segura una regla de excepción o modificar el nivel de seguridad para su cuenta.