Perguntas Frequentes

Onde posso encontrar detalhes de uso da API e dos endpoints?

Consulte a seção de endpoints da API em nossa documentação para obter informações detalhadas.

Quais configurações de rede e certificados são necessários?

A autenticação é token-based. Você encontrará todos os detalhes sobre o hostname e como usar a API em nossa documentação.

Exemplo:

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"'

Exemplos adicionais estão disponíveis na seção de API da documentação.

Como obtenho e utilizo a chave ou o token de API?

O API token será gerado por nós assim que o NDA for assinado. Por favor, nos informe quando isso for concluído e forneceremos o token. As instruções de uso estão descritas na documentação.

Qual é a estrutura e quais são os limites das requisições e respostas da API?

Você encontrará estruturas detalhadas de requisição e resposta, incluindo parameters e limitations, na documentação da API.

Existe um ambiente sandbox disponível e preciso de uma conta de teste?

No momento, não oferecemos um ambiente de staging.

Existe um painel ou logs para monitoramento e depuração?

Um painel customer-facing está disponível para dar visibilidade sobre as requisições e a atividade. Essa interface baseada em Retool permite que os usuários acompanhem seu uso tanto para chamadas de API com script quanto sem script.

Nossa API suporta ou pode ser integrada a uma solução RAG?

Embora nossa API não implemente nativamente uma solução RAG (Retrieval-Augmented Generation), ela certamente pode ser integrada a fluxos de trabalho RAG. Nossos serviços focam na análise de fluxos de áudio, e as saídas podem ser utilizadas como entrada para sistemas RAG ou outros pipelines que se beneficiem de contexto derivado de áudio enriquecido. Para fornecer uma resposta mais personalizada ou sugerir uma abordagem de integração ideal, compartilhe mais detalhes sobre o caso de uso pretendido pelo cliente ou sobre sua arquitetura.

Qual largura de banda é necessária para um funcionamento adequado dos recursos de fala com IA?

Por ora, os únicos requisitos relacionados à largura de banda que fornecemos são os listados em nossa documentação da API. Eles se aplicam independentemente de como os recursos de fala com IA são usados ou integrados. Se você puder compartilhar mais detalhes sobre seu caso de uso específico, teremos prazer em fornecer uma recomendação mais precisa.

É possível identificar de qual endereço IP cada chunk foi enviado?

No momento, não retemos nenhuma informação sobre a origem das requisições da API, como endereços IP. Isso significa que não conseguimos determinar de qual IP cada chunk foi enviado. Nossos logs focam em metadados de requisição relevantes para a funcionalidade do serviço, mas não incluem detalhes de rede em nível de origin-level.

Quais são os parâmetros da seção de resposta "utterance"?

Os parâmetros da seção de resposta utterance são:

nativeness_score: A pontuação de naturalidade alcançada pelo usuário para o enunciado completo, em uma escala de 0 a 100.
nativeness_score_partial: Esta pontuação reflete a naturalidade do usuário no subconjunto de palavras que ele efetivamente pronunciou, com uma pontuação mínima de 25%.
decision: Uma string que indica o nível de proficiência do usuário na pronúncia do enunciado, com base no nativeness_score. Valores possíveis: correct, almost_correct ou incorrect.

Observação: Enquanto o nativeness_score considera todas as palavras do enunciado (incluindo as que o usuário não disse), o nativeness_score_partial foca apenas nas palavras pronunciadas pelo usuário, mesmo que tenham uma pontuação baixa.

Exemplo: Se o enunciado é "Hello ELSA" e o usuário diz apenas "Hello", o nativeness_score_partial considerará apenas a pontuação de "Hello" (assumindo que ultrapasse 25%), enquanto o nativeness_score levará em conta todas as palavras, incluindo as não pronunciadas (por exemplo, "ELSA," com uma pontuação baixa ou zero).

Para mais detalhes, consulte a documentação da API.

Quais são os parâmetros da seção de resposta "words"?

Os parâmetros da seção de resposta words são:

nativeness_score: A pontuação de naturalidade (0–100) para a pronúncia da palavra individual.
decision: Avaliação de proficiência baseada no nativeness_score, com valores possíveis de correct, almost_correct ou incorrect.

Para mais detalhes, consulte a documentação da API.

Quais são os parâmetros da seção de resposta "word_stress"?

