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 de seus pesos abertos. Se você quiser experimentar o “Le Chonk” de 1 trilhão de parâmetros agora, a API é a única maneira de acessá-lo, e no momento é também a maneira mais barata: a Mistral o lista por $0,68 por milhão de tokens de entrada e $2,09 por milhão de tokens de saída durante a prévia pública, metade do preço de tabela de $1,36 / $4,18.

Este guia leva você do zero a uma primeira chamada funcional em cerca de cinco minutos, depois aborda as partes que costumam causar problemas: chunks de raciocínio, entrada de imagem, chamada de função, saída JSON e custo. Cada requisição pode ser salva e reproduzida no Apidog para que você possa comparar o Large 4 com qualquer modelo que você execute hoje.

Novo no próprio modelo? Leia Mistral está de volta: Le Chonk supera GPT-6 Astra e Claude no Cyber primeiro para os benchmarks e o que há por trás da manchete de cyber.

O que você precisa

Passo 1: Obtenha uma chave de API

1. Faça login no Mistral Studio (anteriormente La Plateforme).
2. Abra API Keys e crie uma nova chave. Dê a ela um nome que indique onde ela será usada, como local-dev ou ci-staging.
3. Copie-a uma vez. O Studio não a exibirá novamente.
4. Exporte-a em seu shell:

export MISTRAL_API_KEY="sua-chave-aqui"

Mantenha a chave fora do controle de versão. Se você a estiver conectando a várias ferramentas, nosso guia sobre melhores práticas de gerenciamento de chaves de API abrange rotação e escopo.

Passo 2: Faça sua primeira chamada

A verificação mais rápida é um simples curl:

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 retorna choices[0].message.content com a resposta e um bloco usage com prompt_tokens, completion_tokens e total_tokens. Se você receber um 401, a chave está errada ou não foi exportada. Um 404 no modelo geralmente significa um erro de digitação no ID do modelo.

A mesma chamada em Python

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)

E em TypeScript

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 no Apidog

Digitar comandos curl fica cansativo no momento em que você começa a comparar modelos. No Apidog:

1. Crie uma nova requisição HTTP: POST https://api.mistral.ai/v1/chat/completions.
2. Adicione uma variável de ambiente MISTRAL_API_KEY e defina o cabeçalho Authorization: Bearer {{MISTRAL_API_KEY}}.
3. Cole o corpo JSON do Passo 2 e clique em Send.
4. Duplique a requisição, mude model para o modelo que você usa hoje (por exemplo, mistral-medium-3-5) e execute ambos.

Agora você tem duas requisições salvas com o mesmo prompt. O Apidog mostra o corpo da resposta, status, tempo e tamanho para cada uma, para que você possa comparar a qualidade da resposta, latência e contagens de tokens usage sem escrever um script. Adicione uma asserção pós-resposta de que choices[0].message.content não está vazio e você terá um teste de fumaça que pode ser executado novamente sempre que a Mistral atualizar a prévia.

Passo 4: Ativar e desativar o raciocínio

Large 4 é um modelo híbrido: o mesmo modelo lida com respostas rápidas e raciocínio passo a passo. Você o controla com um parâmetro, reasoning_effort:

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"
  }'

Esta é a parte que quebra os parsers. Com reasoning_effort: "high", message.content não é mais uma string. Torna-se uma lista de chunks:

• um chunk thinking contendo o rastreamento do raciocínio, e
• um chunk text contendo a resposta final.

Então response.choices[0].message.content imprimirá uma lista, não sua resposta. Extraia o chunk de texto explicitamente:

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(c.text for c in content if c.type == "text")

print(answer)

Tokens de raciocínio são cobrados como tokens de saída, então "high" custa mais por requisição. Use "none" por padrão e mude para "high" apenas nas chamadas que precisam.

Passo 5: Enviar uma imagem

