DEV Community

Cover image for Mistral Medium 3.5 API Nasıl Kullanılır?
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Mistral Medium 3.5 API Nasıl Kullanılır?

Mistral, Medium 3.5'i 29 Nisan 2026'da yayınladı. API model kimliği mistral-medium-3.5, uç nokta https://api.mistral.ai/v1/chat/completions ve istek şeması OpenAI standardına yakındır; çoğu entegrasyonda sağlayıcı değiştirmek temel URL ve model ID güncellemesiyle yapılır. Model; 256K bağlam penceresi, yerel görsel girdi, işlev çağırma, 24 dil desteği ve SWE-Bench Verified'da %77,6 başarı oranıyla kod, ajan ve uzun bağlam iş yükleri için konumlanır.

Apidog'u bugün deneyin

Bu kılavuzda kimlik doğrulama, temel parametreler, Python ve Node örnekleri, görsel girdi, araç çağırma, JSON modu, akış, hata yönetimi ve istemleri denerken maliyeti görünür tutan bir Apidog iş akışı yer alır. Karşılaştırmalı model rehberleri için DeepSeek V4 API'sini nasıl kullanacağınızı ve GPT-5.5 API'sini nasıl kullanacağınızı inceleyebilirsiniz.

TL;DR

  • Uç nokta: POST https://api.mistral.ai/v1/chat/completions
  • Kimlik doğrulama: Authorization: Bearer <MISTRAL_API_KEY>
  • Model ID: mistral-medium-3.5
  • Bağlam penceresi: 256K token
  • Fiyatlandırma: milyon giriş tokenı başına 1,5$, milyon çıkış tokenı başına 7,5$
  • Yetenekler: akıl yürütme, görsel girdi, yerel işlev çağırma, yapılandırılmış JSON çıkışı ve 24 dil desteği
  • Açık ağırlıklar: Hugging Face üzerinde mistralai/Mistral-Medium-3.5-128B
  • SWE-Bench Verified: %77,6
  • τ³-Telekom: 91,4
  • Pratik test akışı: Apidog'u indirin, API anahtarını gizli değişkende saklayın, mevcut modelinizle A/B test edin ve çağrı başına token maliyetini izleyin.

Medium 3.5'te Neler Değişti?

Medium 3, daha önce 128K bağlam penceresine sahip metin odaklı bir model olarak konumlanıyordu. Medium 3.5 ise Mistral'ın amiral gemisi birleştirilmiş modeli olarak gelir: talimat takip etme, akıl yürütme ve kodlama tek ağırlık setinde birleşir. Bu nedenle sohbet modeli ile akıl yürütme modeli arasında seçim yapmak yerine aynı model üzerinden ilerleyebilirsiniz.

Medium 3.5 görseli

Öne çıkan üç sayı:

  • SWE-Bench Verified: %77,6 — kod yamalama ve yazılım mühendisliği görevleri için güçlü bir gösterge.
  • τ³-Telekom: 91,4 — çok turlu ajan diyaloglarında güçlü performans.
  • 256K bağlam — orta büyüklükte bir kod tabanını, uzun belgeleri veya saatlerce transkripti tek çağrıda işlemek için yeterli alan.

Fiyat tarafında Medium 3.5 daha pahalıdır. Medium 3, milyon giriş tokenı başına 0,40$ ve milyon çıkış tokenı başına 2,00$ seviyesindeydi. Medium 3.5, giriş için 1,5$ ve çıkış için 7,5$ olarak fiyatlanır. Bu yüzden pratik yaklaşım şudur:

  • Ucuz ve toplu işler için Medium 3 kullanın.
  • Kod, görsel, uzun bağlam veya ajan mantığı gereken kritik çağrılarda Medium 3.5'e yükseltin.

Önkoşullar

İlk çağrıdan önce şunları hazırlayın:

  1. console.mistral.ai üzerinde ödeme yöntemi tanımlı bir Mistral hesabı.
  2. Üretim için proje kapsamlı bir API anahtarı.
  3. Python veya JavaScript SDK.
  4. İstekleri tekrar çalıştırmak, farklı prompt sürümlerini karşılaştırmak ve anahtarı gizli tutmak için Apidog gibi bir API istemcisi.

Mistral API yapılandırması

API anahtarını terminalde ortam değişkeni olarak tanımlayın:

export MISTRAL_API_KEY="..."
Enter fullscreen mode Exit fullscreen mode

Uç Nokta ve Kimlik Doğrulama

Medium 3.5 için sohbet tamamlama uç noktası:

POST https://api.mistral.ai/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