Os parâmetros da seção de resposta word_stress são:

decision: Indica se o usuário enfatizou a sílaba corretamente, com valores possíveis correct ou incorrect.

Para mais detalhes, consulte a documentação da API.

Quais são os parâmetros da seção de resposta "phonemes"?

Os parâmetros da seção de resposta phonemes são:

nativeness_score: A pontuação para os fonemas nesta entrada, em uma escala de 0–100.
decision: Indica a precisão da pronúncia dos fonemas, com valores possíveis correct, warning ou error.

Para mais detalhes, consulte a documentação da API.

Como funciona o cálculo de chunks

Um chunk tem 15 seconds de duração. No entanto, o número real de chunks é calculado usando a fórmula:

num_chunks = ceil(duration / chunk_size)

Assim, por exemplo, um áudio de entrada de 17-second resulta em 2 chunks (e não 1,13), por causa da operação de teto.

Além disso:

Se a duração total exceder ligeiramente a duração máxima permitida pela API, ela é truncada para se enquadrar nos limites. Isso evita que uma segunda requisição seja disparada por causa de apenas alguns frames extras.
Também removemos silêncio e ruído do início ou do fim do áudio quando aplicável, o que pode afetar ainda mais a contagem final de chunks.

Esses fatores explicam por que num_standard_chunks pode não se alinhar exatamente com num_secs / 15.

Como o Speech Analyzer detecta erros gramaticais?

Detectamos erros gramaticais, mas corrigimos apenas aqueles para os quais temos alta confiança no contexto. Especificamente, uma correção proposta deve ter pelo menos 80% confidence antes de ser aplicada. Essa abordagem garante que evitemos sugerir alterações irrelevantes em casos de ambiguidade gramatical.

Quais são os limites máximos de upload de arquivos de áudio?

Bytes

O tamanho máximo de arquivo permitido para upload é de 100MB. Caso precise enviar arquivos maiores do que esse limite, entre em contato com nossa equipe de suporte.

Minutos

O comprimento máximo de arquivo de áudio para requisições sem script com o flag sync definido como True permitido para upload é de 15 minutes.

Com script: Sem limite
Sem script:
- sync = True => 15 minutes
- sync = False => 12 minutes

As pontuações de pronúncia e entonação estão relacionadas?

Não existe dependência direta entre pronunciation_score e intonation_score. No entanto, normalmente calculamos o intonation_score apenas para entradas mais longas, como frases completas. Como resultado, usuários que são iniciantes absolutos e tendem a produzir enunciados muito curtos ou incompletos podem não receber um intonation_score. Isso pode dar a impressão de uma relação, mas é mais um reflexo do comprimento e da qualidade da entrada do que uma dependência entre as pontuações em si.

Como as decisões de pronúncia e entonação são avaliadas?

Esses atributos de decisão são baseados nas pontuações de CEFR-level correspondentes (por exemplo, pronunciation_cefr, intonation_cefr). Um exemplo de mapeamento é o seguinte:

Correct: nível CEFR C1 ou C2
Warning: nível CEFR B1 ou B2
Incorrect: nível CEFR A1 ou A2

Por que algumas chamadas de API sem script não têm pontuações EPS ou transcrições?

Para obter resultados com métricas, certifique-se de que o comprimento do áudio exceda 20 seconds.

O nível de pronúncia é mapeado para um sotaque nativo americano/britânico?

Seguimos padrões globais (CEFT, IELTS, TOEFL), nos quais não penalizamos os indivíduos por falar com seu sotaque nativo, mas sim focamos na clareza da fala. Embora possa haver pequenas variações para usuários com sotaques mais marcados, as diferenças geralmente permanecem dentro da mesma faixa.

Por que as métricas de gramática e vocabulário estão ausentes nos resultados da API sem script?

Essas métricas têm um limite mínimo. Se quiser obter resultados para as métricas de gramática e vocabulário na API sem script apesar desse limite mínimo, basta adicionar o flag -F force_grammar_vocab=True. No entanto, é importante observar que esses resultados podem não ser tão precisos quanto os que atendem ao limite mínimo.

Qual padrão utilizamos para explicabilidade?

