MultiTEL
Programadores

Tarefas de transcrição e tradução

Autenticação, acompanhamento, novas tentativas sem cobranças duplicadas, liquidação e utilização nos dois servidores da API.

Nesta página
  1. Autenticação
  2. Consultar até à conclusão
  3. Repetir com segurança pedidos de resultado incerto
  4. Obter um resultado depois de adicionar saldo
  5. Consultar a utilização
  6. Limites
  7. Tratar erros dos pedidos

Substitua SERVICE abaixo por speech_to_text ou translate, e JOB_ID pelo UUID recebido. Todas as operações exigem credenciais da sua conta, conforme descrito em Autenticação, e ficam limitadas à conta proprietária. Uma tarefa pode ser consultada em qualquer um dos dois servidores da API, mas cada servidor usa a sua própria estrutura de resposta; use sempre o mesmo servidor.

ServidorSucessoErro
api.multi.tel{"status":"success","data":{...}}{"status":"error","code":"...","message":"...","requestId":"..."}
api.multitel.net{"status":{"code":200},"response":{...}}{"status":{"code":409},"response":{"code":"idempotency_conflict"}}

Em api.multitel.net, as falhas de autenticação (401) são devolvidas antes de aplicar esta estrutura e podem ter um corpo diferente. Verifique o estado HTTP antes de analisar a resposta.

Autenticação

Cada pedido deve incluir credenciais da sua conta. As tarefas, chaves de idempotência, limites, utilização e cobranças pertencem à conta proprietária das credenciais. São partilhados por todas as credenciais dessa conta nos dois servidores, independentemente de quais enviam o pedido.

  • HTTP Basic (Authorization: Basic, ou curl --user). São aceites uma conta de API do tipo palavra-passe, uma subconta ou as credenciais de acesso da sua conta. Recomendamos uma conta de API dedicada. O nome de utilizador não pode conter dois-pontos, e nem o nome de utilizador nem a palavra-passe podem estar vazios.
  • Token Bearer (Authorization: Bearer YOUR_TOKEN). Aceite para uma conta de API do tipo token. Estas contas devem ter uma restrição de IP, e os pedidos devem vir de um endereço permitido. Ambos os servidores da API aceitam os endereços IPv4 e os intervalos CIDR configurados para a conta. Um token não pode ser enviado como palavra-passe Basic. Confirme que o seu token funciona no servidor que utiliza.
API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Se uma conta de API estiver limitada por endereço IP, envie os pedidos a partir de um endereço permitido. Credenciais ausentes ou inválidas devolvem 401. Em api.multitel.net, credenciais válidas que não podem usar estes serviços, como as de uma conta do tipo token enviadas por Basic, devolvem 403 unsupported_transcription_principal ou unsupported_translation_principal. Falhas de autenticação repetidas a partir do mesmo endereço em api.multitel.net podem causar o bloqueio desse endereço. Corrija as credenciais antes de tentar novamente.

Consultar até à conclusão

Envie um pedido GET /v3/SERVICE/JOB_ID. Recomendamos consultar, no máximo, uma vez a cada 3 segundos. A estrutura exterior descreve o pedido; consulte o campo status da tarefa para determinar se o processamento terminou.

EstadoSignificado
queuedAceite e em espera. As tarefas de uma conta são processadas uma de cada vez, alternadamente com as de outras contas.
runningEm processamento. progress pode ser null; um valor null, por si só, não significa que a tarefa tenha bloqueado.
completedO resultado está disponível. Guarde-o e compare os detalhes importantes com a fonte.
failedConsulte failureCode. O trabalho que falha não é cobrado. Corrija a causa e envie um pedido com uma chave nova; reenviar a mesma chave devolve a mesma tarefa falhada.
awaiting_paymentO processamento terminou, mas o saldo pré-pago não cobriu a cobrança. O resultado fica guardado e retido até a tarefa ser liquidada.
API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

Em api.multitel.net, defina HOST como https://api.multitel.net e leia .response.id em vez de .data.id.

Repetir com segurança pedidos de resultado incerto

Se um envio exceder o tempo de espera ou devolver 429 ou um estado 5xx, reenvie os mesmos dados com a mesma chave de idempotência. A resposta de qualquer servidor pode perder-se ou ser substituída por um erro depois de o trabalho ter sido aceite; reenviar a mesma chave devolve a tarefa, se existir. Reutilizar uma chave com dados diferentes devolve 409 idempotency_conflict. Alguns erros repetem-se em todas as tentativas, como 503 enquanto um serviço pago está desativado ou 500 para um ficheiro de áudio que não pode ser lido. Pare após algumas tentativas.

Alterar a chave tem efeitos diferentes em cada serviço.

  • Na transcrição de áudio, uma chave nova cria uma tarefa nova, cobrada separadamente se o processamento terminar com sucesso. A chave original continua a devolver a tarefa original, mesmo após uma atualização do processamento.
  • Na tradução, uma chave nova com conteúdo idêntico devolve, sem nova cobrança, uma tarefa correspondente em espera, em processamento, concluída ou a aguardar pagamento. Cria trabalho novo se a tarefa anterior falhou ou se a versão de processamento mudou. Uma nova tentativa de tradução com a chave original devolve 409 após uma alteração da versão de processamento; guarde o ID da tarefa original e consulte-a diretamente.