Minimum curl isteği:

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Başarılı yanıt şunları içerir:

  • choices
  • usage.prompt_tokens
  • usage.completion_tokens
  • usage.total_tokens
  • izleme için kullanılabilecek id

Hatalar ise genellikle error.code ve error.message alanlarını içeren OpenAI benzeri bir zarfla döner.

İstek Parametreleri

Parametre Tip Değerler Not
model string mistral-medium-3.5 Zorunlu
messages array rol/içerik çiftleri Zorunlu
temperature float 0 - 1.5 Genel kullanım için 0.7, kod için 0.3 önerilir
top_p float 0 - 1 Varsayılan 1.0
max_tokens int 1 - bağlam limiti Çıkış uzunluğunu sınırlar
stream bool true / false SSE akışını açar
tools array OpenAI araç şeması Yerel işlev çağırma
tool_choice string/object auto, any, none veya belirli araç Araç kullanımını kontrol eder
response_format object {"type":"json_object"} veya JSON şeması Yapılandırılmış çıktı
random_seed int herhangi bir int Tekrarlanabilirlik için
safe_prompt bool true / false Mistral güvenlik istemini ekler
presence_penalty float -2 - 2 Tekrarlanan konuları cezalandırır
frequency_penalty float -2 - 2 Tekrarlanan tokenleri cezalandırır

OpenAI'dan geçerken iki fark önemlidir:

OpenAI:  tool_choice="required"
Mistral: tool_choice="any"

OpenAI:  seed
Mistral: random_seed
Enter fullscreen mode Exit fullscreen mode

Python ile Medium 3.5 Kullanımı

Resmi Mistral SDK'sı:

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("Content:", response.choices[0].message.content)
print("Total tokens:", response.usage.total_tokens)

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

print("Cost estimate USD:", cost)
Enter fullscreen mode Exit fullscreen mode

OpenAI SDK ile uyumlu kullanım:

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)
Enter fullscreen mode Exit fullscreen mode

Eğer sağlayıcıdan bağımsız bir kod tabanınız varsa OpenAI SDK yolu daha hızlıdır. Mistral'a özgü özellikleri daha net kullanmak istiyorsanız resmi mistralai SDK'sını tercih edin.

Node.js ile Medium 3.5 Kullanımı

Resmi Mistral SDK'sı:

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("Usage:", response.usage);
Enter fullscreen mode Exit fullscreen mode

OpenAI SDK ile:

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);
Enter fullscreen mode Exit fullscreen mode

Akış Yanıtları

Akış için stream: true kullanın. SSE parçaları OpenAI formatına yakındır.

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)
Enter fullscreen mode Exit fullscreen mode

Terminal yerine karşılaştırmalı test yapıyorsanız Apidog yanıt görüntüleyicisiyle aynı istemi farklı modellerde yan yana çalıştırabilirsiniz.

Araç Çağırma

Medium 3.5 yerel işlev çağırmayı destekler. Önce çağrılabilir araçları tools içinde tanımlayın:

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)
Enter fullscreen mode Exit fullscreen mode

Tipik araç döngüsü:

  1. Model araç çağrısı üretir.
  2. Uygulama ilgili fonksiyonu yerel olarak çalıştırır.
  3. Sonuç role: "tool" mesajı olarak tekrar modele gönderilir.
  4. Model nihai cevabı üretir veya yeni bir araç çağrısı ister.

Bu akış OpenAI araç kullanım döngüsüyle aynıdır.

JSON Modu ve Yapılandırılmış Çıktı

Şema doğrulamalı çıktı için response_format içinde JSON şeması gönderin:

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

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Daha gevşek JSON çıktısı için:

response_format = {"type": "json_object"}
Enter fullscreen mode Exit fullscreen mode

Bu durumda istemci tarafında Pydantic, Zod veya benzer bir doğrulama katmanı eklemek iyi olur.

Görsel Girdi

Medium 3.5, metinle birlikte görsel içerik alabilir. Görseli messages[].content içinde image_url olarak geçin:

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)
Enter fullscreen mode Exit fullscreen mode

Görseller giriş tokenı olarak ücretlendirilir. Tam token sayısı çözünürlüğe göre değişir ve usage.prompt_tokens alanında raporlanır. Yüksek hacimli görsel iş yüklerinde:

  • ilgili bölgeyi kırpın,
  • gereksiz çözünürlüğü azaltın,
  • her çağrıda usage değerini kaydedin.

Apidog'da Medium 3.5 Koleksiyonu Oluşturma

