Áudio assíncrono

Transcrição, síntese de voz e turnos de voz são jobs assíncronos. O cliente cria um job e consulta o seu estado; não existe streaming nesta API.

Disponibilidade e acesso

Todas as rotas abaixo exigem uma chave de projeto com o escopo audio.create. As chaves de teste podem criar jobs sandbox; no ambiente live, preço de áudio e interruptores operacionais também precisam estar ativos.

Rotas

Método	Rota	Uso
`POST`	`/v1/audio/uploads`	Cria um URL assinado de upload.
`PUT`	`upload_url`	Envia o ficheiro ao URL devolvido pelo upload.
`POST`	`/v1/audio/transcriptions`	Cria uma transcrição a partir de um upload.
`POST`	`/v1/audio/speech`	Cria síntese de voz a partir de texto.
`POST`	`/v1/voice/turns`	Cria um turno de voz a partir de um upload.
`GET`	`/v1/jobs/{id}`	Consulta um job do mesmo projeto e chave.
`DELETE`	`/v1/jobs/{id}/data`	Apaga imediatamente os dados retidos de um job finalizado.

1. Criar e enviar um upload

Peça primeiro um URL assinado com formato e duração declarada. São aceitos mp3, mp4, wav, webm e m4a, até 25 MB e 15 minutos.

curl https://api.tipochat.co.mz/v1/audio/uploads \
  -X POST \
  -H "Authorization: Bearer $TIPOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "wav",
    "declared_seconds": 12
  }'

A resposta 201 contém id, upload_url, method: "PUT", data de expiração e limite de bytes. Guarde os dois valores apenas até criar o job.

Depois, envie os bytes do ficheiro diretamente ao upload_url. Não envie a chave TipoChat nesta chamada: o URL assinado já autoriza um único upload.

curl "$UPLOAD_URL" \
  -X PUT \
  -H "Content-Type: audio/wav" \
  --upload-file "./mensagem.wav"

Se o URL expirar ou o envio falhar, crie outro upload; não reutilize um upload_id inválido.

2. Criar o job certo

Cada criação de job recebe uma Idempotency-Key nova. A resposta é 202: guarde o id e não assuma que o áudio já existe.

Transcrever um ficheiro enviado

curl https://api.tipochat.co.mz/v1/audio/transcriptions \
  -X POST \
  -H "Authorization: Bearer $TIPOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "upload_id": ""
  }'

Gerar voz a partir de texto

Envie input com até 4.096 caracteres e uma das vozes disponíveis, se desejar.

curl https://api.tipochat.co.mz/v1/audio/speech \
  -X POST \
  -H "Authorization: Bearer $TIPOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "input": "Bem-vindo à TipoChat.",
    "voice": "coral"
  }'

Receber texto e voz a partir de um ficheiro

Para um turno de voz, envie o upload_id, max_output_tokens entre 1 e 1.024 e, opcionalmente, instruções e voz.

curl https://api.tipochat.co.mz/v1/voice/turns \
  -X POST \
  -H "Authorization: Bearer $TIPOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "upload_id": "",
    "instructions": "Responda em português de Moçambique.",
    "voice": "coral",
    "max_output_tokens": 300
  }'

{
  "id": "",
  "object": "job",
  "type": "transcription",
  "mode": "sandbox",
  "status": "queued"
}

3. Consultar o resultado com GET e apagar dados

Faça GET no mesmo servidor, a cada 2 segundos, até status ser done ou failed. Os estados queued e processing ainda não têm resultado. Não crie outro job enquanto aguarda.

curl https://api.tipochat.co.mz/v1/jobs/ \
  -H "Authorization: Bearer $TIPOCHAT_API_KEY"

Em done, uma transcrição devolve output.transcript; voz e turno de voz devolvem output.audio_url, um URL temporário de 10 minutos. A resposta também inclui billing, warning_code e error_code.

Quando o job finalizado já não for necessário, apague os seus dados:

curl https://api.tipochat.co.mz/v1/jobs//data \
  -X DELETE \
  -H "Authorization: Bearer $TIPOCHAT_API_KEY"