Obter um resultado depois de adicionar saldo

Para uma tarefa no estado awaiting_payment, adicione fundos para que o saldo seja pelo menos igual ao valor costUsd da tarefa, arredondado para cima ao múltiplo seguinte de $0.00001, e envie POST /v3/SERVICE/JOB_ID/settle. Os débitos são feitos em passos inteiros de $0.00001 e incluem o resto acumulado de tarefas anteriores do mesmo serviço. Assim, o valor debitado pode exceder costUsd em menos de $0.00001. Em api.multi.tel, envie o JSON {} ou um corpo vazio; qualquer propriedade no corpo é rejeitada com 400. api.multitel.net ignora o corpo. A liquidação liberta o resultado guardado sem executar novamente a transcrição ou a tradução. A resposta contém a tarefa; confirme que o seu estado é completed. Se o saldo continuar a ser insuficiente, a tarefa mantém o estado awaiting_payment e a resposta continua a ser HTTP 200.

Na transcrição de áudio, liquidar uma tarefa já concluída devolve-a com duplicate: true, e liquidar uma tarefa em espera, em processamento ou falhada devolve 409 transcription_not_awaiting_payment. Na tradução, liquidar uma tarefa em qualquer outro estado devolve-a sem alterações. A liquidação só está disponível enquanto o processamento pago estiver ativado (caso contrário, 503). As tarefas a aguardar pagamento contam como custo reservado; nas contas pré-pagas, podem por isso bloquear novos envios pagos com 402 até serem liquidadas.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Consultar a utilização

Use GET /v3/SERVICE/usage. Os parâmetros opcionais from e to são datas UTC no formato YYYY-MM-DD, e ambas as datas limite estão incluídas. Se forem omitidos, from assume por predefinição a data de há 30 dias e to a data de hoje (UTC). to não pode ser anterior a from, e as datas podem estar separadas por, no máximo, 366 dias (até 367 datas incluídas). Datas inválidas ou intervalos invertidos ou mais longos devolvem 400, tal como outros parâmetros de consulta em api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

A resposta contém mode, currency (USD), from, to e days, uma lista ordenada das entradas mais recentes para as mais antigas.

  • As entradas de transcrição de áudio são agrupadas por data e fonte. Contêm date, source (api, ou hpbx para gravações de Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd e debitedUsd.
  • As entradas de tradução são agrupadas por data, fonte e motor. Contêm date, source, engine, jobs, sourceCharacters, accruedUsd e debitedUsd.

accruedUsd é o custo exato com nove casas decimais, e debitedUsd é o valor debitado, com cinco. A utilização é registada na data UTC em que a cobrança de cada tarefa foi liquidada; por isso, não aparecem tarefas em espera, em processamento, falhadas ou a aguardar pagamento.

Limites

Cada conta pode ter, no máximo, 50 tarefas pendentes de transcrição de áudio e tradução no total: em espera, em processamento ou a aguardar pagamento, incluindo trabalho com gravações de Hosted PBX. Quando esse limite ou a capacidade global do serviço é atingido, os envios devolvem 429 transcription_queue_full ou translation_queue_full. api.multi.tel também limita cada endereço IP de cliente a 300 pedidos por minuto, contando todos os pedidos para esse servidor. Esse limite devolve 429 com cabeçalhos de limitação de frequência e um corpo de texto simples, em vez da estrutura JSON de erro.

Tratar erros dos pedidos

No servidor principal, as falhas devolvem um estado de erro HTTP e JSON com status: "error", code, message e requestId. Cada resposta inclui também um cabeçalho X-Request-ID. Pode fornecer o seu próprio valor; valores com mais de 128 caracteres são truncados. O servidor de compatibilidade devolve apenas o código de erro em response.code. Registe o ID do pedido, quando disponível, e o código de erro, mas não inclua áudio, texto ou credenciais nos registos.

Estados comuns:

EstadoSignificado
400Dados de entrada inválidos.
401Credenciais ausentes ou inválidas.
402Saldo pré-pago insuficiente.
403No servidor de compatibilidade, credenciais que não podem usar estes serviços.
404Uma tarefa ou rota desconhecida.
405Um método não suportado ou um caminho desconhecido dentro de um serviço.
409Dados em conflito, uma tradução para a mesma língua ou a liquidação de uma tarefa de transcrição que não está a aguardar pagamento.
413Um corpo ou ficheiro demasiado grande.
422Áudio não suportado ou um par de línguas indisponível para tradução padrão.
429Limites da fila, da validação ou da frequência de pedidos.
500Um erro inesperado do servidor, incluindo um ficheiro de áudio que não pode ser lido.
503Um serviço desativado ou temporariamente indisponível, ou credenciais que não podem ser verificadas neste momento.

Siga o código de erro devolvido, em vez de assumir que todas as falhas de validação têm o mesmo estado.

Para 429 ou 503, aguarde e tente novamente com intervalos progressivamente maiores e a mesma chave de envio; respeite Retry-After quando estiver presente. Para dados de entrada ou credenciais inválidos, corrija primeiro a causa. Não envie repetidamente chaves novas enquanto as tarefas anteriores ainda estiverem em espera.