API REST V3¶

O CPqD Transcrição de Diálogos possui uma API REST que permite realizar as operações cadastro e transferência de arquivos de áudio, bem como controlar o processo de transcrição dos arquivos. Esta seção tem como objetivo detalhar essas funções que compõem a API REST do servidor de transcrição.

Todo a API do transcritor é auto-documentada, e pode ser acessada a partir da seguinte URL http://TRD_HOST:8000/trd/v3/docs, onde TRD_HOST é o IP do servidor de funcionamento do transcritor.

Nota

Caso não tenha acesso a um servidor de transcrição a documentação também pode ser acessada a partir do link

API JOB síncrona¶

Aviso

API para desenvolvimento. Não utilize em produção.

Transcrição síncrona de 1 arquivo, limitada a duração do em até 120 segundos. A transcrição é iniciada imediatamente, e o arquivo é apagado ao final do processo. O sistema não armazena o resultado da transcrição. O sistema deve contabilizar a duração do áudio para cobrança, registrando o nome e tag.

Requisição

POST /trd/v3/transcribe

Query

Tag (opcional)

Header

X-License-ID

Request Body

Arquivo binário
Configuração

Response

200 - Resultado da transcrição
413 - Audio muito longo
400 - Solicitação invalida
401 - Não autorizado
422 - Erro de validação
503 - Servidor ocupado

Resultado

O resultado é um objeto que denominamos de JOB que possue os seguintes atributos.

id: identificador único do processo de transcrição
filename: nome do arquivo
status: estado do processo de transcrição
create_at: timestamp do momento de upload do arquivo
started_at: timestamp do inicio do processo de transcrição
diarized_at: timestamp do final do processo de diarização
completed_at: timestamp do final do processo de transcrição
tag: identificador opcional do arquivo
callback_urls: endereços para o webhook
media: objeto que reuni informações de media do arquivo transcrito, como seu tamanho, numero de canais e formato
config: objeto que reuni informações de configuração, dos processo de diarização e reconhecimento

Exemplos

Chamada REST:

curl -X POST "http://localhost:8000/trd/v3/transcribe?tag=novo"
-H  "accept: application/json"
-H  "Content-Type: multipart/form-data"
-F "config="
-F "callback_urls="
-F "upload_file=@<file_path>;type=audio/wav"

Resultado JSON:

{
   "job":{
      "id":"5fc8e4b8eee464d8c64c7fd9",
      "filename":"nas.wav",
      "status":"COMPLETED",
      "created_at":"2020-12-03T10:14:32.636000-03:00",
      "started_at":"2020-12-03T10:14:32.704000-03:00",
      "diarized_at":"2020-12-03T10:14:33.053000-03:00",
      "completed_at":"2020-12-03T10:14:33.697000-03:00",
      "tag":"novo",
      "callback_urls":[
         
      ],
      "media":{
         "md5":"18eef3c06a975dc8cd1adad4ae662824",
         "size":72544,
         "input":{
            "sample_rate":8000,
            "channels":1,
            "bit_rate":128000,
            "format":"Wave",
            "codec":""
         },
         "output":{
            "redundant_channel":false,
            "channels":[
               {
                  "channel":1,
                  "duration":4.531,
                  "speech":3.2590000000000003,
                  "bandwidth":4000
               }
            ]
         }
      },
      "config":{
         "diarization":{
            "vad":{
               "chunk_max_silence":1200.0,
               "chunk_max_length":3600.0
            },
            "clustering":{
               "threshold":-0.4,
               "enabled": true
            }
         },
         "recognition":{
            "params":{
               
            },
            "lm":"builtin:slm/callcenter-small"
         }
      }
   }
}

API JOB assíncrona¶

Transcrição assíncrona de 1 arquivo. É criado um processo de transcrição (job) e é iniciado, sendo inserido na fila de processamento.

Requisição

POST /trd/v3/job/create

Query

Tag (opcional)

Header

X-License-ID (opcional)

Request Body

Arquivo binário
Configuração (opcional)
callback_urls: (opcional: api webhook)

Response

200 - Resultado da transcrição
201 - JOB criado
413 - Audio muito longo
400 - Solicitação invalida
401 - Não autorizado
422 - Erro de validação
503 - Servidor ocupado

