Como Usar a API Mistral Large 4

Mistral Large 4 foi lançado na API da Mistral em 6 de outubro de 2026, três semanas antes da disponibilização de seus pesos abertos. Se você quer testar o “Le Chonk” de 1 trilhão de parâmetros agora, a API é a única opção. Durante a prévia pública, a Mistral lista o modelo por US$ 0,68 por milhão de tokens de entrada e US$ 2,09 por milhão de tokens de saída — metade do preço de tabela de US$ 1,36 / US$ 4,18.

Experimente o Apidog hoje

Este guia mostra como fazer sua primeira chamada em poucos minutos e cobre os pontos que mais exigem atenção na implementação: chunks de raciocínio, imagens, chamadas de função, saída JSON e estimativa de custos. Você também pode salvar e reproduzir cada requisição no Apidog para comparar o Large 4 com os modelos já usados no seu stack.

Novo no modelo? Leia primeiro Mistral está de volta: Le Chonk supera GPT-6 Astra e Claude no Cyber para os benchmarks e o contexto da manchete de cyber.

O que você precisa

Item	Valor
URL base	https://api.mistral.ai/v1
Autenticação	Authorization: Bearer $MISTRAL_API_KEY
ID do modelo	mistral-large-4 (alias: mistral-large-4-0)
Endpoint principal	POST /v1/chat/completions
Janela de contexto	1M tokens
Tipos de entrada	Texto, imagens
SDK Python	pip install mistralai
SDK TypeScript	npm install @mistralai/mistralai

Passo 1: obtenha uma chave de API

1. Faça login no Mistral Studio — anteriormente chamado La Plateforme.
2. Abra API Keys e crie uma chave.
3. Use um nome que identifique o ambiente, como local-dev, ci-staging ou production.
4. Copie a chave imediatamente. O Studio não a exibirá novamente.
5. Exporte-a no shell:

export MISTRAL_API_KEY="sua-chave-aqui"

Não envie a chave para o Git. Se ela for usada por múltiplas ferramentas ou ambientes, aplique rotação e escopo seguindo estas melhores práticas de gerenciamento de chaves de API.

Passo 2: faça a primeira chamada

Comece com uma requisição curl para validar chave, endpoint e acesso ao modelo:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {
        "role": "user",
        "content": "Me dê três casos de borda para testar em uma API de paginação."
      }
    ]
  }'

Uma resposta bem-sucedida inclui:

• choices[0].message.content: resposta gerada;
• usage.prompt_tokens: tokens de entrada;
• usage.completion_tokens: tokens de saída;
• usage.total_tokens: total consumido.

Diagnóstico rápido:

• 401 Unauthorized: a chave está ausente, inválida ou não foi exportada.
• 404 para o modelo: confirme que o ID é exatamente mistral-large-4.

A mesma chamada em Python

Instale o SDK:

pip install mistralai

Depois, crie a chamada:

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.chat.complete(
    model="mistral-large-4",
    messages=[
        {
            "role": "user",
            "content": "Me dê três casos de borda para testar em uma API de paginação.",
        }
    ],
)

print(response.choices[0].message.content)

A mesma chamada em TypeScript

Instale o pacote:

npm install @mistralai/mistralai

Use o cliente:

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

const response = await client.chat.complete({
  model: "mistral-large-4",
  messages: [
    {
      role: "user",
      content: "Me dê três casos de borda para testar em uma API de paginação.",
    },
  ],
});

console.log(response.choices[0].message.content);

Passo 3: salve a requisição no Apidog

Comparar modelos manualmente com curl deixa de ser prático assim que você começa a testar prompts reais. Para salvar uma versão reproduzível no Apidog:

1. Crie uma requisição HTTP:

   POST https://api.mistral.ai/v1/chat/completions

1. Crie uma variável de ambiente chamada MISTRAL_API_KEY.
2. Adicione o cabeçalho:

   Authorization: Bearer {{MISTRAL_API_KEY}}

1. Cole o JSON do passo anterior no corpo da requisição.
2. Clique em Send.
3. Duplique a requisição e altere apenas o campo model, por exemplo para mistral-medium-3-5.
4. Execute ambas com o mesmo prompt.

Com isso, você terá requisições salvas para comparar corpo da resposta, status, tempo de execução, tamanho da resposta e os valores de usage.

