Como Usar a API Mistral Medium 3.5? Guia Completo

A Mistral lançou o Medium 3.5 em 29 de abril de 2026. O ID do modelo da API é mistral-medium-3.5, o endpoint é https://api.mistral.ai/v1/chat/completions, e o formato da requisição é suficientemente próximo ao padrão da OpenAI, de modo que a troca de URLs base de outro provedor leva apenas uma linha de código. Os números de destaque são uma janela de contexto de 256K, visão nativa, chamada de função, suporte a 24 idiomas e 77,6% no SWE-Bench Verified; números que o colocam na mesma categoria de discussão que o GPT-5.5 e o DeepSeek V4 para o tipo de trabalho com agente e intensivo em código que a maioria das equipes está configurando atualmente.

Este guia aborda autenticação, todos os parâmetros importantes, exemplos em Python e Node, entrada de visão, chamada de ferramenta, modo JSON, streaming, tratamento de erros e um fluxo de trabalho Apidog que mantém o custo visível enquanto você itera nos prompts. Para guias de modelos comparáveis, consulte como usar a API DeepSeek V4 e como usar a API GPT-5.5.

TL;DR

• Endpoint: POST https://api.mistral.ai/v1/chat/completions. A autenticação é um token de portador (bearer token) no cabeçalho `Authorization` padrão.
• ID do modelo: mistral-medium-3.5. Janela de contexto: 256K tokens. Preços: $1,5 por milhão de tokens de entrada, $7,5 por milhão de tokens de saída.
• Modelo denso de 128B mesclado com raciocínio, visão, chamada de função nativa, saída JSON estruturada e cobertura de 24 idiomas.
• Pesos abertos disponíveis no Hugging Face como mistralai/Mistral-Medium-3.5-128B sob uma Licença MIT Modificada com uma exceção para grandes receitas.
• SWE-Bench Verified: 77,6%. τ³-Telecom: 91,4. Forte em codificação, seguimento de instruções e uso de ferramentas.
• Baixe o Apidog para comparar (A/B testing) o Medium 3.5 com seu modelo atual, armazene a chave como uma variável secreta e observe a diferença de custo por chamada.

O que mudou no Medium 3.5

O Medium 3 foi lançado no início do ano como um modelo apenas de texto com um contexto de 128K. O Medium 3.5 é uma fera diferente. É o primeiro modelo mesclado carro-chefe da Mistral: seguimento de instruções, raciocínio e codificação vivem em um único conjunto de pesos, então você não precisa mais escolher entre um checkpoint de chat e um de raciocínio. A visão é nativa, o contexto dobra para 256K, e a chamada de função é integrada no nível do modelo em vez de adicionada por meio de uma superfície de API separada.

Três números sustentam a atualização. O SWE-Bench Verified em 77,6% se enquadra na mesma faixa dos principais modelos de fronteira para correção de código. O τ³-Telecom em 91,4 o coloca à frente da maioria dos modelos generalistas em diálogos agenticos de múltiplas turnos. O contexto de 256K cobre uma base de código de tamanho médio completa ou uma transcrição de várias horas sem truncamento. Nenhum desses são erros de arredondamento de marketing; eles mapeiam diretamente para se o modelo pode concluir sua tarefa sem uma segunda passagem.

A mudança de preços é a parte a ser orçada. O Medium 3 custava $0,40 por milhão de tokens de entrada e $2,00 por milhão de saída. O Medium 3.5 salta para $1,5 de entrada e $7,5 de saída, aproximadamente 4x. Esse é o custo da abordagem de checkpoint mesclado, mais a visão e o contexto mais longo. Trate o Medium 3 mais antigo como a opção de alto rendimento e o Medium 3.5 como o nível 'Preciso dessa resposta agora'.

Pré-requisitos

Antes da primeira chamada, prepare quatro coisas.

• Uma conta Mistral em console.mistral.ai com um método de pagamento arquivado. Sem saldo, as chamadas retornam 402 Payment Required.
• Uma chave de API com escopo para o projeto que você faturará. As chaves de projeto são mais seguras do que as chaves de conta para qualquer coisa que vá para produção.
• Um SDK. A Mistral publica um pacote oficial `mistralai` para Python e JavaScript, e o SDK da OpenAI funciona com o mesmo endpoint com uma troca de URL base.
• Um cliente de API que pode repetir requisições sem lotar seu histórico de terminal. O curl funciona para a primeira chamada. Depois disso, use o Apidog para manter a chave fora do seu histórico de shell e os corpos das requisições sob controle de versão.

Exporte a chave uma vez:

export MISTRAL_API_KEY="..."

Endpoint e autenticação

A plataforma La Plateforme da Mistral expõe tudo através de uma única URL base.

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

A autenticação é um token de portador (bearer token) no cabeçalho `Authorization`. A requisição mínima viável se parece com isto:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium-3.5",
    "messages": [
      {"role": "user", "content": "Explain dense merged checkpoints in two sentences."}
    ]
  }'

Uma resposta bem-sucedida retorna um corpo JSON com um array `choices`, um bloco `usage` detalhado em `prompt_tokens`, `completion_tokens` e `total_tokens`, e um `id` que você pode usar para rastreamento. Falhas retornam um envelope de `error` com `code` e `message`. O formato corresponde ao envelope da OpenAI de forma suficientemente próxima para que qualquer analisador de erros que você já possua funcione sem modificações.

Parâmetros da requisição

Cada campo mapeia para custo ou comportamento. Aqui está o mapa para mistral-medium-3.5.

Duas pequenas diferenças confundem as pessoas ao migrar da OpenAI: tool_choice="any" significa “forçar uma chamada de ferramenta” (a OpenAI usa `required`), e o parâmetro de seed é `random_seed` (a OpenAI usa `seed`). Todo o resto se alinha.

Cliente Python

A Mistral distribui um SDK Python oficial que corresponde à API um-a-um.

import os
from mistralai import Mistral

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

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    temperature=0.3,
    max_tokens=2048,
)

print("Conteúdo:", response.choices[0].message.content)
print("Total de tokens:", response.usage.total_tokens)
print("Estimativa de custo (USD):",
      response.usage.prompt_tokens * 1.5 / 1_000_000 +
      response.usage.completion_tokens * 7.5 / 1_000_000)

Se você já possui uma base de código no formato OpenAI, o SDK Python da OpenAI funciona com o endpoint da Mistral com duas alterações: a URL base e o ID do modelo.

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MISTRAL_API_KEY"],
    base_url="https://api.mistral.ai/v1",
)

response = client.chat.completions.create(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Hello, Mistral."}],
)

A rota do SDK da OpenAI é o caminho de menor resistência para equipes que executam código agnóstico de provedor; o SDK nativo `mistralai` é o caminho que expõe os recursos específicos da Mistral de forma limpa, então escolha com base em se você planeja usar intensamente a visão e as saídas estruturadas.

Cliente Node

Mesma escolha de duas vias no Node. O SDK nativo:

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

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

const response = await client.chat.complete({
  model: "mistral-medium-3.5",
  messages: [
    { role: "user", content: "Explain dense merged checkpoints in plain English." },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log("Uso:", response.usage);

A rota do SDK da OpenAI, para paridade com o código existente:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MISTRAL_API_KEY,
  baseURL: "https://api.mistral.ai/v1",
});

const response = await client.chat.completions.create({
  model: "mistral-medium-3.5",
  messages: [{ role: "user", content: "Hello, Mistral." }],
});

Streaming de respostas

Defina `stream: true` e itere os chunks SSE. O formato corresponde exatamente ao da OpenAI, e o trace de raciocínio cumulativo é intercalado em `choices[].delta.content` em vez de ser separado em um campo auxiliar.

stream = client.chat.stream(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Stream a 300-word essay on merged checkpoints."}],
)

for chunk in stream:
    delta = chunk.data.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Para saída no terminal, o ritmo do stream da Mistral é mais rápido que o do DeepSeek V4-Pro no mesmo comprimento de prompt e aproximadamente igual ao do GPT-5.5, com base em execuções lado a lado através do visualizador de respostas do Apidog.

Chamada de ferramenta

O Medium 3.5 vem com chamada de função nativa. As funções definidas no array `tools` tornam-se chamáveis, e o modelo decide quando invocá-las.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Return the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Weather in Lagos in Celsius?"}],
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

A partir daí, execute a função localmente, anexe o resultado como uma mensagem `role: "tool"` e chame a API novamente para continuar o loop. O padrão é idêntico ao loop de uso de ferramenta da OpenAI. A capacidade de agente é demonstrada na pontuação τ³-Telecom; na prática, isso se traduz em menos saltos desperdiçados em fluxos de trabalho de várias turnos, onde o modelo precisa decidir entre chamar uma ferramenta, perguntar ao usuário e responder diretamente.

Modo JSON e saída estruturada

Para saída validada por esquema, passe um esquema JSON em `response_format`.

schema = {
    "type": "json_schema",
    "json_schema": {
        "name": "release_note",
        "schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "date": {"type": "string"},
                "bullets": {"type": "array", "items": {"type": "string"}},
            },
            "required": ["title", "date", "bullets"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Reply with a single JSON object matching the schema."},
        {"role": "user", "content": "Summarize today's Mistral Medium 3.5 release."},
    ],
    response_format=schema,
)

O modo estrito impõe o esquema no momento da decodificação, então você não precisa adicionar uma etapa de parsing Pydantic ou Zod no cliente; a resposta ou corresponde ao esquema ou a chamada falha com um erro estruturado. Para casos de menor atrito, onde você precisa apenas de JSON válido de qualquer forma, defina `response_format={"type": "json_object"}` e valide no lado do cliente.

Entrada de visão

O codificador de visão do Medium 3.5 foi treinado do zero para lidar com tamanhos de imagem e proporções variáveis; você não precisa pré-redimensionar nada. Passe o conteúdo da imagem junto com o texto no array `messages`.

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What is in this image and what is it doing wrong?"},
            {"type": "image_url", "image_url": "https://example.com/diagram.png"},
        ],
    }],
)