Regras

Recebe o arquivo binário, usa o header licence-id para selecionar database para gravar o arquivo.
Cria um job, armazena no database e envia para a fila de normalização.

Resultado

O resultado é um objeto que denominamos de JOB que possue os seguintes atributos.

id: identificador único do processo de transcrição
filename: nome do arquivo
status: estado do processo de transcrição
create_at: timestamp do momento de upload do arquivo
tag: identificador opcional do arquivo
callback_urls: endereços para o webhook
media: objeto que reuni informações de media do arquivo transcrito, como seu tamanho, numero de canais e formato
config: objeto que reuni informações de configuração, dos processo de diarização e reconhecimento

Exemplos

Chamada REST:

curl -X POST "http://localhost:8000/trd/v3/job/create"
-H  "accept: application/json"
-H  "Content-Type: multipart/form-data"
-F "config="
-F "callback_urls="
-F "upload_file=@<file_path>;type=audio/wav"

Resultado JSON:

{
   "job":{
      "id":"5fc900c5eee464d8c64c7fe5",
      "filename":"nas.wav",
      "status":"QUEUED",
      "created_at":"2020-12-03T12:14:13.413663-03:00",
      "tag":"novo",
      "callback_urls":[
         
      ],
      "media":{
         "md5":"18eef3c06a975dc8cd1adad4ae662824",
         "size":72544
      },
      "config":{
         "diarization":{
            "vad":{
               "chunk_max_silence":1200.0,
               "chunk_max_length":3600.0
            },
            "clustering":{
               "threshold":-0.4,
               "enabled": true
            }
         },
         "recognition":{
            "params":{
               
            },
            "lm":"builtin:slm/callcenter-small"
         }
      }
   },
   "segments": []
}

API Lista JOB¶

Retorna a lista de todos jobs criados para determinado License-ID.

Requisição

GET /trd/v3/job

Query

Tag (opcional)
Page (opcional)
Limit (opcional, máximo 1000)

Header

X-License-ID

Response

200 - Resultado da consulta
400 - Solicitação invalida
401 - Não autorizado
404 - Não encontrado
422 - Erro de validação

Resultado

O resultado é um objeto que denominamos de JOB que possue os seguintes atributos.

page: numero da pagina que será retornada
limit: numero de item resultantes por pagina
total: numero total de jobs
result: lista com todos os jobs

Chamada REST:

curl -X GET "http://localhost:8000/trd/v3/job?page=1&limit=1"
-H  "accept: application/json"

Resultado JSON:

{
  "page": 1,
  "limit": 1,
  "total": 19,
  "results": [
    {
      "job": {
        "id": "5fc7baefeee464d8c64c7e1a",
        "filename": "nas.wav",
        "status": "COMPLETED"
      }
    }
  ]
}

API Status JOB¶

Retorna o status do processo de transcrição.

Requisição

GET /trd/v3/job/status/<id>

Header

X-License-ID

Path

id: id do processo

Response

200 - Resultado da transcrição
400 - Solicitação invalida
403 - Acesso proibido
404 - Não encontrado
422 - Erro de validação

Resultado

O resultado é um objeto que denominamos de JOB que possue os seguintes atributos.

id: identificador único do processo de transcrição
filename: nome do arquivo
status: estado do processo de transcrição
create_at: timestamp do momento de upload do arquivo
started_at: timestamp do inicio do processo de transcrição
diarized_at: timestamp do final do processo de diarização
completed_at: timestamp do final do processo de transcrição
tag: identificador opcional do arquivo
callback_urls: endereços para o webhook
media: objeto que reuni informações de media do arquivo transcrito, como seu tamanho, numero de canais e formato
config: objeto que reuni informações de configuração, dos processo de diarização e reconhecimento

Exemplos

Chamada REST:

curl -X GET "http://localhost:8000/trd/v3/job/status/<id>"
-H  "accept: application/json"

Resultado JSON:

{
  "job": {
    "id": "5fc7c1dceee464d8c64c7e9c",
    "filename": "big.wav",
    "status": "COMPLETED",
    "created_at": "2020-12-02T13:33:32.713000-03:00",
    "started_at": "2020-12-02T13:33:33.491000-03:00",
    "diarized_at": "2020-12-02T13:34:14.126000-03:00",
    "completed_at": "2020-12-02T13:35:43.139000-03:00",
    "callback_urls": [],
    "media": {
      "md5": "633644fdd31a0bbbbb5ffa6fd3fa1417",
      "size": 32958764,
      "input": {
        "sample_rate": 8000,
        "channels": 1,
        "bit_rate": 128000,
        "format": "Wave",
        "codec": ""
      },
      "output": {
        "redundant_channel": false,
        "channels": [
          {
            "channel": 1,
            "duration": 2059.92,
            "speech": 363.5129999999991,
            "bandwidth": 4000
          }
        ]
      }
    },
    "config": {
      "diarization": {
        "vad": {
          "chunk_max_silence": 1200,
          "chunk_max_length": 3600
        },
        "clustering":{
          "threshold":-0.4,
          "enabled": true
        }
      },
      "recognition": {
        "params": {},
        "lm": "builtin:slm/callcenter-small"
      }
    }
  }
}

API Resultado JOB¶

Obtém o resultado da transcrição de um arquivo finalizado.

Requisição

GET /trd/v3/job/result/<id>

Query

Format (csv opcional)

Header

X-License-ID

Path

id: id do processo

Response

102 - Em processo
200 - Resultado da transcrição
400 - Solicitação invalida
403 - Acesso proibido
404 - Não encontrado
422 - Erro de validação

Resultado

Retorna um JSON ou um CSV com a transcrição do arquivo.

id: identificador único do processo de transcrição
filename: nome do arquivo
status: estado do processo de transcrição
create_at: timestamp do momento de upload do arquivo
started_at: timestamp do inicio do processo de transcrição
diarized_at: timestamp do final do processo de diarização
completed_at: timestamp do final do processo de transcrição
tag: identificador opcional do arquivo
callback_urls: endereços para o webhook
media: objeto que reuni informações de media do arquivo transcrito, como seu tamanho, numero de canais e formato
config: objeto que reuni informações de configuração, dos processo de diarização e reconhecimento
segments: lista com os trechos da transcriação

Chamada REST:

curl -X GET "http://localhost:8000/trd/v3/job/result/<id>"
-H  "accept: text/csv"

curl -X GET "http://localhost:8000/trd/v3/job/result/<id>?format=csv"
-H  "accept: text/csv"

Resultado JSON:

{
  "job": {
    "id": "5fc90f68eee464d8c64c7ff7",
    "filename": "nas.wav",
    "status": "COMPLETED",
    "created_at": "2020-12-03T13:16:40.468000-03:00",
    "started_at": "2020-12-03T13:16:40.576000-03:00",
    "diarized_at": "2020-12-03T13:16:40.926000-03:00",
    "completed_at": "2020-12-03T13:16:41.572000-03:00",
    "tag": "teste",
    "callback_urls": [],
    "media": {
      "md5": "18eef3c06a975dc8cd1adad4ae662824",
      "size": 72544,
      "input": {
        "sample_rate": 8000,
        "channels": 1,
        "bit_rate": 128000,
        "format": "Wave",
        "codec": ""
      },
      "output": {
        "redundant_channel": false,
        "channels": [
          {
            "channel": 1,
            "duration": 4.531,
            "speech": 3.2590000000000003,
            "bandwidth": 4000
          }
        ]
      }
    },
    "config": {
      "diarization": {
        "vad": {
          "chunk_max_silence": 1200,
          "chunk_max_length": 3600
        },
        "clustering":{
          "threshold":-0.4,
          "enabled": true
      },
      "recognition": {
        "params": {},
        "lm": "builtin:slm/callcenter-small"
      }
    }
  },
  "segments": [
    {
      "channel": 1,
      "speaker": "1",
      "start": 0.861,
      "end": 4.12,
      "status": "RECOGNIZED",
      "alternatives": [
        {
          "text": "a minha filha nasceu hoje ela tem dez anos",
          "words": [
            {
              "text": "a",
              "score": 98,
              "start_time": 0.000314649,
              "end_time": 0.0899809
            },
            {
              "text": "minha",
              "score": 100,
              "start_time": 0.0899809,
              "end_time": 0.45
            },
            {
              "text": "filha",
              "score": 100,
              "start_time": 0.45,
              "end_time": 0.87
            },
            {
              "text": "nasceu",
              "score": 100,
              "start_time": 0.87,
              "end_time": 1.3199999
            },
            {
              "text": "hoje",
              "score": 100,
              "start_time": 1.3199999,
              "end_time": 1.77
            },
            {
              "text": "ela",
              "score": 98,
              "start_time": 1.86,
              "end_time": 2.1299999
            },
            {
              "text": "tem",
              "score": 99,
              "start_time": 2.1299999,
              "end_time": 2.339976
            },
            {
              "text": "dez",
              "score": 100,
              "start_time": 2.34,
              "end_time": 2.6699998
            },
            {
              "text": "anos",
              "score": 100,
              "start_time": 2.6699998,
              "end_time": 3.12
            }
          ],
          "score": 99,
          "lm": "builtin:slm/callcenter-small"
        }
      ]
    }
  ]
}

API Parar JOB¶

Interrompe o processo de transcrição.

Requisição

POST /trd/v3/job/stop/<id>

Header

X-License-ID

Path

id: id do processo

Response

200 - Resultado da transcrição
400 - Solicitação invalida
401 - Não autorizado
404 - Não encontrado
422 - Erro de validação

Regras

Pelo job id, recupera o Job e “interrompe”, muda o status para STOPPED.
Interrompe apenas quando o status for QUEUED ou IN_PROGRESS.

Resultado

Retorna o objeto JOB com o formato JSON com o status do arquivo atualizado.

id: identificador único do processo de transcrição
filename: nome do arquivo
status: estado do processo de transcrição
create_at: timestamp do momento de upload do arquivo
started_at: timestamp do inicio do processo de transcrição
tag: identificador opcional do arquivo
callback_urls: endereços para o webhook
media: objeto que reuni informações de media do arquivo transcrito, como seu tamanho, numero de canais e formato
config: objeto que reuni informações de configuração, dos processo de diarização e reconhecimento

Chamada REST:

curl -X POST "http://localhost:8000/trd/v3/job/stop/<id>"
-H  "accept: application/json"

Resultado JSON:

{
  "job": {
    "id": "5fc91173eee464d8c64c807b",
    "filename": "big.wav",
    "status": "STOPPED",
    "created_at": "2020-12-03T13:25:23.378000-03:00",
    "started_at": "2020-12-03T13:25:24.192000-03:00",
    "callback_urls": [],
    "media": {
      "md5": "633644fdd31a0bbbbb5ffa6fd3fa1417",
      "size": 32958764,
      "input": {
        "sample_rate": 8000,
        "channels": 1,
        "bit_rate": 128000,
        "format": "Wave",
        "codec": ""
      },
      "output": {
        "redundant_channel": false,
        "channels": [
          {
            "channel": 1,
            "duration": 2059.92,
            "bandwidth": 4000
          }
        ]
      }
    },
    "config": {
      "diarization": {
        "vad": {
          "chunk_max_silence": 1200,
          "chunk_max_length": 3600
        },
        "clustering":{
          "threshold":-0.4,
          "enabled": true
        }
      },
      "recognition": {
        "params": {},
        "lm": "builtin:slm/callcenter-small"
      }
    }
  }
}

API Retornar JOB¶

Inicia um novo processo de transcrição para um arquivo cujo processo foi interrompido ou falhou.

Requisição

POST /trd/v3/job/retry/<id>

Header

X-License-ID

Path

id: id do processo

Response

200 - Resultado da transcrição
400 - Solicitação invalida
401 - Não autorizado
404 - Não encontrado
422 - Erro de validação

Regras

Pelo job id, recupera o Job e cria um novo job com o mesmo arquivo de áudio.
Deleta o job id antigo
O status necessário para esse método são FAILED ou STOPPED

Resultado

Retorna o objeto JOB com um novo id.

id: identificador único do processo de transcrição
filename: nome do arquivo
status: estado do processo de transcrição
create_at: timestamp do momento de upload do arquivo
tag: identificador opcional do arquivo
callback_urls: endereços para o webhook
media: objeto que reuni informações de media do arquivo transcrito, como seu tamanho, numero de canais e formato
config: objeto que reuni informações de configuração, dos processo de diarização e reconhecimento

Chamada REST:

curl -X POST "http://localhost:8000/trd/v3/job/retry/<id>"
-H  "accept: application/json"

Resultado JSON:

{
  "job": {
    "id": "5fc91355eee464d8c64c807e",
    "filename": "big.wav",
    "status": "QUEUED",
    "created_at": "2020-12-03T13:33:25.522402-03:00",
    "callback_urls": [],
    "media": {
      "md5": "633644fdd31a0bbbbb5ffa6fd3fa1417",
      "size": 32958764
    },
    "config": {
      "diarization": {
        "vad": {
          "chunk_max_silence": 1200,
          "chunk_max_length": 3600
        },
        "clustering":{
          "threshold":-0.4,
          "enabled": true
        }
      },
      "recognition": {
        "params": {},
        "lm": "builtin:slm/callcenter-small"
      }
    }
  }
}

API Remover JOB¶

Apaga um processo que foi interrompido, falhou ou terminou.

Requisição

DELETE /trd/v3/job/<id>

Header

X-License-ID

Path

id: id do processo

Response

200 - JOB removido
400 - Solicitação invalida
401 - Não autorizado
404 - Não encontrado
422 - Erro de validação

Resultado

Não existem retorno no corpo da requisição HTTP alem do status 200.

Chamada REST:

curl -X DELETE "http://localhost:8000/trd/v3/job/<id>"
-H  "accept: application/json"

API Consulta¶

Permite recuperar os registros dos Jobs, utilizando campos do registro como filtros. É possível também definir quais campos devem ser recuperados, através do recurso de projeção.

Requisição

GET /trd/v3/query/job?result=<result>&tag=<tag>&filename=<filename>&status=<status>&start_date=<start>&end_date=<end>&page=<page>&limit=<limit>

Header

X-License-ID

Path

result (opcional)
tag (opcional)
filename (opcional)
status (opcional)
start_date (opcional)
end_date (opcional)
page (opcional)
limit (opcional)

Response

200 - Resultado da consulta
400 - Solicitação invalida
401 - Não autorizado
404 - Não encontrado
422 - Erro de validação

Regras

Através da query recuperar os jobs.

Resultado

O resultado é um objeto que denominamos de JOB que possue os seguintes atributos.

page: numero da pagina que será retornada
limit: numero de item resultantes por pagina
total: numero total de jobs que se adequam a consulta
result: lista com todos os jobs

Chamada REST:

curl -X GET "http://localhost:8000/trd/v3/query/job?result=false&status=COMPLETED&start_date=2020-08-31T15%3A53%3A00-03%3A00&end_date=2021-08-31T15%3A53%3A00-03%3A00&page=1&limit=1"
-H  "accept: application/json"

Resultado JSON:

{
  "page": 1,
  "limit": 1,
  "total": 21,
  "results": [
    {
      "job": {
        "id": "5fc7baefeee464d8c64c7e1a",
        "filename": "nas.wav",
        "status": "COMPLETED",
        "created_at": "2020-12-02T13:03:59.801000-03:00",
        "started_at": "2020-12-02T13:04:04.082000-03:00",
        "diarized_at": "2020-12-02T13:04:05.041000-03:00",
        "completed_at": "2020-12-02T13:04:06.254000-03:00",
        "callback_urls": [],
        "media": {
          "md5": "18eef3c06a975dc8cd1adad4ae662824",
          "size": 72544,
          "input": {
            "sample_rate": 8000,
            "channels": 1,
            "bit_rate": 128000,
            "format": "Wave",
            "codec": ""
          },
          "output": {
            "redundant_channel": false,
            "channels": [
              {
                "channel": 1,
                "duration": 4.531,
                "speech": 3.2590000000000003,
                "bandwidth": 4000
              }
            ]
          }
        },
        "config": {
          "diarization": {
            "vad": {
              "chunk_max_silence": 1200,
              "chunk_max_length": 3600
            },
            "clustering":{
              "threshold":-0.4,
              "enabled": true
            }
          },
          "recognition": {
            "params": {},
            "lm": "builtin:slm/callcenter-small"
          }
        }
      }
    }
  ]
}