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 yapısı OpenAI standardına o kadar yakın ki, başka bir sağlayıcının temel URL'lerini değiştirmek tek bir kod satırı sürer. Başlıca özellikler arasında 256K bağlam penceresi, yerel görüş, işlev çağırma, 24 dil desteği ve SWE-Bench Verified'da %77,6'lık bir başarı oranı bulunuyor; bu rakamlar, çoğu ekibin şu anda kullandığı aracı ve yoğun kod gerektiren işler için GPT-5.5 ve DeepSeek V4 ile aynı seviyeye getiriyor.

Bu kılavuz, kimlik doğrulama, önemli her parametre, Python ve Node örnekleri, görüş girişi, araç çağırma, JSON modu, akış, hata yönetimi ve istemler üzerinde yinelerken maliyeti görünür tutan bir Apidog iş akışını kapsar. Karşılaştırılabilir model kılavuzları için DeepSeek V4 API'sini nasıl kullanacağınızı ve GPT-5.5 API'sini nasıl kullanacağınızı inceleyin.

TL;DR

• Uç nokta: POST https://api.mistral.ai/v1/chat/completions. Kimlik doğrulama, standart Authorization başlığında bir taşıyıcı (bearer) tokendir.
• Model Kimliği: 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$.
• Akıl yürütme, görüş, yerel işlev çağırma, yapılandırılmış JSON çıkışı ve 24 dil desteği ile 128B yoğun birleştirilmiş model.
• Açık ağırlıklar, büyük gelir istisnası içeren Değiştirilmiş MIT Lisansı altında Hugging Face'te mistralai/Mistral-Medium-3.5-128B olarak yayındadır.
• SWE-Bench Onaylı: %77,6. τ³-Telekom: 91,4. Kodlama, talimat takip etme ve araç kullanımı konularında güçlü.
• Apidog'u indirin, Medium 3.5'i mevcut modelinizle karşılaştırın (A/B testi), anahtarı gizli bir değişken olarak saklayın ve çağrı başına maliyet farkını izleyin.

Medium 3.5'te Neler Değişti?

Medium 3, yılın başlarında 128K bağlam penceresine sahip yalnızca metin tabanlı bir model olarak yayınlanmıştı. Medium 3.5 ise bambaşka bir şey. Bu, Mistral'ın ilk amiral gemisi birleştirilmiş modeli: talimat takip etme, akıl yürütme ve kodlama tek bir ağırlık setinde yer alıyor, bu nedenle artık bir sohbet kontrol noktası ile bir akıl yürütme kontrol noktası arasında seçim yapmak zorunda değilsiniz. Görüş yeteneği yereldir, bağlam 256K'ya iki katına çıkar ve işlev çağırma ayrı bir API yüzeyi üzerinden eklenmek yerine model düzeyinde entegre edilmiştir.

Yükseltmeyi üç sayı sağlamlaştırıyor. SWE-Bench Verified'da %77,6, kod yamalama için en iyi sınır modelleriyle aynı seviyede yer alıyor. τ³-Telekom'da 91,4 ise, çok turlu ajans diyaloglarında çoğu genel modelin önüne geçmesini sağlıyor. 256K bağlam, orta büyüklükteki tam bir kod tabanını veya birkaç saatlik bir transkripti kesmeden kapsar. Bunların hiçbiri pazarlama yuvarlama hataları değildir; doğrudan modelin görevinizi ikinci bir geçiş yapmadan tamamlayıp tamamlayamayacağına işaret eder.

Fiyatlandırma değişimi, bütçelemeniz gereken kısımdır. Medium 3, milyon giriş tokenı başına 0,40$ ve milyon çıkış tokenı başına 2,00$ idi. Medium 3.5, yaklaşık 4 kat artışla giriş için 1,5$ ve çıkış için 7,5$'a yükseliyor. Bu, birleştirilmiş kontrol noktası yaklaşımının, görüş yeteneğinin ve daha uzun bağlamın maliyetidir. Daha eski Medium 3'ü toplu işlem seçeneği olarak, Medium 3.5'i ise "bu cevaba hemen ihtiyacım var" seviyesi olarak değerlendirin.

Önkoşullar

İlk çağrıdan önce dört şeyi hazırlayın.

• console.mistral.ai adresinde kayıtlı bir ödeme yöntemine sahip bir Mistral hesabı. Bakiye olmadan çağrılar 402 Payment Required hatası döndürür.
• Fatura kesilecek projenize özel bir API anahtarı. Proje anahtarları, üretime çıkan her şey için hesap anahtarlarından daha güvenlidir.
• Bir SDK. Mistral, Python ve JavaScript için resmi mistralai paketini yayınlar ve OpenAI SDK'sı, temel URL değişikliği ile aynı uç noktaya karşı çalışır.
• Terminal geçmişinizi doldurmadan istekleri tekrar oynatabilen bir API istemcisi. curl ilk çağrı için işe yarar. Ondan sonra, anahtarı kabuk geçmişinizden ve istek gövdelerini sürüm kontrolü altında tutmak için Apidog'u kullanın.

