API de tradução de texto

Esta API traduz texto através de tarefas em fila de espera, com um idioma de destino por tarefa. Envie o texto, guarde o ID da tarefa devolvido e consulte a tarefa até o processamento terminar. Envie todos os pedidos por HTTPS com as credenciais da sua conta, sejam as credenciais HTTP Basic apresentadas nos exemplos ou um token API, conforme descrito em Autenticação. Mantenha as credenciais no seu servidor.

Pontos de acesso

Os dois servidores API, https://api.multi.tel e o servidor de compatibilidade https://api.multitel.net, partilham as tarefas, chaves de idempotência, limites e faturação associados à mesma conta. Diferem no formato exterior das respostas; por isso, utilize sempre o mesmo servidor com um analisador adequado.

Em api.multi.tel, todos os caminhos também estão disponíveis com o prefixo /v1/translate em vez de /v3/translate. Em api.multitel.net, utilize os caminhos /v3/translate.

A resposta com as informações do serviço apresenta enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages e ratesNanosPerCharacter. cpuLanguages apresenta os códigos dos idiomas de base aceites para a tradução padrão. ratesNanosPerCharacter indica o preço configurado por ponto de código de origem para cada motor, em milésimos de milionésimo de dólar dos EUA: um valor de 5000 corresponde a $5 por milhão de pontos de código. A resposta não indica se a tradução melhorada está atualmente disponível; uma estimativa com tradução melhorada devolve 503 quando não está. A consulta é gratuita.

Traduzir texto

Envie JSON com Content-Type: application/json para POST https://api.multi.tel/v3/translate. Cada tarefa tem um idioma de destino; por isso, submeta uma tarefa separada para cada destino.

Os códigos de locale são etiquetas BCP 47 com 2 a 63 letras, algarismos e hífenes. São convertidos para a forma canónica; assim, en-us é registado como en-US. Etiquetas inválidas, bem como und, mul ou zxx, devolvem 400 invalid_translation_language. A disponibilidade da tradução padrão é verificada pelo idioma de base, e nb e nn contam como no. Um destino regional, como fr-CA, é aceite e registado, mas o resultado padrão segue o idioma de base, sem garantia de refletir a região.

Mantenha o corpo do pedido dentro de 128 KiB neste servidor. Envie o texto em UTF-8 em vez de representar cada carácter não ASCII através de uma sequência \u, o que pode fazer um pedido com 20,000 caracteres ultrapassar o limite.

O corpo aceita apenas estes quatro campos. Qualquer outra propriedade é rejeitada com 400 invalid_translation_request, incluindo idempotency_key, IDs de proprietário, indicadores de processamento gratuito e arrays de segmentos.

Idempotência e reutilização

Cada submissão exige um cabeçalho Idempotency-Key com 1 a 190 caracteres. Utilize letras ASCII, algarismos, -, _, . e :, sem espaços no início ou no fim; uma chave em falta ou com 191 ou mais caracteres é rejeitada com 400. As chaves são específicas da sua conta e da tradução, abrangendo ambos os servidores e todas as credenciais da sua conta.

• A mesma chave com o mesmo texto, idiomas na forma canónica e motor devolve a tarefa existente com HTTP 200 e duplicate: true, sem nova cobrança.
• A mesma chave com texto, idiomas ou motor diferentes devolve 409 idempotency_conflict. A mesma chave também devolve 409 se a versão do processamento tiver mudado desde a criação da respetiva tarefa. Nesse caso, consulte a tarefa original pelo respetivo ID em vez de a voltar a submeter.
• Uma nova chave com o mesmo texto, idiomas na forma canónica e motor devolve a tarefa existente com HTTP 200 e duplicate: true, sem nova cobrança de processamento, se existir uma tarefa com esse conteúdo e a versão de processamento atual em fila de espera, em execução, concluída ou a aguardar pagamento. Uma tarefa reutilizada que esteja a aguardar pagamento continua a necessitar de liquidação. As tarefas falhadas não são reutilizadas: é criada uma nova tarefa, que é cobrada quando terminar.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

Uma nova tarefa devolve HTTP 202. O texto do exemplo tem 57 pontos de código; por isso, a $5 por milhão de pontos de código, custa $0.000285. Uma resposta abreviada (o identificador é um exemplo):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

Uma submissão também pode devolver 402 insufficient_balance quando o saldo pré-pago não cobre a tarefa em conjunto com as outras tarefas pendentes, e 429 translation_queue_full quando a sua conta ou o serviço tem demasiadas tarefas pendentes. Devolve 503 nestes casos:

• paid_translation_not_enabled enquanto a tradução paga está desativada.
• translation_unavailable para um pedido de tradução melhorada enquanto esta está indisponível.
• translation_pricing_unavailable enquanto o motor escolhido não tem um preço configurado.

Perante respostas 429 e 503, tente novamente mais tarde com a mesma chave.

Escolher a qualidade

O texto longo é processado em partes mais pequenas e depois reunido. As quebras de linha e o espaçamento podem mudar, e uma frase pode perder contexto na fronteira entre partes processadas. Guarde o texto original e reveja o resultado reunido. A tradução padrão utiliza o idioma de base de uma etiqueta regional; aceitar e registar uma etiqueta não garante uma formulação regional.