Também vale adicionar uma asserção pós-resposta para garantir que choices[0].message.content não esteja vazio. Isso transforma a requisição em um teste de fumaça reutilizável para executar sempre que a Mistral atualizar a prévia.

Passo 4: controle o raciocínio com reasoning_effort

O Large 4 é um modelo híbrido: pode responder rapidamente ou executar raciocínio passo a passo. O comportamento é controlado pelo parâmetro reasoning_effort.

Valor	Comportamento	Use para
"none"	Pensamento mínimo, sem chunk de raciocínio na resposta	Chat, extração, classificação e fluxos sensíveis à latência
"high"	Retorna um chunk de pensamento antes da resposta final	Depuração, planejamento multi-etapas, matemática e revisão de código

Exemplo com raciocínio alto:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {
        "role": "user",
        "content": "Nossa API retorna 200 com um corpo vazio sob carga. Liste as prováveis causas em ordem de probabilidade."
      }
    ],
    "reasoning_effort": "high"
  }'

Atenção: content deixa de ser uma string

Esse é um ponto comum de quebra em parsers. Com reasoning_effort: "high", message.content pode deixar de ser uma string e passar a ser uma lista de chunks:

• chunk thinking: rastreamento de raciocínio;
• chunk text: resposta final.

Portanto, não assuma que response.choices[0].message.content sempre é texto simples. Extraia explicitamente os chunks de tipo text:

response = client.chat.complete(
    model="mistral-large-4",
    messages=[
        {
            "role": "user",
            "content": "Por que uma resposta 200 teria um corpo vazio?",
        }
    ],
    reasoning_effort="high",
)

content = response.choices[0].message.content

if isinstance(content, str):
    answer = content
else:
    answer = "".join(chunk.text for chunk in content if chunk.type == "text")

print(answer)

Tokens de raciocínio são cobrados como tokens de saída. Use "none" como padrão e habilite "high" apenas nos fluxos que justificam maior custo e latência.

Passo 5: envie uma imagem

O Large 4 é multimodal e aceita texto e imagem na mesma mensagem. Para enviar uma imagem por URL, use partes de conteúdo:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Esta é uma captura de tela do nosso painel de erros da API. Qual endpoint está falhando mais e qual é o código de erro?"
          },
          {
            "type": "image_url",
            "image_url": "https://example.com/dashboard.png"
          }
        ]
      }
    ]
  }'

Para arquivos locais, envie uma URL de dados base64:

{
  "type": "image_url",
  "image_url": "data:image/png;base64,<codificado>"
}

A Mistral informa que o Large 4 pontua 42% no benchmark de aterramento visual Dense 200, ligeiramente à frente dos 41% do GPT-6 Astra. Isso torna capturas de tela de dashboards, gráficos e estados de interface casos de uso razoáveis para testar.

Passo 6: implemente chamada de função

Na chamada de função, você descreve as ferramentas disponíveis, o modelo decide se precisa usá-las e seu código executa a operação.

Defina uma ferramenta para consultar pedidos:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": "Consulta o status de um pedido pelo seu ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "O ID do pedido, ex: ORD-1042",
                    }
                },
                "required": ["order_id"],
            },
        },
    }
]

messages = [
    {
        "role": "user",
        "content": "Onde está o pedido ORD-1042?",
    }
]

response = client.chat.complete(
    model="mistral-large-4",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]

print(tool_call.function.name)
print(tool_call.function.arguments)

O modelo apenas solicita a ferramenta. Seu serviço precisa validar os argumentos, executar a função e devolver o resultado usando o mesmo tool_call_id:

import json

result = {
    "order_id": "ORD-1042",
    "status": "enviado",
    "eta": "2026-10-09",
}

messages.append(response.choices[0].message)

messages.append(
    {
        "role": "tool",
        "name": "get_order_status",
        "content": json.dumps(result),
        "tool_call_id": tool_call.id,
    }
)

final = client.chat.complete(
    model="mistral-large-4",
    messages=messages,
    tools=tools,
)

print(final.choices[0].message.content)

O campo parameters usa JSON Schema. Se sua API já possui uma especificação OpenAPI, você pode aproveitar o schema de requisição de cada operação ao definir as ferramentas.

