Como Usar a API do Mistral AI (Guia Passo a Passo)

A Mistral AI rapidamente se destacou com seus modelos de linguagem de alto desempenho. Se você está procurando construir um chatbot, gerar texto criativo, analisar dados, escrever código ou embutir texto para busca semântica, a API da Mistral fornece as ferramentas necessárias. Mas, como qualquer ferramenta poderosa, há uma porta de entrada: a chave da API.

Pense na chave da API como sua senha secreta ou identificador único. Ela diz à Mistral, "Ei, sou eu! Tenho permissão para usar seus serviços." Sem ela, os servidores da API não saberiam quem está fazendo a solicitação ou se estão autorizados.

Este guia é seu companheiro passo a passo para navegar pela configuração inicial, entender o cenário dos modelos da Mistral, fazer suas primeiras chamadas à API e até mesmo usar ferramentas como o APidog para interagir com a API. Vamos explicar tudo de maneira conversacional, com o objetivo de levar você de zero a fazer chamadas bem-sucedidas à API.

Tempo Estimado: A leitura e o acompanhamento podem levar de 30 a 45 minutos.
Pré-requisitos: Um entendimento básico do que é uma API é útil, mas não obrigatório. Vamos explicar os conceitos à medida que avançamos. Você também precisará de uma conexão à internet e um navegador web.

Pronto? Vamos obter essa chave da API!

💡

Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada e tudo-em-um para sua equipe de desenvolvedores trabalhar junta com máxima produtividade?

O APidog atende todas suas demandas e substitui o Postman a um preço muito mais acessível!

button

Passo 1: Configurando Sua Conta Mistral AI

Primeiramente, você precisa de uma conta na plataforma da Mistral, conhecida como "La Plateforme".

Navegue até o Console: Abra seu navegador e vá para console.mistral.ai.
Inscreva-se ou Entre:

Se você é novo, clique na opção de inscrição. Provavelmente você precisará fornecer um endereço de email e criar uma senha, ou pode se inscrever usando uma conta existente do Google ou GitHub. Siga as instruções na tela, que podem incluir a verificação do seu endereço de email.
Se você já possui uma conta, basta entrar com suas credenciais.

3. Informações de Faturamento (Importante!): Este é um passo crucial que frequentemente dificulta as pessoas. Para realmente usar a API (mesmo que você planeje usar modelos da versão gratuita inicialmente, a plataforma frequentemente exige detalhes de faturamento para ativar as chaves), você precisa configurar o faturamento.

Uma vez logado, procure uma seção normalmente rotulada como "Workspace" ou seu nome de conta na barra lateral ou menu de navegação.
Dentro dessa seção, encontre "Faturamento".
Clique nela e siga as instruções para adicionar suas informações de pagamento (geralmente um cartão de crédito). Não se preocupe, você geralmente será cobrado apenas pelo que usar, e muitos modelos podem ter níveis gratuitos ou créditos iniciais, mas ativar os pagamentos é frequentemente necessário para habilitar suas chaves da API para uso geral. A página de preços da Mistral (linkada mais tarde) contém os detalhes específicos.
Certifique-se de que seus pagamentos estejam marcados como "ativos" ou "habilitados". Pode levar alguns momentos após adicionar os detalhes para que o status seja atualizado.

Agora você tem uma conta Mistral AI pronta para uso! O próximo passo é gerar aquela chave tão importante.

Passo 2: Gerando Sua Chave Secreta da API

Com sua conta configurada e o faturamento ativado, vamos criar a chave em si.

Navegue até Chaves da API: Enquanto estiver logado no console da Mistral (console.mistral.ai), procure uma seção chamada "Chaves da API" na barra lateral ou no menu de navegação. Clique nela.
Criar uma Nova Chave: Você deve ver um botão como "Criar nova chave" ou "+ Nova Chave". Clique nele.
Dê um Nome à Sua Chave (Opcional, mas Recomendado): Você pode ser solicitado a dar um nome à sua chave. Isso é super útil para organização, especialmente se você planeja criar várias chaves mais tarde (por exemplo, uma para "Meu Projeto de Chatbot", outra para "Script de Análise de Dados"). Escolha um nome descritivo.
Gere e COPIE Sua Chave: Clique no botão final de confirmação (por exemplo, "Criar", "Gerar"). A Mistral agora gerará uma chave API única para você. Ela parecerá uma longa sequência de caracteres aleatórios, algo como sk-aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890.......
!!! PASSO CRÍTICO: SALVE SUA CHAVE SEGURO !!!

