Skip to main content

Integração via API

Este guia foi criado para ajudar você a fazer sua primeira chamada à nossa API, que responde a requisições via HTTP e suporta as seguintes funcionalidades:

  • Conversação com respostas normais
  • Conversação em stream (resposta em tempo real, por partes)
  • Transcrição de áudio (speech-to-text)
  • Síntese de fala (text-to-speech)
  • Envio de arquivos

Endereço da API

Todas as chamadas devem ser feitas para o seguinte hostname: api.evalmind.ai

Esse é o endereço base utilizado para acessar os serviços da API do evalmind chat.


Autenticação

Para que uma requisição seja aceita, é obrigatório enviar um cabeçalho de autenticação com uma chave de API válida.

O cabeçalho deve ser enviado no seguinte formato: Authorization: Bearer SUA_CHAVE_DE_API

Sem esse cabeçalho, a API não conseguirá validar a origem da requisição e o acesso será negado.


Quem pode gerar uma chave de API?

A criação de chaves de API está disponível apenas para usuários com os perfis:

  • enterprise-admin
  • admin

A geração da chave é feita pela interface administrativa web, seguindo o processo de emissão de chaves de API da plataforma.


Formato das chaves

As chaves de API do evalmind utilizam o prefixo: ev-sk-

Esse padrão ajuda a identificar rapidamente que se trata de uma chave válida da plataforma.


Como funcionam as permissões da chave?

Cada chave de API herda as permissões e características do usuário que a criou.

Isso significa que todas as operações realizadas com essa chave serão executadas em nome do usuário emissor.

Na prática, isso quer dizer que:

  • O acesso da API respeita as permissões do usuário que gerou a chave;
  • Ações feitas pela API ficam associadas a esse usuário;
  • Conversas e interações podem ser registradas na área de Monitoramento em nome do emissor da chave.
Exemplo prático

Se uma chave foi criada por um usuário administrador chamado João, qualquer integração que utilize essa chave fará operações como se estivesse atuando no contexto do João.

Assim, se o sistema externo iniciar uma conversa com o evalmind chat usando essa chave, essa conversa poderá aparecer no monitoramento vinculada a esse usuário.


Endpoints

Os endpoints disponíveis são:

EndpointFuncionalidade
/v1/chatsConversação
/v1/audio/transcribeTranscrição de áudio
/v1/audio/sythensizeSíntese de áudio
/v1/filesUpload de documentos

Conversação

A principal funcionalidade da API do evalmind chat é a conversação, que permite enviar mensagens para o serviço e receber respostas automaticamente.

A API oferece duas formas de conversação:

1. Conversação tradicional

Nesse modo, a resposta só é enviada quando estiver completamente pronta.

Características
  • Retorna o conteúdo final de uma só vez;
  • É mais simples de implementar;
  • Pode ter maior latência, já que o sistema só responde ao término do processamento.

Esse modo é indicado quando não há necessidade de exibir a resposta em tempo real para o usuário.


2. Conversação em stream

Nesse modo, a resposta é enviada em partes, à medida que vai sendo gerada.

Características
  • Entrega resultados parciais em tempo real;
  • Reduz a latência percebida pelo usuário;
  • Proporciona uma experiência mais fluida e interativa.

Esse é o modo utilizado nas interfaces web do evalmind, justamente por oferecer uma experiência melhor ao usuário final.


Iniciando uma Conversação

Para iniciar uma conversação, é necessário primeiro criar uma entidade do tipo chat. Essa criação pode ser feita de duas formas:

  • Informando um modelo padrão, por meio da propriedade model; ou
  • Informando um assistente configurado, por meio da propriedade assistant_id.

Criando um chat

O exemplo abaixo demonstra a criação de um chat utilizando um modelo padrão:

curl --request POST \
--url $HOSTNAME/v1/chats \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-4o-mini"
}'

Após a criação, a API retornará os dados da entidade chat, incluindo seu identificador. Esse identificador será utilizado nas próximas requisições de conversação.

Conversação Tradicional

Com o identificador do chat em mãos, é possível realizar uma conversação tradicional por meio da URI:

$HOSTNAME/v1/chats/$CHAT_ID/completions

