Visão Geral de Inteligência Artificial
As rotas de IA se dividem em quatro grupos: configuração de provedores da conta, utilitários (transcrição, leitura de imagem, estruturação de texto), apoio à decisão clínica (hipóteses diagnósticas e sugestão de desfecho) e chat da consulta. O comportamento de cada agente de IA (modelo, instruções, temperatura) é configurado à parte, em IA — Configuração de Agentes.
Base
https://api-dev.imagemais.com.br/api/ai
Todas as rotas exigem autenticação e são isoladas pela conta (accountId) do token.
Provedores e capacidades
A conta pode usar a chave de API da plataforma (padrão) ou cadastrar a própria chave de um provedor. Cada capacidade pode apontar para um provedor diferente:
| Capacidade | Usada em |
|---|---|
TEXT_GENERATION | Estruturação de texto, extração de campos, chats e agentes |
VISION_OCR | Leitura de imagens e exames (OCR) |
AUDIO_TRANSCRIPTION | Transcrição de áudio |
Provedores disponíveis: OPENAI e GROK — hoje os dois atendem as três capacidades. Sem preferência salva, a capacidade usa OPENAI com a chave da plataforma.
- Salvar a chave do provedor (armazenada criptografada; as respostas nunca devolvem a chave).
- Testar a conexão com a chave salva.
- Definir o provedor de cada capacidade.
- Conferir o estado em Buscar Configuração de IA.
Remover a chave de um provedor também remove as capacidades que apontavam para ele; Resetar o Provedor volta uma capacidade ao padrão.
Utilitários
| Rota | Entrada | Saída |
|---|---|---|
| Transcrever Áudio | Arquivo de áudio (mp3, wav, webm, m4a, ogg, aac) | Texto transcrito |
| Transcrever Imagem | Imagem | Texto extraído |
| Gerar Avaliação em JSON | Texto + instruções | JSON estruturado |
| Corrigir Campo por Voz | Conteúdo atual do campo + transcrição de um comando de voz | Texto corrigido ou preenchido |
O texto transcrito passa por uma normalização que remove acentos. Considere isso ao exibir ou comparar o resultado.
Apoio à decisão clínica
Usadas na decisão da triagem, a partir do caso descrito em texto:
- Gerar Hipóteses Diagnósticas — executa o agente
diagnosis-assistante devolve hipóteses com CID. - Sugerir Desfecho da Triagem — executa o agente
outcome-assistante devolve os desfechos sugeridos com confiança, justificativa, achados e alertas (redFlags).
As sugestões não são gravadas na triagem. Quem registra a hipótese e o desfecho é o médico, em Registrar Desfecho — o campo diagnosisSelection[].fromAi indica quais hipóteses vieram da sugestão.
Chat da consulta
Um chat com o agente consultation-chat, que conhece os dados da consulta:
- Buscar ou Criar Conversa — devolve o histórico; cria a conversa na primeira chamada.
- Enviar Mensagem — devolve o histórico atualizado com a resposta do agente.
- Deletar Conversa — apaga a conversa e permite começar outra.
As rotas /thread são a versão legada do mesmo chat e devem ser substituídas pelas de /conversation.
Rotas
| Método | Rota | Permissão | Descrição |
|---|---|---|---|
GET | /ai/settings | read_configurations | Provedores e capacidades |
POST | /ai/settings/credentials | read_configurations | Salva a chave de um provedor |
POST | /ai/settings/credentials/{provider}/test | read_configurations | Testa a chave |
DELETE | /ai/settings/credentials/{provider} | read_configurations | Remove a chave |
PUT | /ai/settings/capabilities/{capability} | read_configurations | Define o provedor da capacidade |
DELETE | /ai/settings/capabilities/{capability} | read_configurations | Volta ao padrão |
POST | /ai/transcription | — | Transcreve áudio |
POST | /ai/vision | — | Lê imagem |
POST | /ai/evaluation | — | Estrutura texto em JSON |
POST | /ai/correct-field | — | Corrige campo por voz |
POST | /ai/diagnosis/evaluate | — | Hipóteses diagnósticas |
POST | /ai/outcome/suggest | — | Sugestão de desfecho |
GET | /ai/consultation/{consultationId}/conversation | — | Busca ou cria a conversa |
POST | /ai/consultation/{consultationId}/conversation/message | — | Envia mensagem |
DELETE | /ai/consultation/{consultationId}/conversation | — | Deleta a conversa |
GET | /ai/consultation/{consultationId}/thread | — | Legado |
POST | /ai/consultation/{consultationId}/thread/message | — | Legado |
DELETE | /ai/consultation/{consultationId}/thread | — | Legado |
"—" na coluna de permissão: a rota não exige permissão específica, apenas autenticação.