A Mistral só mostrará esta chave UMA VEZ. Se você fechar a janela ou navegar para longe sem copiá-la, você nunca a verá novamente. Você teria que gerar uma nova chave.
Copie a chave imediatamente. Clique no ícone de copiar ou selecione e copie manualmente toda a string.
Armazene-a com segurança. Use um gerenciador de senhas (como 1Password, Bitwarden, Dashlane) ou um aplicativo de anotações seguras. NÃO a salve em um arquivo de texto simples em sua área de trabalho, não envie por email não criptografado, ou não a embuta diretamente em seu código (mais sobre isso mais tarde). Trate esta chave como uma senha para sua conta bancária – qualquer um que a tiver pode fazer chamadas API cobradas à sua conta.
Não a compartilhe. Sério.

Você conseguiu! Agora você possui uma chave API da Mistral AI. Mantenha-a segura e vamos descobrir como usá-la.

Passo 3: Entendendo o Cenário dos Modelos Mistral

Antes de fazer uma chamada à API, você precisa dizer à Mistral qual modelo você deseja usar. A Mistral oferece uma variedade de modelos adaptados para diferentes tarefas, equilibrando desempenho, custo e capacidades. Escolher o correto é fundamental.

Você pode encontrar uma visão geral detalhada dos modelos aqui: Visão Geral dos Modelos Mistral

Aqui está uma rápida descrição dos tipos de modelos que você encontrará:

Modelos Premier: Estes são os modelos de maior desempenho da Mistral, geralmente exigindo pagamento.

Mistral Large: Seu modelo principal, projetado para tarefas de raciocínio complexo. Ele possui uma janela de contexto grande (pode lidar com muito texto) e forte desempenho em várias referências.
Codestral: Modelos especializados ajustados para tarefas de geração, conclusão e explicação de código. Excelente para desenvolvedores.
Pixtral Large: Um poderoso modelo multimodal capaz de entender tanto texto quanto imagens.
Mistral Embed: Um modelo altamente eficiente projetado especificamente para criar representações numéricas (embeddings) de textos para tarefas como busca semântica, agrupamento e classificação.
Mistral Moderation: Uma ferramenta para detectar conteúdo prejudicial ou indesejado em texto.
Mistral OCR: Serviço para extrair texto intercalado com imagens de documentos.
Modelos especializados como Mistral Saba (para línguas do Oriente Médio/Ásia do Sul) ou Ministral (modelos de borda eficientes).

Modelos Gratuitos (Frequentemente com Pesos Abertos): Esses modelos podem ter pesos disponíveis sob licenças permissivas (como Apache 2.0), o que significa que a comunidade de IA pode estudá-los e construir sobre eles. Eles costumam estar disponíveis via API também, às vezes com camadas gratuitas mais generosas ou custos mais baixos.

Mistral Small: Um modelo menor, mas altamente capaz, equilibrando desempenho e eficiência. Frequentemente um ótimo ponto de partida.
Modelos mais antigos como Mistral 7B ou Mixtral 8x7B ainda podem estar listados, mas podem estar se tornando obsoletos (veja abaixo).

Versionamento de Modelo e Tags latest:

Você notará que os modelos frequentemente têm nomes como mistral-large-latest ou mistral-large-2411.

*-latest: Essa tag sempre aponta para a versão estável mais recente desse modelo (por exemplo, mistral-large-latest atualmente aponta para mistral-large-2411). Usar latest é conveniente para ter sempre as funcionalidades mais novas, mas esteja ciente de que o modelo subjacente pode mudar, o que pode alterar ligeiramente o comportamento ou os resultados ao longo do tempo.
*-YYYYMM (por exemplo, mistral-large-2411): Isso se refere a uma versão específica e datada do modelo (lançado em novembro de 2024 neste exemplo). Usar uma versão datada garante consistência. Sua aplicação sempre atingirá a exata mesma versão do modelo, o que é crucial para ambientes de produção onde o comportamento previsível é fundamental.

Recomendação: Para desenvolvimento e exploração, latest é aceitável. Para aplicações em produção, considere fortemente usar uma versão datada para estabilidade.

Descontinuação de Modelos:

A IA se move rápido! A Mistral lança continuamente modelos novos e melhores. Como parte desse ciclo, modelos mais antigos são eventualmente descontinuados e aposentados. A página de Visão Geral dos Modelos inclui uma seção sobre modelos legados, mostrando suas datas de descontinuação e aposentadoria. Sempre verifique isso se você depende de um modelo mais antigo e planeje sua migração para alternativas mais novas com antecedência.

Escolhendo um Modelo:

Tarefa: O que você precisa fazer? (Chat, código, embeddings, análise de imagem?)
Complexidade: Quão difícil é a tarefa? (Perguntas e respostas simples vs. raciocínio sutil?)
Custo: Verifique a página de preços! Modelos maiores geralmente custam mais.
Velocidade: Modelos menores são tipicamente mais rápidos.

Comece com um modelo menor e mais barato (como mistral-small-latest) e veja se atende às suas necessidades. Se não, escale para modelos maiores ou mais especializados.

Passo 4: Fazendo Sua Primeira Chamada à API (Conclusão de Chat) com Python

Vamos fazer algo acontecer! O caso de uso mais comum é a conclusão de chat – dando ao modelo um prompt ou um histórico de conversa e obtendo uma resposta. O endpoint principal da Mistral para isso é /v1/chat/completions.

Usaremos o modelo mistral-large-latest para este exemplo, mas você pode substituir pelo nome de qualquer modelo de chat apropriado.

Aviso de Segurança Importante: Nos exemplos abaixo, frequentemente usamos os.environ["MISTRAL_API_KEY"] (Python) ou process.env.MISTRAL_API_KEY (TypeScript). Isso assume que você definiu sua chave da API como uma variável de ambiente chamada MISTRAL_API_KEY. Isso é altamente recomendado em vez de colar a chave diretamente em seu código.

Como definir uma variável de ambiente (temporária para a sessão do terminal):
Mac/Linux: export MISTRAL_API_KEY='sua_chave_api_real_aqui'
Windows (Prompt de Comando): set MISTRAL_API_KEY=sua_chave_api_real_aqui
Windows (PowerShell): $env:MISTRAL_API_KEY='sua_chave_api_real_aqui'
Substitua sua_chave_api_real_aqui pela chave que você salvou. Lembre-se de omitir as aspas se estiver usando o Prompt de Comando do Windows. Para uma configuração mais permanente, pesquise como definir variáveis de ambiente de forma persistente em seu sistema operacional.

Instale a biblioteca:

pip install mistralai

Crie um arquivo Python (por exemplo, mistral_test.py):

import os
from mistralai.client import MistralClient
from mistralai.models.chat_completion import ChatMessage

# Carrega a chave da API das variáveis de ambiente
api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
    raise ValueError("Variável de ambiente MISTRAL_API_KEY não configurada!")

# Defina o modelo que deseja usar
model_name = "mistral-large-latest" # Ou escolha outro modelo

# Inicialize o cliente Mistral
client = MistralClient(api_key=api_key)

print(f"Enviando solicitação ao modelo: {model_name}")

# Defina as mensagens da conversa
# A lista 'messages' contém o histórico do chat ou um único prompt do usuário
messages = [
    ChatMessage(role="user", content="Qual é o melhor queijo francês?")
    # Você pode adicionar mais mensagens para o histórico da conversa:
    # ChatMessage(role="assistant", content="Existem muitos queijos franceses maravilhosos! Depende do seu gosto. Você prefere queijo macio, duro ou azul?"),
    # ChatMessage(role="user", content="Eu prefiro queijo macio.")
]

try:
    # Faça a chamada à API para o endpoint de conclusões de chat
    chat_response = client.chat(
        model=model_name,
        messages=messages,
        # Parâmetros opcionais:
        # temperature=0.7, # Controla a aleatoriedade (0.0 = determinístico, 1.0 = mais aleatório)
        # max_tokens=150   # Limita o comprimento da resposta
    )

    # Imprima a resposta do modelo
    if chat_response.choices:
        print("Resposta do Modelo:")
        print(chat_response.choices[0].message.content)
    else:
        print("Nenhuma resposta recebida.")

    # Você também pode imprimir o objeto de resposta completo para ver detalhes de uso, etc.
    # print("\nObjeto de Resposta Completo:")
    # print(chat_response)

except Exception as e:
    print(f"Ocorreu um erro: {e}")

Execute o script:

python mistral_test.py

Você deve ver a resposta do modelo impressa em seu terminal!

Passo 5: Testando Embeddings da Mistral AI com a API

A Mistral não é apenas sobre chat! Vamos olhar outra capacidade chave: Embeddings. Embeddings transformam texto em vetores numéricos que capturam o significado semântico. Textos com significados semelhantes terão vetores próximos no espaço vetorial. Isso é fundamental para RAG (Geração Aumentada por Recuperação), busca semântica, sistemas de recomendação, etc.

O modelo de embeddings da Mistral é acessado via o endpoint /v1/embeddings, geralmente usando o identificador de modelo mistral-embed.

Vamos ver como obter embeddings para algumas frases com Python:

import os
from mistralai.client import MistralClient

api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
    raise ValueError("Variável de ambiente MISTRAL_API_KEY não configurada!")

model_name = "mistral-embed"
client = MistralClient(api_key=api_key)

print(f"Solicitando embeddings usando o modelo: {model_name}")

texts_to_embed = [
    "A Mistral AI fornece modelos de linguagem poderosos.",
    "Embeddings são representações numéricas de texto.",
    "Como está o tempo hoje?"
]

try:
    embeddings_response = client.embeddings(
        model=model_name,
        input=texts_to_embed
    )

    # A resposta contém uma lista de objetos de embedding, cada um com o vetor
    print(f"Recebidos {len(embeddings_response.data)} embeddings.")

    # Imprima as primeiras dimensões do primeiro embedding como exemplo
    if embeddings_response.data:
        first_embedding_vector = embeddings_response.data[0].embedding
        print(f"Dimensões de cada embedding: {len(first_embedding_vector)}")
        print(f"Primeiras 5 dimensões do primeiro embedding: {first_embedding_vector[:5]}")

    # Normalmente, você armazenaria esses vetores para uso posterior
    # print("\nResposta Completa dos Embeddings:")
    # print(embeddings_response)

except Exception as e:
    print(f"Ocorreu um erro: {e}")

Execute este script Python, e você verá as dimensões dos embeddings e uma amostra do primeiro.

Outras Capacidades:

A Mistral oferece ainda mais! Embora não detalharemos o código aqui, não deixe de explorar a documentação oficial para:

Conclusão (Legado): Embora o chat seja frequentemente preferido, pode haver endpoints de conclusão mais simples discutidos aqui: Capacidades de Conclusão da Mistral
Compreensão de Documentos (OCR): Extração de texto de documentos, potencialmente lidando com layouts e imagens: Capacidades de Documentos da Mistral
Chamada de Funções: Permitir que modelos interajam com ferramentas e APIs externas.
Ajuste Fino: Personalizando modelos com seus próprios dados (geralmente um recurso empresarial).

Consulte sempre a documentação oficial da Mistral AI para obter as informações mais atualizadas sobre endpoints, parâmetros e capacidades.

Passo 6: Compreendendo Preços e Monitorando o Uso

Usar modelos poderosos de IA geralmente tem um custo. É crucial entender como a Mistral precifica o uso de sua API.

Os preços variam por modelo: Modelos maiores e mais capazes geralmente custam mais por token (entrada e saída) do que modelos menores. Modelos de embedding têm sua própria precificação, geralmente baseada no número de tokens processados.
Tokens: Modelos de IA processam texto em partes chamadas tokens. Um token não é exatamente uma palavra; pode ser uma palavra, parte de uma palavra ou pontuação. Aproximadamente, 1000 tokens correspondem a cerca de 750 palavras, mas isso varia. Os preços são normalmente especificados como "custo por 1 milhão de tokens de entrada" e "custo por 1 milhão de tokens de saída".
Verifique a Página Oficial de Preços: Os preços podem mudar. Consulte sempre a página oficial de preços da Mistral AI para os últimos detalhes. Você geralmente pode encontrar um link para isso em seu site principal ou dentro da documentação de Visão Geral dos Modelos.
Monitore Seu Uso: O console da Mistral AI (console.mistral.ai) geralmente tem uma seção (frequentemente sob "Faturamento" ou "Uso") onde você pode rastrear suas chamadas à API e custos associados. Verifique isso regularmente para evitar surpresas.
Defina Orçamentos/Alertas: Se a plataforma permitir, defina limites de gastos ou alertas para notificá-lo se seu uso exceder certos limites.

Esteja ciente de seu uso, especialmente ao desenvolver aplicativos que possam fazer muitas chamadas. Otimize seus prompts e escolha o modelo mais econômico que atenda às suas necessidades.

Passo 7: Fazendo Chamadas à API com APidog

Embora codificar seja comum, às vezes você quer uma interface gráfica para testar rapidamente os endpoints da API. Ferramentas como Postman, Insomnia, ou APidog são excelentes para isso. Vamos passar pela utilização do APidog para fazer a mesma chamada de conclusão de chat que antes.

Baixe e Instale o APidog: Se você ainda não fez isso, baixe o APidog de seu site oficial e instale-o em seu computador.

Inicie o APidog: Abra o aplicativo.

Crie uma Nova Solicitação: Você provavelmente verá um botão "+" ou uma opção para criar uma "Nova Solicitação". Clique nele.

Defina o Método HTTP e a URL:

Na área de solicitação, encontre o dropdown para o método HTTP (geralmente padrão para GET). Altere para POST.
No campo de entrada de URL ao lado, insira o endpoint de conclusões de chat da Mistral: https://api.mistral.ai/v1/chat/completions

Configure a Autorização:

Procure abas abaixo da barra de URL como "Params", "Authorization", "Headers", "Body". Clique na aba "Authorization".
No dropdown "Type" dentro desta aba, selecione "Bearer Token".
Um campo rotulado "Token" aparecerá à direita. Cole sua Chave da API Mistral salva neste campo.

Defina os Cabeçalhos da Solicitação:

Clique na aba "Headers".
Você precisa adicionar dois cabeçalhos:
Na primeira linha vazia sob "Key", digite Content-Type. Na coluna "Value" ao lado, digite application/json.
Na próxima linha vazia, digite Accept para "Key", e application/json para "Value".
Defina também Authorization: Bearer $MISTRAL_API_KEY

Forneça o Corpo da Solicitação:

Clique na aba "Body".
Selecione o botão de opção "raw".
Logo à direita de "raw", geralmente há um menu suspenso mostrando o formato (por exemplo, "Text"). Altere este menu para "JSON".
Na grande área de texto abaixo, cole a carga JSON para sua solicitação:

{
    "model": "mistral-large-latest",
    "messages": [{"role": "user", "content": "Quem é o pintor francês mais renomado?"}]
}

Envie a Solicitação: Encontre o botão "Enviar" (geralmente exibido em destaque perto da barra de URL) e clique nele.

Veja a Resposta: O APidog fará a chamada para a API da Mistral. A resposta do servidor aparecerá na seção inferior da janela do APidog, geralmente sob uma aba "Response" ou "Body". Você deve ver a resposta JSON, incluindo a resposta do modelo dentro de choices[0].message.content. Você também pode inspecionar os cabeçalhos de resposta e códigos de status (esperançosamente 200 OK!).

Usar uma ferramenta como o APidog é fantástico para experimentar diferentes modelos, prompts e parâmetros sem escrever código.

Passo 8: Melhores Práticas & Segurança (Um Rápido Resumo)

Trabalhar com chaves da API requer responsabilidade. Vamos reiterar alguns pontos cruciais:

NEVER Hardcode Keys: Não cole sua chave da API diretamente em seu código-fonte (my_key = "sk-..."). Se você cometer este código em um repositório público (como o GitHub), sua chave será exposta, e outros poderão usá-la, acumulando encargos em sua conta.
Use Variáveis de Ambiente: Como mostrado nos exemplos de código, carregar chaves de variáveis de ambiente (os.environ, process.env) é uma prática padrão muito mais segura.
Ferramentas de Gerenciamento Secreto: Para aplicativos mais robustos, especialmente em ambientes de equipe ou implementações na nuvem, use serviços dedicados de gerenciamento de segredos (como AWS Secrets Manager, Google Secret Manager, HashiCorp Vault).
Menor Privilégio: Se a Mistral permitir a criação de chaves com permissões específicas (isso nem sempre está disponível), crie chaves que apenas tenham as permissões necessárias para um aplicativo específico.
Rotação de Chaves: Para maior segurança, considere gerar novas chaves periodicamente e aposentar as antigas (por exemplo, a cada poucos meses), embora isso exija a atualização de seus aplicativos.
Monitore Regularmente: Fique de olho no seu painel de uso no console da Mistral. Atividades incomuns podem indicar uma chave comprometida.

Conclusão: Vá em Frente e Construa!

Você navegou com sucesso pelo processo de obtenção e uso de uma chave da API da Mistral AI! Nós cobrimos:

Configurando sua conta Mistral e ativando o faturamento.
Gerando e armazenando com segurança sua chave API exclusiva.
Entendendo os diferentes modelos da Mistral e como escolher um.
Fazendo chamadas à API usando Python, TypeScript e cURL para conclusões de chat e embeddings.
Verificando preços e monitorando seu uso.
Usando uma ferramenta GUI como o APidog para fácil teste de API.
Reforçando as melhores práticas essenciais de segurança.

A API da Mistral é uma porta de entrada para capacidades de IA incrivelmente poderosas. Sua chave da API é a chave literal para desbloquear esse potencial. Seguindo os passos e as melhores práticas descritas aqui, você está no caminho certo para integrar IA de ponta em seus próprios projetos.

Não hesite em explorar a documentação oficial da Mistral ainda mais – é a fonte definitiva de verdade para todos os parâmetros, modelos e recursos avançados disponíveis.

Feliz construção!

💡

button