Ir para o conteúdo principal
Português— Escolher um idioma
Menu

O Endpoint /v1/chat/completions

Aula 1 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. A Sua Porta de Entrada para os Modelos Mistral
  2. O URL Base
  3. Anatomia de um Pedido
  4. Equivalente em Python com o SDK
  5. Estrutura da Resposta
  6. Códigos de Erro Comuns
  7. Pontos-chave

Atualização de 2 de novembro de 2026 — Modelos. O Mistral Large 3 (mistral-large-2512) e o Mistral Medium 3.5 foram descontinuados a 31 de outubro de 2026 e serão retirados de serviço a 30 de abril de 2027. O seu sucessor designado, Mistral Large 4 (mistral-large-4), está em pré-visualização pública desde 6 de outubro. Os exemplos neste curso utilizam o alias mistral-large-latest, que aponta atualmente para o Mistral Large 3 de acordo com a sua especificação oficial (verificado a 3 de novembro de 2026). Da mesma forma, mistral-medium-latest aponta para o Mistral Medium 3.5. Estes aliases permanecerão válidos até 30 de abril de 2027. Para novos projetos, teste o mistral-large-4, o seu sucessor designado.

A Sua Porta de Entrada para os Modelos Mistral

Tudo o que fizer com a API Mistral passa por um único caminho: /v1/chat/completions. Este é o hub central da plataforma, gerindo todas as suas interações conversacionais com modelos de linguagem. Quer esteja a construir um chatbot de suporte interno, um extrator que converte faturas em PDF em linhas de base de dados, ou um assistente de escrita integrado no seu CMS, estas três aplicações aparentemente distintas chamam exatamente o mesmo endpoint com mensagens e parâmetros diferentes. Não precisa de aprender três integrações separadas; apenas precisa de dominar uma.

A partir de abril de 2026, este endpoint processa milhares de milhões de pedidos diariamente em todo o mundo. Compreender a sua estrutura é o primeiro passo para aproveitar os modelos Mistral em produção.

1 endpoint
Para todas as conversas
POST
Método HTTP único
< 500 ms
Latência do primeiro token (streaming)
JSON
Formato de entrada/saída

O URL Base

Todos os pedidos à API Mistral partem da mesma base:

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

Envia um pedido POST com um corpo JSON contendo as suas mensagens e parâmetros, e a API devolve uma resposta JSON estruturada. Não há sessões para abrir nem estado do lado do servidor para manter: cada chamada é autónoma.

Anatomia de um Pedido

A forma mais rápida de verificar se a sua chave funciona é enviar um pedido mínimo utilizando curl diretamente no seu terminal:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "model": "mistral-large-latest",
    "messages": [
      {"role": "user", "content": "Hello, how does your API work?"}
    ]
  }'

Dois cabeçalhos são obrigatórios: Content-Type: application/json descreve o formato do corpo do pedido, e Authorization: Bearer <sua-chave> transporta a sua autenticação. O corpo em si deve conter pelo menos dois campos: model, o identificador do modelo a utilizar, e messages, o vetor que transporta a conversa.

Equivalente em Python com o SDK

Assim que ultrapassar a fase de testes, ninguém escreve comandos curl brutos em produção. O SDK oficial faz a mesma chamada em apenas algumas linhas:

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "Hello, how does your API work?"}
    ]
)

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

O SDK trata dos cabeçalhos, da serialização JSON e da análise da resposta por si. Também gere novas tentativas automáticas para erros temporários, poupando-o de escrever a sua própria lógica de repetição quando um pico de tráfego causa uma falha transitória.

Estrutura da Resposta

Independentemente de como chamar a API, ela devolve sempre o mesmo objeto JSON:

{
  "id": "cmpl-abc123",
  "object": "chat.completion",
  "created": 1712150400,
  "model": "mistral-large-latest",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! The Mistral API works..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 87,
    "total_tokens": 102
  }
}

Três campos merecem a sua atenção imediata. choices é um vetor contendo a(s) resposta(s) gerada(s); é aqui que encontra o texto a apresentar ao utilizador. usage fornece a contagem de tokens para entrada, saída e o total, permitindo-lhe acompanhar o custo real de cada funcionalidade em vez de descobrir a fatura no final do mês. Por fim, finish_reason explica porque é que o modelo parou: stop para um fim natural, length quando o limite de tokens cortou a resposta, ou tool_calls quando o modelo solicita a execução de ferramentas. Um resumo que termina a meio de uma frase quase nunca é um problema do modelo; é um finish_reason de length que ninguém leu.

Códigos de Erro Comuns

Quando algo corre mal, a API devolve códigos HTTP padrão:

  • 400 — Pedido mal formado (JSON inválido, parâmetro em falta)
  • 401 — Chave de API inválida ou em falta
  • 429 — Limite de taxa atingido (demasiados pedidos)
  • 500 — Erro do servidor (tente novamente após alguns segundos)

Em Python, o SDK lança exceções tipadas que pode capturar, permitindo-lhe distinguir entre uma chave expirada e uma saturação temporária, reagindo de forma diferente em cada caso:

from mistralai.client import Mistral
from mistralai.client.errors import SDKError

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

try:
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": "Test"}]
    )
except SDKError as e:
    print(f"API Error: {e.status_code} — {e.message}")

Crie o hábito de envolver cada chamada neste bloco desde o seu primeiro script. No dia em que a sua aplicação correr sem supervisão, ela dir-lhe-á o que falhou em vez de parar silenciosamente.

Pontos-chave

  • O endpoint /v1/chat/completions é o único necessário para interações conversacionais
  • Cada pedido requer um model e um vetor messages
  • A resposta contém sempre choices, usage e finish_reason
  • O SDK Python simplifica significativamente as chamadas em comparação com curl
  • Os tokens de utilização permitem-lhe calcular os seus custos com precisão