Terminalden aynı isteği tekrar çalıştırmak hem kredi tüketir hem de varyantlar arasındaki farkı takip etmeyi zorlaştırır. Daha sürdürülebilir akış:

  1. Apidog'u indirin ve yeni bir proje oluşturun.
  2. Bir ortam ekleyin.
  3. MISTRAL_API_KEY değerini gizli değişken olarak kaydedin.
  4. BASE_URL değerini şu şekilde tanımlayın: 
https://api.mistral.ai/v1
Enter fullscreen mode Exit fullscreen mode
  1. Yeni bir POST isteği oluşturun: 
{{BASE_URL}}/chat/completions
Enter fullscreen mode Exit fullscreen mode
  1. Header ekleyin: 
Authorization: Bearer {{MISTRAL_API_KEY}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. Gövdeyi ekleyin: 
{
  "model": "mistral-medium-3.5",
  "messages": [
    {
      "role": "user",
      "content": "Explain dense merged checkpoints in two sentences."
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}
Enter fullscreen mode Exit fullscreen mode
  1. Farklı model, sıcaklık ve araç ayarlarını test etmek için isteği çoğaltmak yerine değişkenleri kullanın.
  2. Yanıt sonrası küçük bir maliyet betiği ekleyin: 
const usage = response.json().usage;

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

console.log(`Estimated cost: $${cost}`);
Enter fullscreen mode Exit fullscreen mode

Zaten DeepSeek V4 API koleksiyonu kullanıyorsanız, koleksiyonu kopyalayıp temel URL'yi https://api.mistral.ai/v1, model kimliğini de mistral-medium-3.5 yapmanız yeterlidir. Aynı yaklaşım GPT-5.5 ile karşılaştırma için de geçerlidir.

Hata Yönetimi

İlk karşılaşacağınız durum kodları:

Kod Anlamı Düzeltme
400 Hatalı istek messages, tools ve JSON şemasını doğrulayın
401 Geçersiz anahtar console.mistral.ai üzerinden anahtarı yenileyin
402 Ödeme gerekli Hesaba bakiye veya kart ekleyin
403 Model izni yok Proje kapsamını ve model ID yazımını kontrol edin
422 Parametre aralık dışında max_tokens, tool_choice veya şema alanlarını kontrol edin
429 Oran limiti Üstel geri çekilme ile tekrar deneyin
500 Sunucu hatası Kısa süre sonra tekrar deneyin
503 Aşırı yük Bekleyin veya geçici olarak Medium 3'e dönün

Python için basit yeniden deneme deseni:

import time
import random

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

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

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

    raise RuntimeError("Retry limit exceeded")
Enter fullscreen mode Exit fullscreen mode

4xx hatalarını otomatik yeniden denemeyin. Bunlar genellikle geçici değil, istek veya yetki hatasıdır.

Maliyet Kontrolü Desenleri

Medium 3.5 güçlüdür, ancak çıktı tokenı pahalıdır. Üretimde şu desenleri uygulayın:

1. Varsayılanı ucuz model yapın

Önce Medium 3 veya daha ucuz bir modelle ilk geçiş yapın. Sadece doğrulama başarısız olursa veya düşük güven skoru dönerse Medium 3.5'e yükseltin.

2. max_tokens değerini sınırlandırın 

{
  "max_tokens": 1200
}
Enter fullscreen mode Exit fullscreen mode

256K bağlam girdi içindir. Uzun çıktı her çağrıda maliyeti hızlı artırır.

3. Sistem istemini kısaltın

Her sistem istemi tokenı her çağrıda tekrar faturalandırılır. 2.000 tokenlık sistem istemini 500 tokene indirmek, yüksek hacimde ciddi tasarruf sağlar.

4. Her çağrıda usage kaydedin

Kaydetmeniz gereken minimum alanlar:

{
  "prompt_tokens": 1234,
  "completion_tokens": 456,
  "total_tokens": 1690,
  "estimated_cost_usd": 0.005271
}
Enter fullscreen mode Exit fullscreen mode

5. Görsel girdiyi seçici kullanın

Görseli modele göndermeden önce:

  • kırpın,
  • sıkıştırın,
  • gereksiz kareleri atın,
  • sadece yanıt için gerekli bölgeyi gönderin.

Medium 3.5'i Diğer Mistral Seviyeleriyle Karşılaştırma

Nisan 2026 sonu itibarıyla tablo:

Model Bağlam Giriş $/M Çıkış $/M Görsel En iyi olduğu alan
mistral-small 32K 0,10$ 0,30$ Hayır Yüksek hacimli sınıflandırma, hafif sohbet
mistral-medium-3 128K 0,40$ 2,00$ Hayır Toplu iş, uzun sohbet
mistral-medium-3.5 256K 1,5$ 7,5$ Evet Akıl yürütme, kod, görsel, ajanlar
mistral-large 128K 2,00$ 6,00$ Sınırlı Sınır katmanı metin akıl yürütme

Medium 3.5; uzun bağlam, görsel girdi ve birleşik akıl yürütmeyi aynı seviyede toplar. Ancak seçim model adına göre değil, iş yüküne göre yapılmalıdır.

Başka Bir Sağlayıcıdan Geçiş

Çoğu durumda geçiş temel URL ve model ID değişikliğidir.

OpenAI'dan:

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

DeepSeek'ten:

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

Dikkat edilecek iki fark:

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

- seed=123
+ random_seed=123
Enter fullscreen mode Exit fullscreen mode

Üretim trafiğini değiştirmeden önce:

  1. Mevcut test suitinizi Mistral üzerinde çalıştırın.
  2. Bir süre gölge trafik gönderin.
  3. Yanıtları ve usage değerlerini kaydedin.
  4. Apidog'da model farklarını yan yana karşılaştırın.

Gerçek Dünya Kullanım Senaryoları

Medium 3.5 için pratik kullanım alanları:

  • Kod inceleme asistanları: 256K bağlam sayesinde PR diff'i ve ilgili dosyaları aynı çağrıda değerlendirebilir.
  • Uzun belge Soru-Cevap: Sözleşme, RFP veya politika belgelerini parçalara bölmeden işleyebilir.
  • Çok modlu veri çıkarımı: Fiş, ekran görüntüsü veya diyagramlardan yapılandırılmış alan çıkarabilir.
  • Araç çağrılı ajan döngüleri: Yerel işlev çağırma sayesinde API, veri tabanı veya iç servislerle çok turlu iş akışları kurulabilir.

Sıkça Sorulan Sorular

API'deki Mistral Medium 3.5 model kimliği nedir?

Barındırılan API için:

mistral-medium-3.5
Enter fullscreen mode Exit fullscreen mode

Hugging Face kontrol noktası:

mistralai/Mistral-Medium-3.5-128B
Enter fullscreen mode Exit fullscreen mode

Medium 3.5 OpenAI ile uyumlu mu?

Büyük ölçüde evet. Uç nokta yapısı, header'lar ve çoğu parametre benzerdir. OpenAI Python ve Node SDK'ları base_url / baseURL değişikliğiyle kullanılabilir.

Farklılıklar:

  • tool_choice="required" yerine tool_choice="any"
  • seed yerine random_seed

Medium 3.5'i yerel olarak çalıştırabilir miyim?

Evet. Ağırlıklar, büyük gelir istisnası içeren Değiştirilmiş MIT Lisansı altında açıktır. 128B parametre sayısı ciddi GPU belleği gerektirir. Nicelenmiş GGUF derlemeleri için unsloth/Mistral-Medium-3.5-128B-GGUF kullanılabilir. Yerel çalıştırma desenleri için DeepSeek V4'ü yerel olarak nasıl çalıştıracağınız rehberindeki yaklaşım uygulanabilir.

Araç çağrılarıyla akışı destekliyor mu?

Evet. Akış sırasında araç çağrısı argüman parçaları delta.tool_calls üzerinden artımlı döner. Akış tamamlandığında parçalar tam JSON nesnesine birleştirilir.

Göndermeden önce giriş tokenlarını nasıl sayabilirim?

Tam sayım için mistral-common Python paketinin tokenlaştırıcısını kullanabilirsiniz. API'nin kullandığı tokenlaştırıcıyla eşleştiği için sonuçlar usage.prompt_tokens ile tutarlı olur.

Üretimde hangi bağlam uzunluğunu planlamalıyım?

256K üst sınırdır, varsayılan hedef değildir. 200K tokenlık bir çağrı, model çıktı üretmeden önce yalnızca giriş için yaklaşık 0,30$ maliyet oluşturur. Çoğu üretim iş yükü 32K altında tutulmalıdır; uzun bağlamı yalnızca gerçekten gerekiyorsa kullanın.

Ücretsiz katman var mı?

Mistral kalıcı bir ücretsiz katman duyurmaz; yeni hesaplar zaman zaman küçük deneme kredileriyle gelebilir. Benzer seviyedeki ücretsiz deneme seçenekleri için DeepSeek V4 API'sini ücretsiz olarak nasıl kullanacağınızı inceleyebilirsiniz.

Top comments (0)