Anahtarı bir kez dışa aktarın:

export MISTRAL_API_KEY="..."

Uç nokta ve kimlik doğrulama

Mistral'ın La Plateforme'u her şeyi tek bir temel URL üzerinden sunar.

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

Kimlik doğrulama, Authorization başlığında bir taşıyıcı (bearer) tokendir. Minimum uygulanabilir istek şöyle görünür:

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

Başarılı bir yanıt, bir choices dizisi, prompt_tokens, completion_tokens ve total_tokens'a ayrılmış bir usage bloğu ve izleme için kullanabileceğiniz bir id içeren bir JSON gövdesi döndürür. Hatalar, code ve message içeren bir error zarfı döndürür. Yapı, OpenAI zarfıyla o kadar yakından eşleşir ki, sahip olduğunuz herhangi bir hata ayrıştırıcı değişiklik yapmadan çalışır.

İstek parametreleri

Her alan ya maliyetle ya da davranışla ilişkilidir. mistral-medium-3.5 için harita aşağıdadır.

OpenAI'dan geçiş yaparken insanları zorlayan iki küçük fark var: tool_choice="any" "bir araç çağrısını zorla" anlamına gelir (OpenAI required kullanır) ve seed parametresi random_seed'dir (OpenAI seed kullanır). Diğer her şey uyumludur.

Python istemcisi

Mistral, API ile birebir eşleşen resmi bir Python SDK'sı sunar.

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)
print("Cost estimate (USD):",
      response.usage.prompt_tokens * 1.5 / 1_000_000 +
      response.usage.completion_tokens * 7.5 / 1_000_000)

Halihazırda OpenAI'ye benzer bir kod tabanınız varsa, OpenAI Python SDK'sı iki değişiklikle Mistral uç noktasına karşı çalışır: temel URL ve model kimliği.

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

OpenAI SDK yolu, sağlayıcıdan bağımsız kod çalıştıran ekipler için en az dirençli yoldur; yerel mistralai SDK'sı ise Mistral'a özgü özellikleri temiz bir şekilde ortaya çıkaran yoldur, bu nedenle görüş yeteneğini ve yapılandırılmış çıktıları yoğun bir şekilde kullanmayı planlayıp planlamadığınıza göre seçim yapın.

Node istemcisi

Node'da da aynı iki seçenekli tercih. Yerel SDK:

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

Mevcut kodla uyumluluk için OpenAI SDK yolu:

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

Akış yanıtları

stream: true ayarlayın ve SSE öbeklerini yineleyin. Yapı OpenAI ile tamamen eşleşir ve kümülatif akıl yürütme izi, ayrı bir yan alan yerine choices[].delta.content içine serpiştirilir.

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)

Terminal çıktısı için, Apidog yanıt görüntüleyicisi aracılığıyla yapılan yan yana çalıştırmalara göre, Mistral akış hızı aynı istem uzunluğunda DeepSeek V4-Pro'dan daha hızlı ve GPT-5.5 ile kabaca eşittir.

Araç çağırma

Medium 3.5, yerel işlev çağırma ile birlikte gelir. tools dizisinde tanımlanan işlevler çağrılabilir hale gelir ve model bunları ne zaman çağıracağını seçer.

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)

Buradan sonra, işlevi yerel olarak çalıştırın, sonucu bir role: "tool" mesajı olarak ekleyin ve döngüyü devam ettirmek için API'yi tekrar çağırın. Bu model, OpenAI'nin araç kullanım döngüsüyle aynıdır. Ajans yeteneği τ³-Telekom skorunda kendini gösterir; pratikte bu, modelin bir araç çağırma, kullanıcıya sorma ve doğrudan yanıtlama arasında karar vermesi gereken çok turlu iş akışlarında daha az boş adıma yol açar.

JSON modu ve yapılandırılmış çıktı

Şema tarafından doğrulanmış çıktı için, response_format içinde bir JSON şeması geçirin.

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

Katı mod, şemayı çözümleme anında zorlar, bu nedenle istemcide bir Pydantic veya Zod ayrıştırma adımı eklemenize gerek kalmaz; yanıt ya şemaya uyar ya da çağrı yapılandırılmış bir hatayla başarısız olur. Herhangi bir şekilde geçerli JSON'a ihtiyaç duyduğunuz, daha az sürtünmeli durumlarda, response_format={"type": "json_object"} ayarlayın ve istemci tarafında doğrulayın.

Görsel girdi