As entradas de imagem são cobradas como tokens de entrada à mesma taxa de $1,5 por milhão; a contagem exata de tokens por imagem varia com a resolução e é relatada no campo `usage.prompt_tokens`. Para cargas de trabalho de imagem de alto volume, registre o custo do token por imagem antecipadamente e decida se deve compactar, cortar ou pular quadros antes de escalar.

Construa a coleção no Apidog

Repetir requisições do terminal gasta créditos e oculta a diferença entre as execuções. O fluxo de trabalho que sobrevive ao uso real:

1. Baixe o Apidog e crie um projeto.
2. Adicione um ambiente com `{{MISTRAL_API_KEY}}` armazenado como uma variável secreta para que nunca apareça em exportações compartilhadas.
3. Salve uma requisição POST para `{{BASE_URL}}/chat/completions` com o cabeçalho `Authorization: Bearer {{MISTRAL_API_KEY}}`.
4. Parametrize `model`, `temperature` e `tool_choice` para que você possa fazer testes A/B entre variantes sem duplicar requisições.
5. Use o visualizador de respostas para inspecionar `usage` em cada execução. Adicione um pequeno script pós-resposta que multiplica `prompt_tokens * 1.5 / 1_000_000 + completion_tokens * 7.5 / 1_000_000` para que o custo por chamada apareça ao lado de cada resultado.

Equipes que já executam a coleção da API DeepSeek V4 correspondente no Apidog podem duplicá-la, trocar a URL base para `https://api.mistral.ai/v1`, mudar o ID do modelo para `mistral-medium-3.5` e executar prompts comparativos entre ambos os provedores em minutos. O mesmo padrão se aplica para comparar com o GPT-5.5.

Tratamento de erros

O envelope de erro segue de perto as convenções da OpenAI. Os códigos que você encontrará primeiro:

Envolva as chamadas em um auxiliar de retry que lida com 429 e 5xx com backoff exponencial. Não tente novamente erros 4xx automaticamente; esses são bugs de lógica, não falhas transitórias. O visualizador de respostas do Apidog torna trivial identificar um payload `tools` malformado porque o campo ofensivo é destacado no corpo da requisição ao lado do erro.

Padrões de controle de custo

O salto de preço de 4x do Medium 3 para o Medium 3.5 penaliza o roteamento preguiçoso. Cinco padrões mantêm a conta previsível.

1. Use o Medium 3 por padrão, escale para o Medium 3.5. Faça uma primeira passagem barata no Medium 3 e direcione prompts difíceis para o 3.5 apenas quando a passagem barata retornar baixa confiança ou falhar em um validador.
2. Limite max_tokens. A maioria das respostas se encaixa em 2.000 tokens de saída. A janela de contexto de 256K é para entrada em massa, não para saída em massa; a saída é o lado caro a $7,5 por milhão.
3. Mantenha os prompts do sistema enxutos. Cada token de prompt do sistema é cobrado em cada chamada; reduzir um preâmbulo de 2K tokens para 500 tokens corta sua conta de entrada em 75% em um endpoint de alto volume.
4. Registre usage em cada chamada. Envie `prompt_tokens`, `completion_tokens` e a estimativa de USD por chamada para sua pilha de observabilidade. Um alerta sobre um pico repentino de tokens de saída detecta prompts que se desviaram para o território da cadeia de pensamento.
5. Use a visão seletivamente. Tokens de imagem se acumulam rapidamente. Corte para a região relevante antes de enviar e reduza a escala para a menor resolução que ainda responda à pergunta.