Projetar a especificação no Apidog antes da integração ajuda a manter as definições de ferramentas e a API real sincronizadas.

Passo 7: obtenha JSON estruturado

Para fluxos que exigem saída legível por máquina, use response_format:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {
        "role": "user",
        "content": "Extraia o método, caminho e código de status de: GET /v1/users/42 retornou 404. Responda em JSON."
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

Inclua a instrução para responder em JSON tanto no prompt quanto em response_format.

Para formatos estritos, a Mistral também suporta:

{
  "type": "json_schema",
  "json_schema": {
    "...": "schema completo"
  }
}

No Apidog, valide a resposta com uma asserção de JSON Schema. Assim, uma mudança de formato falha no teste antes de quebrar um serviço downstream.

Quanto custa

Uso	Preço de prévia	Preço de tabela
Entrada, por 1M tokens	US$ 0,68	US$ 1,36
Entrada em cache, por 1M tokens	US$ 0,07	US$ 0,14
Saída, por 1M tokens	US$ 2,09	US$ 4,18

Considere um agente que realiza 10.000 chamadas por dia, cada uma com:

• 3.000 tokens de entrada;
• 500 tokens de saída;
• 2.500 dos 3.000 tokens de entrada atendidos pelo cache.

A estimativa diária fica assim:

• Entrada em cache: 25M tokens × US$ 0,07 = aproximadamente US$ 1,75/dia.
• Entrada nova: 5M tokens × US$ 0,68 = aproximadamente US$ 3,40/dia.
• Saída: 5M tokens × US$ 2,09 = aproximadamente US$ 10,45/dia.
• Total: aproximadamente US$ 15,60/dia durante a prévia.

No preço de tabela, a mesma carga ficaria em torno de US$ 31 por dia.

A mesma carga de trabalho no GPT-6 Astra, listado a US$ 10 / US$ 50 por milhão antes de descontos de cache, custaria várias centenas de dólares por dia. Como a Mistral não informou quando a prévia termina, planeje o orçamento usando o preço de tabela.

Erros comuns

Erro	Causa provável	Correção
401 Unauthorized	Chave ausente ou incorreta	Verifique echo $MISTRAL_API_KEY e confirme o prefixo Bearer
404 / modelo inválido	Erro de digitação no ID	Use mistral-large-4 exatamente
422 Unprocessable Entity	Corpo malformado, geralmente em tools	Valide o JSON Schema em parameters
429 Too Many Requests	Limite de taxa do workspace	Aguarde e tente novamente ou aumente os limites no Studio
Resposta impressa como lista	reasoning_effort: "high" retorna chunks	Extraia os chunks text, como no Passo 4

FAQ

Mistral Large 4 é compatível com OpenAI?

O formato da requisição é bastante próximo: model, messages, tools, tool_choice e response_format funcionam como esperado. Para maior segurança, use os SDKs da Mistral ou HTTP puro. A saída de raciocínio usa o formato de chunks da própria Mistral.

Quando posso executá-lo localmente?

A Mistral informa que os pesos serão lançados até o fim de outubro de 2026. Com 1,05T de parâmetros totais, o modelo exige hardware de servidor com múltiplas GPUs. Enquanto isso, consulte o guia para executar Mistral 3 localmente para trabalhar com modelos menores.

A prévia é estável o suficiente para produção?

Ainda não. O modelo está identificado como prévia pública e pode mudar antes do lançamento dos pesos. Mantenha testes fixados, execute-os novamente quando a Mistral atualizar o modelo e configure um modelo de fallback.

Posso usar o Large 4 com código Mistral existente?

Sim. A URL base, autenticação e SDK são os mesmos. Basta alterar a string model para mistral-large-4.

Se você vem do Medium 3.5, consulte este guia da API Mistral Medium 3.5 para os componentes que permanecem iguais.

Conclusão

Você consegue sair do zero para uma chamada funcional em poucos minutos. O próximo passo é executar seus prompts reais lado a lado no Large 4 e no modelo atual.

Salve as duas requisições no Apidog, adicione asserções de status e formato de resposta e compare qualidade, latência e consumo de tokens. Assim, você poderá decidir rapidamente se o Le Chonk merece entrar no seu stack enquanto o preço de prévia ainda está pela metade.