Medium 3.5'in görüş kodlayıcısı, değişken görüntü boyutlarını ve en boy oranlarını işlemek üzere sıfırdan eğitilmiştir; önceden boyutlandırma yapmanıza gerek yoktur. messages dizisinde metnin yanında görüntü içeriğini geçirin.

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

Görüntü girdileri, aynı milyon başına 1,5$ oranında giriş tokenı olarak faturalandırılır; görüntü başına 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örüntü iş yükleri için, görüntü başına token maliyetini erken kaydedin ve ölçeklendirmeden önce sıkıştırma, kırpma veya kareleri atlama yapıp yapmayacağınıza karar verin.

Koleksiyonu Apidog'da oluşturun

Terminalden istekleri tekrar oynatmak kredileri tüketir ve çalıştırmalar arasındaki farkı gizler. Gerçek kullanıma dayanıklı iş akışı:

1. Apidog'u indirin ve bir proje oluşturun.
2. {{MISTRAL_API_KEY}} değerini gizli bir değişken olarak saklayan bir ortam ekleyin, böylece paylaşılan dışa aktarmalara asla düşmez.
3. Authorization: Bearer {{MISTRAL_API_KEY}} başlığıyla {{BASE_URL}}/chat/completions adresine bir POST isteği kaydedin.
4. İstekleri çoğaltmadan farklı varyantlar arasında A/B testi yapabilmek için model, temperature ve tool_choice parametrelerini ayarlayın.
5. Her çalıştırmada usage'ı incelemek için yanıt görüntüleyiciyi kullanın. prompt_tokens * 1.5 / 1_000_000 + completion_tokens * 7.5 / 1_000_000 işlemini yapan küçük bir yanıt sonrası betik ekleyin, böylece çağrı başına maliyet her sonucun yanında görünür.

Apidog'da zaten DeepSeek V4 API koleksiyonunu çalıştıran ekipler, bunu kopyalayabilir, temel URL'yi https://api.mistral.ai/v1 olarak değiştirebilir, model kimliğini mistral-medium-3.5 olarak ayarlayabilir ve dakikalar içinde her iki sağlayıcıda da başa baş istemler çalıştırabilir. Aynı desen, GPT-5.5 ile karşılaştırma için de geçerlidir.

Hata yönetimi

Hata zarfı, OpenAI kurallarına yakından uyar. İlk karşılaşacağınız kodlar:

Çağrıları, 429 ve 5xx hatalarını üstel geri çekilmeyle (exponential backoff) yöneten bir yeniden deneme yardımcısıyla sarın. 4xx hatalarını otomatik olarak yeniden denemeyin; bunlar geçici arızalar değil, mantık hatalarıdır. Apidog'un yanıt görüntüleyicisi, hatalı bir tools yükünü kolayca tespit etmeyi sağlar çünkü sorunlu alan, hatanın yanında istek gövdesinde vurgulanır.

Maliyet kontrolü desenleri

Medium 3'ten Medium 3.5'e 4 katlık fiyat artışı, tembel yönlendirmeyi cezalandırır. Beş desen, faturayı öngörülebilir tutar.

1. Varsayılan olarak Medium 3'ü kullanın, Medium 3.5'e yükseltin. Medium 3 üzerinde ucuz bir ilk geçiş yapın ve zor istemleri yalnızca ucuz geçiş düşük güven döndürdüğünde veya bir doğrulayıcıda başarısız olduğunda 3.5'e yönlendirin.
2. max_tokens'ı sınırlayın. Çoğu yanıt 2.000 çıktı tokenına sığar. 256K bağlam penceresi giriş yoğunluğu içindir, çıktı yoğunluğu için değil; çıktı, milyon başına 7,5$ ile maliyetli taraftır.
3. Sistem istemlerini sade tutun. Her sistem istemi tokenı her çağrıda faturalandırılır; 2K tokenlık bir girişi 500 tokene indirmek, yüksek hacimli bir uç noktada giriş faturanızı %75 azaltır.
4. Her çağrıda usage'ı kaydedin. prompt_tokens, completion_tokens ve çağrı başına USD tahminini gözlemlenebilirlik yığınına gönderin. Anlık çıktı tokenı artışı uyarısı, düşünce zinciri alanına kayan istemleri yakalar.
5. Görsel yeteneğini seçici kullanın. Görüntü tokenları hızla artar. Göndermeden önce ilgili bölgeyi kırpın ve soruyu hala yanıtlayan en düşük çözünürlüğe düşürün.

Medium 3.5'i diğer Mistral seviyeleriyle karşılaştırma

Nisan 2026 sonu itibarıyla Mistral'ın ürün yelpazesi:

Medium 3.5, uzun bağlamı, görüşü ve birleştirilmiş akıl yürütme yeteneklerini birleştiren tek seviyedir. Large seviyesi farklı bir maliyet eğrisi sunar (daha ucuz çıktı, daha pahalı giriş) ve bazı yalnızca metin tabanlı karşılaştırmalarda 3.5'i geçer; seviye adına göre değil, iş yüküne göre seçim yapın.

Başka bir sağlayıcıdan geçiş

Geçiş genellikle temel URL değişikliğinden ibarettir.

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"

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"

Dikkat edilmesi gereken iki püf noktası:

• OpenAI'daki tool_choice="required", Mistral'da tool_choice="any" olur.
• seed, random_seed olur.

Üretim trafiğini değiştirmeden önce farkı mevcut test suitinizden geçirin. Daha da iyisi, bir gün boyunca trafiği gölge modunda Mistral'a yansıtın, her iki yanıtı da kaydedin ve yayına almadan önce Apidog'da farklarını karşılaştırın.

Gerçek dünya kullanım senaryoları

Medium 3.5'in şimdiden karşılığını verdiği birkaç kullanım deseni:

• Kod inceleme asistanları. %77,6'lık SWE-Bench Onaylı skoru ve 256K bağlam, modelin tam farkı ve çevresindeki dosyaları görmesi gereken PR düzeyindeki incelemelerde onu güçlü kılar.
• Uzun PDF'ler üzerinde belge Soru-Cevap. 256K bağlam, çoğu sözleşmeyi, RFP'yi ve politika belgesini tek bir çağrıda bölmeden kapsar.
• Çok modlu veri çıkarımı. Fişlerden, ekran görüntülerinden veya diyagramlardan yapılandırılmış alanları tek bir çağrıda çıkarmak, OCR ve ayrı bir metin modelini çalıştırmaktan daha iyidir.
• Araç çağrılarıyla ajan döngüleri. Yerel işlev çağırma ve yüksek τ³-Telekom skoru, "araç çağrısı başarısız oldu, düzeltilmiş JSON ile yeniden dene" döngülerinin token tüketimini azaltır.

Sıkça Sorulan Sorular

• API'deki Mistral Medium 3.5 model kimliği nedir?mistral-medium-3.5. Hugging Face kontrol noktası mistralai/Mistral-Medium-3.5-128B olarak yayınlanmıştır. Açık ağırlıkları kendiniz vLLM veya Unsloth ile sunuyorsanız, Hugging Face ID'sini kullanın. Barındırılan API için kısa ID'yi kullanın.
• Medium 3.5 OpenAI ile uyumlu mu? Yakın, ama aynı değil. Uç nokta yapısı, başlıklar ve çoğu parametre OpenAI ile tamamen eşleştiği için, OpenAI Python ve Node SDK'ları temel URL geçersiz kılma ile çalışır. İki farklılık tool_choice="any" (OpenAI'nin required'ına karşılık) ve random_seed (OpenAI'nin seed'ine karşılık).
• 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ı, önemli GPU belleğine ihtiyacınız olduğu anlamına gelir; unsloth/Mistral-Medium-3.5-128B-GGUF adresindeki nicelenmiş GGUF derlemeleri, tek bir üst düzey tüketici kartında çalışır. DeepSeek V4'ü yerel olarak nasıl çalıştıracağınız ile ilgili desenler doğrudan uygulanabilir.
• Araç çağrılarıyla akışı destekliyor mu? Evet. Akış, delta.tool_calls üzerinde artımlı olarak araç çağrısı argümanı parçacıkları döndürür; bu, OpenAI'nin akışlı araç çağrısı formatıyla aynıdır. Akış kapandığında parçacıklar eksiksiz bir JSON nesnesinde birikir.
• Göndermeden önce giriş tokenlarını nasıl sayabilirim? Tam sayım için mistral-common Python paketinin tokenlaştırıcısını kullanın. API'nin kullandığı tokenlaştırıcıyla aynıdır, bu nedenle byte-byte sayımlar yanıtta usage.prompt_tokens ile eşleşir.
• Üretimde hangi bağlam uzunluğunu planlamalıyım? 256K pencere sınırdır, ancak fiyatlandırma doğrusal olarak ölçeklenir. 200K tokenlık bir çağrı, model daha üretmeye başlamadan sadece giriş için 0,30$'a mal olur. Çoğu üretim iş yükü 32K'nın altına rahatça sığar; uzun bağlamı yalnızca görev gerçekten gerektirdiğinde kullanın.
• Ücretsiz katman var mı? Mistral kalıcı bir ücretsiz katman duyurmaz, ancak yeni hesaplar genellikle küçük bir deneme kredisi ile gelir. Benzer seviyedeki modellerde sürekli ücretsiz denemeler için, DeepSeek V4 API'sini ücretsiz olarak nasıl kullanacağınızı inceleyin.