Comparando o Medium 3.5 com outros níveis da Mistral

A linha de modelos da Mistral a partir do final de abril de 2026:

O Medium 3.5 é o único nível que combina o contexto longo, visão e capacidades de raciocínio mescladas. O nível Large oferece uma curva de custo diferente (saída mais barata, entrada mais cara) e supera o 3.5 em alguns benchmarks apenas de texto; escolha pelo tipo de trabalho, não pelo nome do nível.

Migrando de outro provedor

A migração é principalmente uma mudança de URL base.

Da OpenAI:

- base_url="https://api.openai.com/v1"
- model="gpt-5.5"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Da DeepSeek:

- base_url="https://api.deepseek.com/v1"
- model="deepseek-v4-pro"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Duas pegadinhas para observar:

• `tool_choice="required"` na OpenAI torna-se `tool_choice="any"` na Mistral.
• `seed` torna-se `random_seed`.

Execute a diferença através de sua suíte de testes existente antes de mudar o tráfego de produção. Melhor ainda, espelhe o tráfego para a Mistral em modo sombra por um dia, registre ambas as respostas e compare-as no Apidog antes de promover.

Casos de uso no mundo real

Alguns padrões onde o Medium 3.5 já se paga:

• Assistentes de revisão de código. A pontuação de 77,6% no SWE-Bench Verified e o contexto de 256K o tornam forte em revisões de nível de PR, onde o modelo precisa ver a diferença completa mais os arquivos circundantes.
• QA de documentos em PDFs longos. O contexto de 256K cobre a maioria dos contratos, RFPs e documentos de política em uma única chamada sem a necessidade de fragmentação.
• Extração de dados multimodais. Extrair campos estruturados de recibos, capturas de tela ou diagramas em uma única chamada é mais eficiente do que executar OCR mais um modelo de texto separado.
• Loops de agente com chamadas de ferramenta. A chamada de função nativa e a alta pontuação τ³-Telecom reduzem o número de ciclos de 'chamada de ferramenta falhou, tente novamente com JSON corrigido' que consomem tokens.

FAQ

Qual é o ID do modelo para Mistral Medium 3.5 na API?mistral-medium-3.5. O checkpoint do Hugging Face é publicado como mistralai/Mistral-Medium-3.5-128B. Se você hospedar os pesos abertos por conta própria com vLLM ou Unsloth, use o ID do Hugging Face. Para a API hospedada, use o ID curto.

O Medium 3.5 é compatível com OpenAI?Próximo, mas não idêntico. O formato do endpoint, cabeçalhos e a maioria dos parâmetros correspondem exatamente aos da OpenAI, então os SDKs Python e Node da OpenAI funcionam com uma sobrescrita da URL base. As duas divergências são `tool_choice="any"` (contra o `required` da OpenAI) e `random_seed` (contra o `seed` da OpenAI).

Posso executar o Medium 3.5 localmente?Sim. Os pesos são abertos sob uma Licença MIT Modificada com uma exceção para grandes receitas. A contagem de 128B parâmetros significa que você precisa de uma memória GPU significativa; builds GGUF quantizados de `unsloth/Mistral-Medium-3.5-128B-GGUF` são executados em uma única placa de consumidor de ponta. Os padrões de como executar o DeepSeek V4 localmente são diretamente aplicáveis.

Ele suporta streaming com chamadas de ferramenta?Sim. O streaming retorna fragmentos de argumentos de chamada de ferramenta incrementalmente em `delta.tool_calls`, o mesmo formato que o formato de chamada de ferramenta em streaming da OpenAI. Os fragmentos se acumulam em um objeto JSON completo assim que o stream é fechado.

Como faço para contar os tokens de entrada antes de enviar?Use o tokenizador do pacote Python `mistral-common` para contagens exatas. É o mesmo tokenizador usado pela API, então as contagens byte a byte correspondem a `usage.prompt_tokens` na resposta.

Que comprimento de contexto devo planejar para produção?A janela de 256K é o limite, mas os preços escalam linearmente. Uma chamada de 200K tokens custa $0,30 apenas em entrada antes mesmo de o modelo começar a gerar. A maioria das cargas de trabalho de produção se encaixa confortavelmente abaixo de 32K; utilize o contexto longo apenas quando a tarefa realmente exigir.

Existe um nível gratuito?A Mistral não anuncia um nível gratuito permanente, mas novas contas geralmente vêm com um pequeno crédito de teste. Para experimentação gratuita contínua em modelos de nível similar, consulte como usar a API DeepSeek V4 gratuitamente.