O principal elemento da requisição é o campo messages, cuja estrutura segue um subconjunto do formato originalmente definido pela OpenAI.

Exemplo de Requisição

curl --request POST \
--url $HOSTNAME/v1/chats/$CHAT_ID/completions \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"messages": [
{
"role": "user",
"content": "oi"
}
]
}'

Nesse modo, a resposta é retornada apenas quando estiver completamente pronta.

Conversação em stream

Alternativamente, é possível realizar a conversação em modo stream, no qual a resposta é enviada em partes à medida que é gerada.

A URI utilizada nesse caso é:

$HOSTNAME/v1/chats/$CHAT_ID/completions/stream

Esse modo é indicado para interfaces que desejam exibir a resposta em tempo real, reduzindo a latência percebida pelo usuário.


chats/

Corpo da requisição

ParâmetroDescrição
modelModelo conforme a lista de modelos suportados
assistant_idUID do assistente
headlineTítulo da conversa

Resposta

ParâmetroDescrição
idUID da conversa
headlineTítulo da conversa
enterpriseNome da empresa
userNome do usuário
providerNome do provedor de IA
modelNome do modelo
messagesQuantidade de mensagens
createdData de criação, em segundos
typeTipo do chat
assistantUID do assistente
assistantNameNome do assistente
chat_parametersParâmetros de criação do chat

chat_parameters

ParâmetroDescrição
max_tokensQuantidade máxima de tokens
presence_penaltyPenalidade por presença
frequency_penaltyPenalidade por frequência
seedSemente
temperatureTemperatura, com padrão 1
memory_sizeTamanho da memória, com padrão 4