Nossos modelos são proprietários e não divulgamos as arquiteturas exatas nem os mecanismos internos. Embora priorizemos a transparência em termos de qualidade de saída e benchmarks de desempenho, atualmente não seguimos um padrão público para explicabilidade de modelos.

Como calculamos a pontuação geral?

A pontuação geral é uma combinação das cinco métricas: pronunciation, intonation, fluency, grammar e vocabulary. Às vezes, se não fornecemos pontuações de vocabulário ou gramática porque a gravação foi curta, ainda podemos fornecer uma pontuação geral com base nas outras métricas disponíveis.

Como a pontuação é calculada?

A forma como calculamos o ELSA Score e o mapeamos para o IELTS é desenvolvida internamente. Os parâmetros para calcular a pontuação ELSA podem mudar ao longo do tempo, assim como o mapeamento para o IELTS. De tempos em tempos, reavaliamos e ajustamos ligeiramente.

Como o alcance gramatical e os erros são ponderados na pontuação de Gramática?

A proporção desses aspectos depende do tipo de gravação. Para fala casual, é aproximadamente 60% erros gramaticais e 40% alcance gramatical; para configurações semelhantes a exames, é aproximadamente 50% erros gramaticais e 50% alcance gramatical. É importante observar que esses números são ajustados quando temos novos dados.

Como calculamos a pontuação de pronúncia?

A pontuação de pronúncia é baseada na precisão com que você pronuncia os sons do inglês em cada palavra reconhecida pela ELSA em sua gravação. O número e a gravidade das pronúncias incorretas destacadas contribuirão para a pontuação de pronúncia.

Como calculamos a pontuação de fluência?

A pontuação de Fluência é uma combinação do seu desempenho em Pace, Pausing e Hesitations. Manter um bom Ritmo, Pausar apenas em lugares naturais e reduzir a quantidade de palavras de preenchimento e repetições contribuirá para uma boa pontuação de Fluência.

Como calculamos a pontuação de entonação?

A pontuação de intonation leva em conta as subidas e descidas no seu tom de voz e o quanto você enfatizou as palavras dentro das frases.

Como calculamos a pontuação de vocabulário?

A pontuação de Vocabulary é baseada principalmente nos CEFR levels estimados das palavras e expressões na fala do usuário.

Observação: Apresentamos a distribuição raw do CEFR como feedback (percentual de palavras em cada nível A1-C2), mas a pontuação geral é calculada por um algoritmo estatístico que mapeia essa distribuição para um valor de 0-100 (onde 100% corresponde ao uso de vocabulário semelhante ao de um falante nativo). A pontuação de vocabulary é retornada apenas se o texto tiver (atualmente) 75 words ou mais.

Como calculamos a pontuação de gramática?

A pontuação de grammar é calculada com base nas saídas do módulo de detecção e correção de erros gramaticais combinadas com o alcance gramatical identificado. O módulo de detecção e correção de erros gramaticais identifica erros gramaticais no texto e gera a pontuação de erros. O módulo de alcance gramatical identifica todas as estruturas gramaticais e calcula a pontuação de alcance com base nas 5 estruturas de nível mais alto utilizadas com sucesso na gravação. A pontuação de grammar é retornada apenas se o texto tiver (atualmente) 50 words ou mais.

Qual é o volume e a diversidade dos dados de treinamento?

Embora não divulguemos detalhes de implementação ou estruturas internas de nossos modelos, estamos comprometidos em garantir que as saídas sejam interpretáveis e alinhadas às expectativas dos usuários. Quando aplicável, fornecemos score breakdowns ou feedback em nível de category-level que refletem a lógica de avaliação do modelo de forma transparente e acionável para o usuário final. Internamente, seguimos práticas robustas de validação e benchmarks de desempenho para garantir consistência e imparcialidade nas decisões do modelo.

Qual é a precisão dos modelos e com que frequência são retreinados?

Historicamente, não compartilhamos publicamente dados detalhados de precisão. Em vez disso, normalmente comunicamos que nossos modelos superam os concorrentes com base em nossos benchmarks internos. Em relação à model retraining frequency, ela varia significativamente dependendo do modelo. Embora alguns modelos tenham permanecido inalterados por períodos prolongados, nossa abordagem geral tem sido consistentemente coletar dados dos usuários (onde permitido) e melhorar iterativamente o desempenho dos modelos ao longo do tempo.

Qual é o risco de viés ou discriminação?