A tradução padrão é executada por processos de trabalho em CPU. A tradução melhorada envia o texto para o serviço externo de IA configurado. O resultado continua a precisar de revisão; o serviço não garante que um motor seja mais exato para todos os pares de idiomas ou tipos de texto.

A tradução padrão é um rascunho cuja qualidade e tempo de processamento variam conforme o par de idiomas. A tradução melhorada destina-se a textos em que o contexto é importante, mas continua a exigir revisão dos nomes, números, negações e compromissos importantes. Nenhuma das opções corrige erros já presentes numa transcrição original; por isso, guarde o original para comparação.

Utilize GET /v3/translate no mesmo servidor API para verificar a disponibilidade atual, os idiomas padrão suportados e os preços configurados. Um pedido de tradução padrão cujo idioma de base de origem ou destino não conste de cpuLanguages devolve 422 translation_language_pair_unavailable. Quando source_language é fornecido e tem o mesmo idioma de base do destino, o pedido devolve 409 translation_same_language em vez de criar uma tarefa. A tradução melhorada é ativada separadamente: enquanto estiver indisponível, as submissões e estimativas com tradução melhorada devolvem 503.

Obter primeiro uma estimativa

Em api.multi.tel, envie o mesmo corpo JSON para POST /v3/translate/estimate. Não é necessária uma chave de idempotência. Uma estimativa aplica a mesma validação, incluindo as verificações 422 e 409, mas não cria uma tarefa, não traduz texto, não reserva fundos, não verifica o saldo nem cobra a sua conta. Devolve HTTP 200 com estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd e costUsd em data. Para o exemplo acima, costUsd é 0.000285000 ao preço padrão. Enquanto a tradução melhorada estiver indisponível, uma estimativa com tradução melhorada devolve 503 service_unavailable. As estimativas utilizam o preço atualmente configurado. O preço de uma tarefa é fixado no momento da sua criação, e a cobrança utiliza esse preço.

Obter a tradução

Uma nova submissão devolve HTTP 202, e uma tarefa existente ou reutilizada devolve HTTP 200. Guarde data.id e utilize o fluxo de trabalho comum das tarefas. O objeto da tarefa contém estes campos:

• id, status, engine, sourceLocale e targetLocale.
• sourceCharacters, costUsd, costIsEstimate e pricePerMillionCharactersUsd.
• progress e createdAt.
• modelVersion, uma cadeia opaca que identifica a versão do processamento.
• duplicate nas respostas que reutilizam uma tarefa.
• failureCode para tarefas falhadas: translation_failed, translation_timeout, input_failed ou worker_lease_lost.

Uma tarefa falhada apresenta um costUsd de zero.

Uma tarefa concluída tem data.result com sourceLocale (vazio se não tiver sido fornecido um idioma de origem), targetLocale, o texto traduzido em text (textos dos segmentos unidos por quebras de linha), e segments. Para texto submetido através desta API, segments contém uma entrada com o texto traduzido em text e o idioma de destino em language. Os resultados das tarefas a aguardar pagamento não são disponibilizados até à liquidação.

Utilizar api.multitel.net

O ponto de acesso de compatibilidade POST https://api.multitel.net/v3/translate aceita os mesmos campos JSON e o mesmo cabeçalho Idempotency-Key. Se o cabeçalho estiver ausente, também aceita uma cadeia idempotency_key no corpo JSON. Qualquer outro campo adicional é rejeitado com 400 unsupported_translation_option. Neste servidor, o corpo em bruto pode ter até 256,000 bytes, e texto com mais de 20,000 pontos de código devolve 413 translation_too_large em vez de 400. Um campo source_language vazio é tratado como omitido. Uma resposta 429 inclui Retry-After: 15. Este servidor também devolve estes erros:

• 400 json_body_required quando o corpo está em falta, é JSON inválido ou é um escalar JSON. Envie um objeto JSON.
• 400 invalid_translation_options quando text, target_language ou engine está em falta, está vazio ou não é uma cadeia, ou source_language não é uma cadeia.
• 400 invalid_translation_text para texto composto apenas por espaços em branco.
• 400 invalid_translation_engine para um motor desconhecido.
• 400 idempotency_key_required para uma chave em falta, vazia ou demasiado longa, ou para um valor que não seja uma cadeia em idempotency_key.
• 400 invalid_job para um ID de tarefa malformado.

As respostas do serviço de tradução deste servidor utilizam o formato exterior {"status":{"code":HTTP_STATUS},"response":{...}}, em que status é um objeto. Leia o ID da tarefa em response.id e o resultado concluído em response.result. Os erros colocam o código em response.code, sem mensagem nem ID do pedido. As falhas de autenticação (401) são devolvidas pela verificação geral de início de sessão do servidor e podem ter um corpo diferente; por isso, verifique o estado HTTP antes de analisar a resposta. As tarefas são partilhadas com o servidor principal, mas utilize o mesmo servidor para as consultas periódicas, a liquidação e a utilização, para que o analisador corresponda ao formato exterior. Este servidor também aceita os mesmos campos JSON em /v3/translate/estimate sem uma chave de idempotência, e a estimativa encontra-se em response.