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 é próximo ao padrão da OpenAI. Na prática, migrar de outro provedor costuma exigir apenas trocar a URL base e o ID do modelo. Os destaques: contexto de 256K, visão nativa, chamada de função, suporte a 24 idiomas e 77,6% no SWE-Bench Verified.

Experimente o Apidog hoje

Este guia mostra como autenticar, configurar parâmetros, chamar a API em Python e Node, usar visão, ferramentas, modo JSON, streaming, tratamento de erros e um fluxo de trabalho com Apidog para acompanhar custo por chamada enquanto você itera nos prompts. Para modelos comparáveis, veja 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.
• Autenticação: bearer token no cabeçalho Authorization.
• Modelo: mistral-medium-3.5.
• Contexto: 256K tokens.
• Preço: US$ 1,5 por milhão de tokens de entrada e US$ 7,5 por milhão de tokens de saída.
• Recursos: visão nativa, chamada de função, saída JSON estruturada, raciocínio e suporte a 24 idiomas.
• Pesos abertos: mistralai/Mistral-Medium-3.5-128B no Hugging Face sob Licença MIT Modificada com exceção para grandes receitas.
• Benchmarks citados: 77,6% no SWE-Bench Verified e 91,4 no τ³-Telecom.
• Use o Apidog para salvar requisições, proteger a chave como variável secreta e comparar custo entre execuções.

O que mudou no Medium 3.5

O Medium 3 foi lançado como um modelo apenas de texto com contexto de 128K. O Medium 3.5 muda o perfil: ele combina seguimento de instruções, raciocínio e codificação em um único conjunto de pesos. Você não precisa alternar entre um checkpoint de chat e outro de raciocínio.

Principais mudanças:

• Contexto ampliado de 128K para 256K.
• Visão nativa.
• Chamada de função integrada.
• Melhor desempenho em tarefas de código e agentes.
• Preço mais alto que o Medium 3.

Os números mais relevantes para implementação são:

• 77,6% no SWE-Bench Verified: útil para revisão e correção de código.
• 91,4 no τ³-Telecom: indica bom comportamento em fluxos agenticos de múltiplos turnos.
• 256K de contexto: permite enviar uma base de código média, documentos longos ou transcrições grandes em uma única chamada.

O preço também muda. O Medium 3 custava US$ 0,40/M tokens de entrada e US$ 2,00/M tokens de saída. O Medium 3.5 sobe para US$ 1,5/M entrada e US$ 7,5/M saída. Use o Medium 3.5 quando a tarefa justificar raciocínio, visão, ferramentas ou contexto longo.

Pré-requisitos

Antes de chamar a API, prepare:

1. Uma conta em console.mistral.ai com método de pagamento. Sem saldo, a API pode retornar 402 Payment Required.
2. Uma chave de API com escopo para o projeto correto.
3. Um SDK:
   • mistralai para Python ou JavaScript.
   • SDK da OpenAI, se você quiser reaproveitar código com base_url.
4. Um cliente de API para repetir e versionar requisições. O curl serve para o primeiro teste; para iteração, use o Apidog.

Exporte a chave:

export MISTRAL_API_KEY="..."

Endpoint e autenticação

A URL base da API é:

https://api.mistral.ai/v1

O endpoint de chat completions:

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

Requisição mínima com curl:

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:

• choices: lista de respostas.
• usage.prompt_tokens: tokens de entrada.
• usage.completion_tokens: tokens de saída.
• usage.total_tokens: total.
• id: identificador para rastreamento.

Erros retornam um envelope error com code e message, semelhante ao formato da OpenAI.

Parâmetros principais

Parâmetro	Tipo	Valores	Observações
model	string	mistral-medium-3.5	Obrigatório.
messages	array	pares role / content	Obrigatório. Mesmo padrão da OpenAI.
temperature	float	0 a 1.5	A Mistral recomenda 0.7 para uso geral e 0.3 para código.
top_p	float	0 a 1	Padrão 1.0.
max_tokens	int	1 até o limite de contexto	Limita a saída.
stream	bool	true ou false	Habilita streaming SSE.
tools	array	especificação de ferramenta estilo OpenAI	Chamada de função nativa.
tool_choice	string/object	auto, any, none ou ferramenta específica	Use any para forçar ferramenta.
response_format	object	{"type":"json_object"} ou schema JSON	Saída estruturada.
random_seed	int	qualquer inteiro	Para reprodutibilidade.
safe_prompt	bool	true ou false	Adiciona o preâmbulo de segurança da Mistral.
presence_penalty	float	-2 a 2	Penaliza tópicos repetidos.
frequency_penalty	float	-2 a 2	Penaliza tokens repetidos.

Duas diferenças importantes ao migrar da OpenAI:

• OpenAI: tool_choice="required" Mistral: tool_choice="any"
• OpenAI: seed Mistral: random_seed

Cliente Python

Instale o SDK oficial:

pip install mistralai

Chamada básica:

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)