A IA da ELSA foi desenvolvida especificamente para apoiar falantes de inglês non-native. Ao treinar com milhares de horas de inglês com sotaque, proveniente de falantes reais de segunda língua (L2), a ELSA está em posição única para reconhecer e abordar os desafios de pronúncia dos aprendizes. Essa abordagem inclusiva ajuda a reduzir o viés de sotaque e garante que os aprendizes se sintam reconhecidos, apoiados e empoderados desde o primeiro dia.

Qual é o peso da "entonação" no modelo e como ela é tratada eticamente?

Independentemente de o conteúdo ser scripted ou unscripted, a taxa de detecção é de aproximadamente 20%.

Em relação à questão sobre como tratar isso de forma ethically, é possível que a preocupação esteja relacionada ao potencial de detecção de padrões de fala individuais ou a riscos de falsificação de voz.

Para esclarecer: Nossos sistemas de análise de fala e entonação são projetados para ser agnostic a quaisquer características identificáveis da voz de um usuário. Não realizamos identificação de falantes, nem usamos dados de áudio para esse propósito. Nosso foco permanece exclusivamente na avaliação da pronúncia e da prosódia no contexto do aprendizado de idiomas.

Como o uso do serviço de API é rastreado?

Oferecemos um painel de rastreamento de uso via Retool que fornece visibilidade sobre o consumo diário total da API. Isso inclui métricas como número de characters processed, request counts (discriminados por uso scripted e unscripted), plan tier, processing time, number of chunks e number of ASR requests. Além disso, fornecemos uma visualização detalhada per-request view, que inclui o tier, o audio length e o transcribed text para cada requisição individual. Esse painel pode servir como uma forma confiável de monitorar e gerenciar o uso.

Por que não há pontuações de gramática ou vocabulário para áudios curtos?

No caso de áudios curtos, é esperado que as pontuações de gramática e vocabulário possam não ser geradas. Nosso sistema normalmente requer um mínimo de aproximadamente 50 words for grammar evaluation e 75 words for vocabulary para produzir resultados confiáveis e significativos.

Para melhores resultados, recomendamos o envio de amostras de áudio mais longas. Isso permite que nosso mecanismo de pontuação analise padrões e forneça um feedback mais abrangente.

Como as pontuações são mapeadas?

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

Referências:

Por que minha requisição foi bloqueada (403 Forbidden)?

Sua requisição provavelmente foi bloqueada pelo Cloudflare devido a uma ou mais verificações de segurança acionadas pelo Managed Ruleset deles. Essas regras são projetadas para detectar e impedir tráfego potencialmente malicioso ou suspeito — mesmo que a requisição não seja prejudicial no seu contexto específico. Alguns motivos comuns pelos quais uma requisição pode ser bloqueada incluem:

Nomes ou extensões de arquivos suspeitos: Por exemplo, arquivos terminados em ".php", ".asp" ou outros formatos executáveis são frequentemente bloqueados quando enviados ou referenciados em uma requisição, pois são comumente usados em tentativas de exploração.
Cabeçalhos ou payloads incomuns: Se o corpo ou os cabeçalhos da requisição contiverem conteúdo inesperado (por exemplo, padrões de injeção de código ou dados malformados), o Cloudflare pode sinalizá-la como suspeita.
Parâmetros que correspondem a assinaturas de exploração conhecidas: Por exemplo, a requisição pode corresponder a vulnerabilidades conhecidas como:
- CVE-2018-9206: Explorações no plugin jQuery File Upload.
- CVE-2019-17132: Vulnerabilidades de execução remota de código do Bulletin.

Mesmo que seu sistema não seja diretamente afetado por esses CVEs, uma similaridade na estrutura ou nomenclatura pode fazer com que a requisição seja bloqueada como precaução. A abordagem do Cloudflare é agir com cautela — priorizando a segurança ao bloquear requisições que correspondam a padrões de ataque conhecidos ou heurísticas, mesmo que se revelem falsos positivos.

Para resolver isso:

Você pode compartilhar os detalhes completos da requisição (método, cabeçalhos, corpo, URL) conosco para que possamos analisar o que especificamente acionou a regra.
Se a requisição for legítima e um comportamento esperado, podemos considerar criar com segurança uma regra de exceção ou modificar o nível de segurança para sua conta.