/chats/completion`

Requisição

ParâmetroDescrição
messagesLista de mensagens
mcp_serversLista opcional de IDs dos servidores MCP que devem ser usados na requisição
web_searchParâmetro opcional que indica se a busca web deve ser usada na requisição
O padrão é false

messages

ParâmetroDescrição
roleIndica o papel da mensagem (user ou assistant)
contentConteúdo da mensagem

Resposta

ParâmetroDescrição
messagesLista de mensagens
referencesLista de referências utilizadas a partir do RAG
usageInformações sobre o uso de tokens
successfulIndicativo de sucesso, deve ser true
errorIndicativo de erro, deve ser null

messages

ParâmetroDescrição
roleIndica o papel da mensagem (user ou assistant)
contentConteúdo da mensagem
imagesPor enquanto, nulo

usage

ParâmetroDescrição
input_tokensQuantidade de tokens de entrada
output_tokensQuantidade de tokens de saída
total_tokensQuantidade total de tokens

/v1/chats/completions/stream

Requisição:

Vide /v1/chats/completions.

Resposta:

Stream de eventos com campos id, event e data.

id: yGyyFsRkZ766ASoEUIkFA
event: open,
data: [START]

id: HYeXJsOnoLeEIKkC3kEHT
event: message
data: {"messages":[{"role":"assistant","content":"Ol\u00E1!","images":null}],"references":null,"usage":null,"successful":true,"error":null}

...

id: eQQ-u6-_Rj_gHBE0LM-Pj
event: message
data: [DONE]

O stream se inicia com um event=open e data: [START], e termina com event=message e data: [DONE].

Modelos suportados

Nota

Visto que suportamos múltiplos provedores de IA, a lista de modelos suportados é extensa, e muda com frequência. Fora isso, cada modelo tem seu conjunto particular de características, conforme observado nas próximas seções.

A coluna Entradas indica aquilo os tipos de entrada que suportamos em nossa API. Os modelos, quando acessados diretamente através do provedor de IA podem suportar outras alternativas.

Os modelos de conversação suportados são os seguintes:

ProvedorModelo (nome curto)Nome alternativoAtivoEntradasMCPJanela de Contexto
Anthropicclaude-2.0Anthropic Claude 2📄-
Anthropicclaude-2.1Anthropic Claude 2.1📄-
Anthropicclaude-3-haiku-20240307Anthropic Claude 3 Haiku (20240307)📄 🖼️200 K
Anthropicclaude-3-opus-20240229Anthropic Claude 3 Opus (20240229)📄 🖼️200 K
Anthropicclaude-3-sonnet-20240229Anthropic Claude 3 Sonnet (20240229)📄 🖼️200 K
Anthropicclaude-3-5-haiku-20241022Anthropic Claude 3.5 Haiku (20241022)📄 🖼️200 K
Anthropicclaude-3-5-sonnet-20240620Anthropic Claude 3.5 Sonnet (20240620)📄 🖼️200 K
Anthropicclaude-3-5-sonnet-20241022Anthropic Claude 3.5 Sonnet (20241022)📄 🖼️200 K
Anthropicclaude-3-7-sonnet-20250219Anthropic Claude 3.7 Sonnet (20250219)📄 🖼️200 K
Anthropicclaude-instant-1.2Anthropic Claude Instant 1.2📄-
DeepSeekdeepseek-chatDeepSeek Chat (DeepSeek-V3)📄64 K
DeepSeekdeepseek-reasonerDeepSeek Reasoner (DeepSeek-R1)📄64 K
Googlegemini-proGoogle Gemini Pro📄-
Googlegemini-1.0-proGoogle Gemini 1.0 Pro📄-
Googlegemini-1.5-proGoogle Gemini 1.5 Pro🖼️ 📄2 M
Googlegemini-1.5-flashGoogle Gemini 1.5 Flash🖼️ 📄1 M
Googlegemini-2.0-flashGoogle Gemini 2.0 Flash🖼️ 📄1 M
Googlegemini-2.0-flash-lite-preview-02-05Google Gemini 2.0 Flash Lite 02-05🖼️ 📄1 M
Googlegemini-2.5-flash-preview-04-17Google Gemini 2.0 Flash 04-17🖼️ 📄1 M
Googlegemini-2.5-pro-preview-03-25Google Gemini 2.5 Pro 03-25🖼️ 📄1 M
GroqCloudgemma2-9b-itGroqCloud Google Gemma 2📄8 K
GroqCloudllama-3.3-70b-versatileGroqCloud Meta Llama 3.3 Versatile📄128 K
GroqCloudllama-3.1-8b-instantGroqCloud Meta Llama 3.1📄128 K
GroqCloudllama-guard-3-8bGroqCloud Meta Llama Guard 3📄8 K
GroqCloudllama3-70b-8192GroqCloud Meta Llama 3 70B📄8 K
GroqCloudllama3-8b-8192GroqCloud Meta Llama 3 8B📄8 K
GroqCloudmixtral-8x7b-32768GroqCloud Mistral Mixtral📄-
GroqCloudqwen-2.5-coder-32bGroqCloud Allibaba Cloud Qwen Coder 2.5📄128 K
GroqCloudqwen-2.5-32bGroqCloud Allibaba Cloud Qwen 2.5📄128 K
GroqClouddeepseek-r1-distill-qwen-32bGroqCloud DeepSeek Qwen Distilled📄128 K
GroqClouddeepseek-r1-distill-llama-70bGroqCloud DeepSeek Llama Distilled📄128 K
GroqCloudllama-3.3-70b-specdecGroqCloud Meta Llama 3.2 70B📄8 K
GroqCloudllama-3.2-1b-previewGroqCloud Meta Llama 3.2 1B📄128 K
GroqCloudllama-3.2-3b-previewGroqCloud Meta Llama 3.2 3B📄128 K
GroqCloudllama-3.2-11b-vision-previewGroqCloud Meta Llama Vision 3.2 11B📄128 K
GroqCloudllama-3.2-90b-vision-previewGroqCloud Meta Llama Vision 3.2 90B📄128 K
Maritacasabia-2-mediumMaritaca Sabiá-2 Medium📄--
Maritacasabia-2-smallMaritaca Sabiá-2 Small📄--
Maritacasabia-3Maritaca Sabiá-3📄128 K
Maritacasabia-3-smallMaritaca Sabiá-3 Medium📄32 K
Mistralcodestral-latestCodestral📄256 K
Mistralmistral-large-latestMistral Large📄128 K
Mistralmistral-mediumMistral Medium📄128 K
Mistralopen-mistral-nemoMistral Nemo📄128 K
Mistralmistral-smallMistral Small📄32 K
Mistralmistral-tinyMistral Tiny📄128 K
OpenAIgpt-3.5-turboOpenAI GPT-3.5-Turbo📄16 K
OpenAIgpt-4OpenAI GPT-4📄8 K
OpenAIgpt-4-32kOpenAI GPT-4 32K📄32 K
OpenAIgpt-4-1106-previewOpenAI GPT-4 1106 Preview (128k)📄--
OpenAIgpt-4-turboOpenAI GPT-4 Turbo📄 🖼️--
OpenAIgpt-4.1OpenAI GPT-4.1📄 🖼️1 M
OpenAIgpt-4.1-miniOpenAI GPT-4.1 mini📄 🖼️1 M
OpenAIgpt-4.1-nanoOpenAI GPT-4.1 nano📄 🖼️32 K
OpenAIgpt-5OpenAI GPT-5📄 🖼️400 K
OpenAIgpt-5-miniOpenAI GPT-5 mini📄 🖼️400 K
OpenAIgpt-5-nanoOpenAI GPT-5 nano📄 🖼️400 K
OpenAIgpt-4oOpenAI GPT-4o📄 🖼️128 K
OpenAIgpt-4o-miniOpenAI GPT-4o Mini📄 🖼️128 K
OpenAIo1OpenAI O1📄 🖼️200 K
OpenAIo1-miniOpenAI O1 Mini📄128 K
OpenAIo3-miniOpenAI O3 Mini📄200 K
OpenAIo3-proOpenAI O3 Pro📄 🖼️200 K
OpenAIo4-miniOpenAI O4 Mini📄 🖼️200 K
PerplexitysonarPerplexity Sonar📄128 K
Perplexitysonar-proPerplexity Sonar Pro📄200 K
Perplexitysonar-small-chatPerplexity Sonar Small Chat📄--
Perplexitysonar-medium-chatPerplexity Sonar Medium Chat📄--
Perplexitysonar-small-onlinePerplexity Sonar Small Online📄--
Perplexitysonar-medium-onlinePerplexity Sonar Medium Online📄--
Perplexityllama-3.1-8b-instructPerplexity LLaMA 3.1 8b Instruct📄--
Perplexityllama-3.1-70b-instructPerplexity LLaMA 3.1 70b Instruct📄--
Perplexityllama-3.1-sonar-small-128k-chatPerplexity LLaMA 3.1 Sonar Small Chat📄--
Perplexityllama-3.1-sonar-large-128k-chatPerplexity LLaMA 3.1 Sonar Large Chat📄--
Perplexityllama-3.1-sonar-huge-128k-onlinePerplexity LLaMA 3.1 Sonar Huge Online📄--
Perplexityllama-3.1-sonar-small-128k-onlinePerplexity LLaMA 3.1 Sonar Small Online📄--
Perplexityllama-3.1-sonar-large-128k-onlinePerplexity LLaMA 3.1 Sonar LArge Online📄--
xAIgrok-3-miniGrok 3 Mini📄 🖼️128 K
xAIgrok-3Grok 3📄 🖼️128 K
xAIgrok-4Grok 4📄 🖼️256 K

Transcrição de áudio

Transcrição de áudio. Seu formato e funcionamento se baseia nas definições da OpenAI.

Para gerar uma transcrição basta enviar a requisição para a URI $HOSTNAME/v1/audio/transcribe conforme exemplo abaixo.

curl --request POST \
--url $HOSTNAME/v1/audio/transcribe \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@input.mp3' \
--form response_format=json
Informação

Para a transcrição de áudio há um limite máximo de 25MB do tamanho do arquivo.

/audio/transcribe

Requisição

ParâmetroDescrição
providerProvedor conforme lista de modelos suportados
modelModelo conforme lista de modelos suportados
languageLinguagem, que pode ser informada para melhorar a precisão da transcrição
file_nameNome do arquivo
fileCampo form-data para envio do arquivo
response_formatFormato da resposta, com padrão json

response_format

ValorDescrição
jsonFormato padrão da resposta
verbose_jsonRetorna também todos os segments

Resposta

ParâmetroDescrição
textTexto da transcrição
taskNão utilizado
languageLinguagem do áudio de entrada
durationDuração do áudio, em segundos
segmentsLista de segmentos

segments

ParâmetroDescrição
idIdentificador do segmento
seekOffset para busca no arquivo
startInstante de início
endInstante de término
textTexto do segmento
tokensLista de tokens do segmento

Modelos suportados

Os modelos de transcrição de áudio suportados são os seguintes:

ProvedorModeloNome alternativoAtivoLimite da entrada
GroqClouddistil-whisper-large-v3-enGroqCloud HuggingFace Whisper Large V325 MB
GroqCloudwhisper-large-v3GroqCloud OpenAI Whisper Large V325 MB
GroqCloudwhisper-large-v3-turboGroqCloud OpenAI Whisper Large V3 Turbo25 MB
OpenAIwhisper-1OpenAI Whisper 125 MB
OpenAIgpt-4o-mini-transcribeOpenAI GPT-4o Mini Transcribe25 MB
OpenAIgpt-4o-transcribeOpenAI GPT-4o Transcribe25 MB
Mistralvoxtral-mini-latestVoxtral Mini Latest25 MB

Síntese de áudio

Síntese de áudio, que novamente tem seu formato e funcionamento baseado nas definições da OpenAI.

Para sintetizar áudio basta enviar a requisição para a URI $HOSTNAME/v1/audio/synthesize conforme exemplo abaixo.

curl --request POST \
--url $HOSTNAME/v1/audio/synthesize \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"input": "Diga oi",
"model": "tts-1",
"voice": "nova"
}'
--output speech.mp3
Informação

Para a síntese de áudio há um limite máximo de 4096 caracteres de entrada.

/audio/synthesize

Requisição

ParâmetroDescrição
providerProvedor conforme lista de modelos suportados
modelModelo conforme lista de modelos suportados
inputTexto a ser sintetizado
voiceVoz a ser utilizada: alloy, echo, fable, onyx, nova, shimmer

Resposta:

Arquivo de áudio

Modelos suportados

Os modelos de síntese de áudio suportados são os seguintes:

ProvedorModeloNome alternativoAtivoLimite da entrada
OpenAItts-1OpenAI Text-to-Speech (TTS) 14096 caracteres
OpenAItts-1-hdOpenAI Text-to-Speech (TTS) 1 HD4096 caracteres
OpenAIgpt-4o-mini-ttsOpenAI GPT-4o Mini TTS4096 caracteres

Arquivos

Realizar o upload de documentos. O tamanho máximo do arquivo é 30mb.

Upload

Para enviar um arquivo basta enviar a requisição com o método POST para URI $HOSTNAME/v1/files conforme exemplo abaixo.

curl --request POST \
--url $HOSTNAME/v1/files \
--header 'Authorization: Bearer $API_KEY' \
--header 'Content-Type: multipart/form-data' \
--form "file=@/path/to/documento.pdf" \
ParâmetroDescrição
fileArquivo a ser enviado

Resposta:

Uma mensagem de sucesso e o uid do arquivo.

Listagem

Listar os arquivos, enviar requisição com o método GET para URI $HOSTNAME/v1/files conforme exemplo abaixo.

curl $HOSTNAME/v1/files \
--header 'Authorization: Bearer $API_KEY' \

/files

Resposta:

Os arquivos do usuário.

curl $HOSTNAME/v1/files/fileabc123 \
--header 'Authorization: Bearer $API_KEY' \

/files/{file_uid}

Requisição

ParâmetroDescrição
file_uidObtém os metadados do arquivo indicado

Resposta:

Obtém os metadados do arquivo indicado.


Deletar arquivo

Deletar o arquivo, enviar requisição com o método DELETE para URI $HOSTNAME/v1/files/{file_uid} conforme exemplo abaixo.

curl --request DELETE \
--url $HOSTNAME/v1/files/file123 \
--header 'Authorization: Bearer $API_KEY' \

/files/{file_uid}

ParâmetroDescrição
file_uidRemove o arquivo indicado

Resposta:

O status de sucesso da resposta.