estimated_cost = (
    response.usage.prompt_tokens * 1.5 / 1_000_000
    + response.usage.completion_tokens * 7.5 / 1_000_000
)

print("Estimativa de custo (USD):", estimated_cost)

Se sua aplicação já usa o SDK da OpenAI, altere apenas base_url e model:

import os
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."}
    ],
)

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

Use o SDK mistralai quando quiser suporte mais direto a recursos específicos da Mistral. Use o SDK da OpenAI quando a prioridade for compatibilidade com código existente.

Cliente Node.js

Instale o SDK oficial:

npm install @mistralai/mistralai

Exemplo com 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);

Exemplo com SDK da OpenAI:

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.",
    },
  ],
});

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

Streaming de respostas

Para streaming, defina stream: true ou use o método de stream do SDK.

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)

O formato segue o padrão SSE. O conteúdo incremental aparece em choices[].delta.content.

Para depurar streaming e comparar execuções lado a lado, use o visualizador de respostas do Apidog.

Chamada de ferramenta

O Medium 3.5 suporta chamada de função nativa via tools.

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

Fluxo típico:

1. Envie messages + tools.
2. Leia message.tool_calls.
3. Execute a função localmente.
4. Adicione o resultado como mensagem role: "tool".
5. Chame a API novamente para gerar a resposta final.

Exemplo conceitual:

messages = [
    {"role": "user", "content": "Weather in Lagos in Celsius?"}
]

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

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

# Execute sua função real aqui
tool_result = {
    "city": "Lagos",
    "temperature": 29,
    "unit": "c",
}

messages.append(response.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps(tool_result),
})

final_response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=messages,
    tools=tools,
)

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

Modo JSON e saída estruturada

Para forçar JSON válido, use:

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

Para validar por schema:

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,
)

Use schema estrito quando o resultado alimentar outro sistema. Use json_object quando você só precisa garantir JSON válido e fará a validação no cliente.

Entrada de visão

O Medium 3.5 aceita imagem e texto no mesmo message.content.

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",
                },
            ],
        }
    ],
)

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

As imagens são cobradas como tokens de entrada. A contagem depende da resolução e aparece em usage.prompt_tokens.

Para controlar custo:

• Corte a região relevante antes de enviar.
• Reduza a resolução quando possível.
• Evite enviar frames redundantes em fluxos de vídeo.
• Registre tokens por imagem antes de escalar.

Crie uma coleção no Apidog

Um fluxo prático para desenvolvimento:

1. Baixe o Apidog e crie um projeto.
2. Crie um ambiente com:
   • BASE_URL=https://api.mistral.ai/v1
   • MISTRAL_API_KEY como variável secreta.
3. Salve uma requisição:
   • Método: POST
   • URL: {{BASE_URL}}/chat/completions
   • Header: Authorization: Bearer {{MISTRAL_API_KEY}}
   • Header: Content-Type: application/json
4. Parametrize model, temperature, max_tokens e tool_choice.
5. Inspecione usage em cada resposta.
6. Adicione um cálculo de custo por chamada:

const usage = response.body.usage;

const cost =
  usage.prompt_tokens * 1.5 / 1_000_000 +
  usage.completion_tokens * 7.5 / 1_000_000;

console.log(`Estimated cost: $${cost.toFixed(6)}`);

Se você já tem uma coleção da API DeepSeek V4, duplique a coleção, troque a URL base para https://api.mistral.ai/v1 e altere o modelo para mistral-medium-3.5. O mesmo padrão vale para comparar com o GPT-5.5.

Tratamento de erros

Códigos comuns:

Código	Significado	Como resolver
400	Requisição inválida	Valide messages, tools e JSON.
401	Chave inválida	Regenere a chave em console.mistral.ai.
402	Pagamento necessário	Adicione saldo ou método de pagamento.
403	Modelo não permitido	Verifique escopo da chave e grafia do modelo.
422	Parâmetro fora do intervalo	Revise max_tokens, tool_choice e schema.
429	Rate limit	Use retry com backoff exponencial e jitter.
500	Erro do servidor	Tente novamente uma vez.
503	Sobrecarga	Espere ou faça fallback para outro modelo.

Exemplo simples de retry em Python:

import time
import random

def call_with_retry(fn, max_attempts=4):
    for attempt in range(max_attempts):
        try:
            return fn()
        except Exception as exc:
            status = getattr(exc, "status_code", None)

            if status not in [429, 500, 502, 503, 504]:
                raise

            if attempt == max_attempts - 1:
                raise

            sleep = (2 ** attempt) + random.random()
            time.sleep(sleep)

Não tente novamente erros 4xx automaticamente, exceto 429. Em geral, eles indicam bug de payload ou configuração.

Controle de custo

O Medium 3.5 é mais caro que o Medium 3. Use roteamento e limites desde o início.

1. Use Medium 3 como padrão e escale para 3.5

Faça a primeira passagem com um modelo mais barato. Envie para o Medium 3.5 apenas quando:

• o validador falhar;
• a confiança for baixa;
• houver necessidade de visão;
• o contexto exceder o limite do modelo menor;
• a tarefa envolver ferramentas ou raciocínio mais complexo.

2. Defina max_tokens

A saída é o lado mais caro. Evite deixar a geração sem limite.

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=messages,
    max_tokens=1200,
)

3. Reduza prompts de sistema

Prompts de sistema longos são cobrados em todas as chamadas. Se um preâmbulo de 2K tokens pode virar 500 tokens, você reduz custo de entrada em 75% naquele trecho.

4. Registre usage

Envie para sua observabilidade:

• prompt_tokens
• completion_tokens
• total_tokens
• custo estimado
• modelo usado
• endpoint
• latência

5. Use visão seletivamente

Não envie imagens inteiras quando um recorte resolve. Não envie múltiplos frames quando um único frame responde à pergunta.

Comparando o Medium 3.5 com outros níveis da Mistral

Linha citada para o final de abril de 2026:

Modelo	Contexto	Entrada $/M	Saída $/M	Visão	Melhor para
mistral-small	32K	US$ 0.10	US$ 0.30	Não	Classificação de alto volume e chat leve
mistral-medium-3	128K	US$ 0.40	US$ 2.00	Não	Alto rendimento e chat longo
mistral-medium-3.5	256K	US$ 1.5	US$ 7.5	Sim	Raciocínio, código, visão e agentes
mistral-large	128K	US$ 2.00	US$ 6.00	Limitado	Raciocínio de texto de nível de fronteira

O Medium 3.5 é o nível que combina contexto longo, visão e capacidades mescladas de raciocínio. Escolha pelo tipo de trabalho, não apenas pelo nome do modelo.

Migrando de outro provedor

A migração costuma ser uma troca de URL base e modelo.

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"

Ajustes obrigatórios:

- tool_choice="required"
+ tool_choice="any"

- seed=123
+ random_seed=123

Antes de mudar produção:

1. Rode sua suíte de testes.
2. Compare respostas para prompts críticos.
3. Espelhe tráfego em modo sombra por um dia.
4. Registre as duas respostas.
5. Compare latência, custo e taxa de falha no Apidog.

Casos de uso práticos

Revisão de código

O contexto de 256K permite enviar diffs grandes com arquivos relacionados. A pontuação de 77,6% no SWE-Bench Verified torna o modelo relevante para fluxos de PR review e correção de bugs.

QA em documentos longos

Contratos, RFPs, políticas internas e documentos técnicos podem caber em uma única chamada, reduzindo a necessidade de chunking.

Extração multimodal

Você pode extrair campos estruturados de recibos, screenshots ou diagramas usando visão + JSON estruturado na mesma chamada.

Agentes com ferramentas

A chamada de função nativa ajuda em fluxos onde o modelo precisa decidir entre:

• chamar uma ferramenta;
• pedir mais informação;
• responder diretamente;
• continuar um loop de execução.

FAQ

Qual é o ID do modelo na API?

Use:

mistral-medium-3.5

O checkpoint no Hugging Face é:

mistralai/Mistral-Medium-3.5-128B

Para a API hospedada, use o ID curto. Para self-hosting, use o ID do Hugging Face.

O Medium 3.5 é compatível com OpenAI?

É próximo, mas não idêntico. O endpoint, cabeçalhos e a maioria dos parâmetros seguem o padrão da OpenAI. Os SDKs Python e Node da OpenAI funcionam com override de URL base.

Diferenças principais:

• tool_choice="any" em vez de required.
• random_seed em vez de seed.

Posso executar o Medium 3.5 localmente?

Sim. Os pesos são abertos sob uma Licença MIT Modificada com exceção para grandes receitas. O modelo tem 128B parâmetros, então exige memória GPU significativa. Builds GGUF quantizados de unsloth/Mistral-Medium-3.5-128B-GGUF podem rodar em uma placa de consumidor de ponta. Os padrões de como executar o DeepSeek V4 localmente são aplicáveis.

Ele suporta streaming com chamadas de ferramenta?

Sim. O streaming retorna fragmentos de argumentos de ferramenta em delta.tool_calls, no mesmo estilo do streaming de tool calls da OpenAI. Os fragmentos formam um JSON completo ao final do stream.

Como contar tokens antes de enviar?

Use o tokenizador do pacote Python mistral-common. Ele usa o mesmo tokenizador da API, então as contagens devem corresponder a usage.prompt_tokens.

Qual contexto devo planejar para produção?

O limite é 256K, mas o custo escala linearmente. Uma chamada com 200K tokens de entrada custa US$ 0,30 antes da geração. Para a maioria dos workloads, tente ficar abaixo de 32K e use contexto longo apenas quando necessário.

Existe nível gratuito?

A Mistral não anuncia um nível gratuito permanente, mas novas contas geralmente recebem um pequeno crédito de teste. Para experimentação gratuita em modelos similares, veja como usar a API DeepSeek V4 gratuitamente.