Large 4 é nativamente multimodal, com um codificador de visão de 1.6B parâmetros. Passe imagens como partes de conteúdo ao lado do seu texto:

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 em vez disso: "image_url": "data:image/png;base64,<codificado>". A Mistral informa que o Large 4 pontua 42% no benchmark de aterramento visual Dense 200, logo à frente dos 41% do GPT-6 Astra, então capturas de tela de painéis, gráficos e estados de UI são uma opção razoável.

Passo 6: Chamada de função

A chamada de função é onde os benchmarks de agente do Large 4 (59,9% no AutomationBench) se tornam úteis. Você descreve as ferramentas, o modelo decide quando chamá-las, e seu código executa a chamada.

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, tool_call.function.arguments)

Execute a função você mesmo, então envie o resultado de volta com o tool_call_id correspondente:

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 esquema da ferramenta é um JSON Schema puro. Se sua API já tiver uma especificação OpenAPI, você pode usar o esquema de requisição para cada operação diretamente em parameters. Projetar a especificação no Apidog primeiro mantém as definições da ferramenta e a API real sincronizadas.

Passo 7: Obtenha JSON de volta

Quando você precisa de uma saída legível por máquina, defina 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"}
  }'

Mencione JSON no prompt, bem como em response_format. Para formas estritas, a Mistral também suporta {"type": "json_schema", "json_schema": {...}} com um esquema completo. No Apidog, adicione uma asserção de JSON Schema na resposta para que uma forma divergente falhe ruidosamente em vez de quebrar um serviço downstream.

Quanto custa

Um exemplo prático: um agente que faz 10.000 chamadas por dia, cada uma com 3.000 tokens de entrada (principalmente um prompt de sistema em cache e ferramentas) e 500 tokens de saída.

• Entrada: 30M tokens. Se 2.500 de cada 3.000 estiverem em cache, são 25M em cache a $0,07 e 5M novos a $0,68, cerca de $5,15/dia.
• Saída: 5M tokens a $2,09, cerca de $10,45/dia.
• Total: aproximadamente $15,60/dia com preços de prévia, ou cerca de $31 com preços de tabela.

A mesma carga de trabalho no GPT-6 Astra ($10 / $50 por milhão, antes dos descontos de cache) custaria várias centenas de dólares por dia. A Mistral não informou quando os preços de prévia terminam, então orce com base no preço de tabela.

Erros comuns

FAQ

Mistral Large 4 é compatível com OpenAI? A forma da requisição é muito próxima: model, messages, tools, tool_choice e response_format funcionam como você espera. Use os SDKs da Mistral ou HTTP puro para maior segurança. A saída de raciocínio usa o formato de chunk próprio da Mistral.

Quando posso executá-lo localmente? A Mistral diz que os pesos serão lançados até o final de outubro de 2026. Com 1,05T de parâmetros totais, ele precisa de hardware de servidor multi-GPU. Nosso guia executar Mistral 3 localmente aborda as ferramentas para modelos menores enquanto isso.

A prévia é estável o suficiente para produção? Ainda não. O modelo está rotulado como prévia pública e pode mudar antes do lançamento dos pesos. Fixe seus testes, execute-os novamente quando a Mistral atualizar o modelo e mantenha um modelo de fallback configurado.

Posso usar o Large 4 com meu código Mistral existente? Sim. Mesma URL base, mesma autenticação, mesmo SDK. Mude a string model para mistral-large-4. Se você está vindo do Medium 3.5, consulte nosso guia da API Mistral Medium 3.5 para as partes que se mantêm.

Conclusão

Cinco minutos rendem uma chamada funcional. A próxima hora é melhor gasta executando seus prompts reais contra o Large 4 e seu modelo atual lado a lado. Salve ambas as requisições no Apidog, adicione asserções de status e formato de resposta, e você saberá em um dia se o Le Chonk merece um lugar em sua pilha, enquanto o preço de prévia ainda está pela metade.