Cara Menggunakan API Mistral Medium 3.5

Mistral merilis Medium 3.5 pada 29 April 2026. ID model API adalah mistral-medium-3.5, titik akhir (endpoint) adalah https://api.mistral.ai/v1/chat/completions, dan bentuk permintaan cukup dekat dengan standar OpenAI sehingga menukar URL dasar dari penyedia lain hanya membutuhkan satu baris kode. Angka-angka utamanya adalah jendela konteks 256K, visi asli (native vision), pemanggilan fungsi (function calling), dukungan 24 bahasa, dan 77,6% pada SWE-Bench Verified; angka-angka yang menempatkannya dalam percakapan yang sama dengan GPT-5.5 dan DeepSeek V4 untuk jenis pekerjaan agen (agentic) yang padat kode yang sedang dikerjakan oleh sebagian besar tim saat ini.

Panduan ini mencakup autentikasi, setiap parameter penting, contoh Python dan Node, masukan visi, pemanggilan alat (tool calling), mode JSON, streaming, penanganan kesalahan, dan alur kerja Apidog yang menjaga biaya tetap terlihat saat Anda mengulang prompt. Untuk panduan model yang sebanding, lihat cara menggunakan API DeepSeek V4 dan cara menggunakan API GPT-5.5.

TL;DR

• Endpoint: POST https://api.mistral.ai/v1/chat/completions. Autentikasi adalah token pembawa (bearer token) pada header Authorization standar.
• ID Model: mistral-medium-3.5. Jendela konteks: 256K token. Harga: $1,5 per juta token masukan, $7,5 per juta token keluaran.
• Model terpadu padat (dense merged model) 128B dengan kemampuan penalaran, visi, pemanggilan fungsi bawaan (native function calling), keluaran JSON terstruktur, dan cakupan 24 bahasa.
• Bobot terbuka (open weights) tersedia di Hugging Face sebagai mistralai/Mistral-Medium-3.5-128B di bawah Lisensi MIT yang Dimodifikasi dengan pengecualian pendapatan besar (large-revenue carve-out).
• SWE-Bench Verified: 77,6%. τ³-Telecom: 91,4. Kuat dalam pengkodean, mengikuti instruksi, dan penggunaan alat.
• Unduh Apidog untuk melakukan A/B testing Medium 3.5 terhadap model Anda saat ini, simpan kunci sebagai variabel rahasia, dan amati perbedaan biaya per panggilan.

Apa yang Berubah di Medium 3.5

Medium 3 dikirimkan lebih awal tahun ini sebagai model teks-saja dengan konteks 128K. Medium 3.5 adalah sesuatu yang berbeda. Ini adalah model gabungan andalan pertama Mistral: mengikuti instruksi, penalaran, dan pengkodean hidup dalam satu set bobot, sehingga Anda tidak lagi memilih antara checkpoint obrolan dan checkpoint penalaran. Visi adalah bawaan (native), konteks berlipat ganda menjadi 256K, dan pemanggilan fungsi (function calling) terhubung di tingkat model alih-alih dipasang melalui antarmuka API terpisah.

Tiga angka menjadi dasar peningkatan ini. SWE-Bench Verified pada 77,6% menempatkannya dalam kategori yang sama dengan model-model frontier teratas untuk penambalan kode. τ³-Telecom pada 91,4 menempatkannya di depan sebagian besar model generalis dalam dialog agen multi-giliran. Konteks 256K mencakup seluruh basis kode berukuran sedang atau transkrip beberapa jam tanpa pemotongan. Semua ini bukan kesalahan pembulatan pemasaran; mereka secara langsung menunjukkan apakah model dapat menyelesaikan tugas Anda tanpa perlu percobaan kedua.

Pergeseran harga adalah bagian yang perlu dianggarkan. Medium 3 berada pada $0,40 per juta token masukan dan $2,00 per juta token keluaran. Medium 3.5 melonjak menjadi $1,5 untuk masukan dan $7,5 untuk keluaran, kira-kira 4x lipat. Itu adalah biaya pendekatan checkpoint gabungan (merged-checkpoint approach) ditambah visi ditambah konteks yang lebih panjang. Perlakukan Medium 3 yang lebih lama sebagai opsi throughput massal dan Medium 3.5 sebagai tingkatan “Saya membutuhkan jawaban ini segera”.

Prasyarat

Sebelum panggilan pertama, siapkan empat hal.

• Akun Mistral di console.mistral.ai dengan metode pembayaran yang terdaftar. Tanpa saldo, panggilan akan mengembalikan 402 Payment Required.
• Kunci API yang dicakupkan ke proyek yang akan Anda tagih. Kunci proyek lebih aman daripada kunci akun untuk apa pun yang dikirimkan ke produksi.
• SDK. Mistral menerbitkan paket resmi mistralai untuk Python dan JavaScript, dan SDK OpenAI bekerja pada endpoint yang sama dengan penggantian URL dasar.
• Klien API yang dapat memutar ulang permintaan tanpa membanjiri riwayat terminal Anda. curl berfungsi untuk panggilan pertama. Setelah itu, gunakan Apidog untuk menjaga kunci dari riwayat shell Anda dan badan permintaan di bawah kontrol versi.

Ekspor kunci sekali:

export MISTRAL_API_KEY="..."

Endpoint dan autentikasi

La Plateforme Mistral mengekspos semuanya melalui satu URL dasar.

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

Autentikasi adalah token pembawa (bearer token) pada header Authorization. Permintaan minimum yang dapat dijalankan terlihat seperti ini:

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

Respons yang berhasil mengembalikan badan JSON dengan array choices, blok usage yang dipecah menjadi prompt_tokens, completion_tokens, dan total_tokens, serta id yang dapat Anda gunakan untuk pelacakan. Kegagalan mengembalikan amplop error dengan code dan message. Bentuknya sangat cocok dengan amplop OpenAI sehingga parser kesalahan apa pun yang sudah Anda miliki berfungsi tanpa modifikasi.

Parameter permintaan

Setiap bidang memetakan ke biaya atau perilaku. Berikut adalah peta untuk mistral-medium-3.5.

Dua perbedaan kecil yang sering membingungkan orang saat bermigrasi dari OpenAI: tool_choice="any" berarti “memaksa panggilan alat” (OpenAI menggunakan required), dan parameter seed adalah random_seed (OpenAI menggunakan seed). Selebihnya selaras.

Klien Python

Mistral menyediakan SDK Python resmi yang sesuai dengan API secara satu-ke-satu.

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("Konten:", response.choices[0].message.content)
print("Total token:", response.usage.total_tokens)
print("Estimasi biaya (USD):",
      response.usage.prompt_tokens * 1.5 / 1_000_000 +
      response.usage.completion_tokens * 7.5 / 1_000_000)

Jika Anda sudah memiliki basis kode berbentuk OpenAI, SDK Python OpenAI dapat digunakan pada endpoint Mistral dengan dua perubahan: URL dasar dan ID model.

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

Rute SDK OpenAI adalah jalan paling mudah bagi tim yang menjalankan kode agnostik penyedia; SDK mistralai asli adalah jalan yang mengekspos fitur-fitur khusus Mistral dengan rapi, jadi pilih berdasarkan apakah Anda berencana untuk banyak menggunakan visi dan keluaran terstruktur.

Klien Node

Pilihan dua jalur yang sama pada Node. SDK asli:

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("Penggunaan:", response.usage);

Rute SDK OpenAI, untuk paritas dengan kode yang sudah ada:

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

Respons streaming

Atur stream: true dan ulangi chunk SSE. Bentuknya sangat cocok dengan OpenAI, dan jejak penalaran kumulatif disisipkan ke dalam choices[].delta.content alih-alih dipisahkan ke dalam bidang samping.

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)

Untuk keluaran terminal, kecepatan streaming Mistral lebih cepat daripada DeepSeek V4-Pro pada panjang prompt yang sama dan kira-kira setara dengan GPT-5.5, berdasarkan uji coba berdampingan melalui penampil respons Apidog.

Pemanggilan alat

Medium 3.5 dilengkapi dengan pemanggilan fungsi bawaan (native function calling). Fungsi yang didefinisikan dalam array tools menjadi dapat dipanggil, dan model memilih kapan untuk memanggilnya.

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)

Dari sana, jalankan fungsi secara lokal, tambahkan hasilnya sebagai pesan role: "tool", dan panggil API lagi untuk melanjutkan perulangan. Pola ini identik dengan loop penggunaan alat OpenAI. Kemampuan agen (agentic capability) terlihat pada skor τ³-Telecom; dalam praktiknya, itu berarti lebih sedikit langkah yang terbuang pada alur kerja multi-giliran di mana model harus memutuskan antara memanggil alat, bertanya kepada pengguna, dan menjawab secara langsung.

Mode JSON dan keluaran terstruktur

Untuk keluaran yang divalidasi skema, teruskan skema JSON di 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,
)

Mode ketat (strict mode) memberlakukan skema pada waktu dekode, jadi Anda tidak perlu menambahkan langkah parsing Pydantic atau Zod di klien; responsnya akan sesuai dengan skema atau panggilan akan gagal dengan kesalahan terstruktur. Untuk kasus gesekan rendah (lower-friction) di mana Anda hanya memerlukan JSON valid dalam bentuk apa pun, atur response_format={"type": "json_object"} dan validasi di sisi klien.

Masukan visi

Encoder visi Medium 3.5 dilatih dari awal untuk menangani ukuran gambar dan rasio aspek yang bervariasi; Anda tidak perlu mengubah ukuran apa pun sebelumnya. Teruskan konten gambar bersama teks dalam 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"},
        ],
    }],
)

Masukan gambar ditagih sebagai token masukan dengan tarif yang sama $1,5 per juta; jumlah token yang tepat per gambar bervariasi dengan resolusi dan dilaporkan dalam bidang usage.prompt_tokens. Untuk beban kerja gambar bervolume tinggi, catat biaya token per gambar lebih awal dan putuskan apakah akan mengompres, memotong, atau melewati bingkai sebelum melakukan penskalaan.

Buat koleksi di Apidog

Memutar ulang permintaan dari terminal menghabiskan kredit dan menyembunyikan perbedaan antar proses. Alur kerja yang bertahan dalam penggunaan nyata:

1. Unduh Apidog dan buat proyek.
2. Tambahkan lingkungan dengan {{MISTRAL_API_KEY}} yang disimpan sebagai variabel rahasia sehingga tidak pernah masuk ke ekspor bersama.
3. Simpan permintaan POST ke {{BASE_URL}}/chat/completions dengan header Authorization: Bearer {{MISTRAL_API_KEY}}.
4. Parameterisasi model, temperature, dan tool_choice sehingga Anda dapat melakukan A/B testing di berbagai varian tanpa menduplikasi permintaan.
5. Gunakan penampil respons untuk memeriksa usage pada setiap proses. Tambahkan skrip pasca-respons kecil yang mengalikan prompt_tokens * 1.5 / 1_000_000 + completion_tokens * 7.5 / 1_000_000 sehingga biaya per panggilan muncul di samping setiap hasil.

Tim yang sudah menjalankan koleksi API DeepSeek V4 yang sesuai di Apidog dapat menduplikasinya, menukar URL dasar ke https://api.mistral.ai/v1, mengubah ID model menjadi mistral-medium-3.5, dan menjalankan prompt secara langsung di kedua penyedia dalam hitungan menit. Pola yang sama berlaku untuk membandingkan dengan GPT-5.5.

Penanganan kesalahan

Amplop kesalahan mengikuti konvensi OpenAI dengan cermat. Kode yang akan Anda temui pertama:

Bungkus panggilan dalam pembantu percobaan ulang (retry helper) yang menangani 429 dan 5xx dengan backoff eksponensial. Jangan mencoba lagi kesalahan 4xx secara otomatis; itu adalah bug logika, bukan kegagalan sementara. Penampil respons Apidog membuatnya mudah untuk menemukan payload tools yang salah format karena bidang yang bermasalah disorot dalam badan permintaan di samping kesalahan.

Pola kontrol biaya

Lonjakan harga 4x lipat dari Medium 3 ke Medium 3.5 menghukum routing yang malas. Lima pola menjaga tagihan tetap dapat diprediksi.

1. Defaultkan ke Medium 3, eskalasikan ke Medium 3.5. Jalankan percobaan pertama yang murah di Medium 3 dan arahkan prompt sulit ke 3.5 hanya ketika percobaan murah mengembalikan kepercayaan diri rendah atau gagal dalam validator.
2. Batasi max_tokens. Sebagian besar jawaban muat dalam 2.000 token keluaran. Jendela konteks 256K adalah untuk masukan massal, bukan keluaran massal; keluaran adalah sisi yang mahal dengan harga $7.5 per juta.
3. Jaga prompt sistem tetap ringkas. Setiap token prompt sistem ditagih pada setiap panggilan; memangkas pembukaan 2K-token menjadi 500 token mengurangi tagihan masukan Anda sebesar 75% pada endpoint bervolume tinggi.
4. Catat usage pada setiap panggilan. Kirim prompt_tokens, completion_tokens, dan estimasi USD per panggilan ke tumpukan observabilitas Anda. Peringatan pada lonjakan token keluaran yang tiba-tiba menangkap prompt yang menyimpang ke wilayah chain-of-thought.
5. Gunakan visi secara selektif. Token gambar menumpuk dengan cepat. Potong ke wilayah yang relevan sebelum mengirim, dan turunkan skala ke resolusi terendah yang masih menjawab pertanyaan.

Membandingkan Medium 3.5 dengan tingkatan Mistral lainnya

Lineup Mistral per akhir April 2026:

Medium 3.5 adalah satu-satunya tingkatan yang menggabungkan konteks panjang, visi, dan kemampuan penalaran gabungan. Tingkatan Large menawarkan kurva biaya yang berbeda (keluaran lebih murah, masukan lebih mahal) dan mengungguli 3.5 pada beberapa benchmark teks-saja; pilih berdasarkan beban kerja, bukan berdasarkan nama tingkatan.

Bermigrasi dari penyedia lain

Migrasi sebagian besar adalah perubahan URL dasar.

Dari OpenAI:

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

Dari DeepSeek:

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

Dua hal yang perlu diperhatikan:

• tool_choice="required" di OpenAI menjadi tool_choice="any" di Mistral.
• seed menjadi random_seed.

Jalankan perbedaan melalui rangkaian uji yang ada sebelum mengalihkan lalu lintas produksi. Lebih baik lagi, cerminkan lalu lintas ke Mistral dalam mode bayangan selama sehari, catat kedua respons, dan bandingkan di Apidog sebelum promosi.

Kasus penggunaan dunia nyata

Beberapa pola di mana Medium 3.5 sudah terbayar lunas:

• Asisten tinjauan kode. Skor SWE-Bench Verified 77,6% dan konteks 256K membuatnya kuat dalam tinjauan tingkat PR di mana model perlu melihat seluruh perbedaan ditambah file-file di sekitarnya.
• QA Dokumen atas PDF panjang. Konteks 256K mencakup sebagian besar kontrak, RFP, dan dokumen kebijakan dalam satu panggilan tanpa pemecahan (chunking).
• Ekstraksi data multimodal. Mengambil bidang terstruktur dari tanda terima, tangkapan layar, atau diagram dalam satu panggilan lebih baik daripada menjalankan OCR ditambah model teks terpisah.
• Loop agen dengan panggilan alat. Pemanggilan fungsi bawaan (native function calling) dan skor τ³-Telecom yang tinggi mengurangi jumlah siklus “panggilan alat gagal, coba lagi dengan JSON yang dikoreksi” yang menghabiskan token.

FAQ

• Apa ID model untuk Mistral Medium 3.5 di API?mistral-medium-3.5. Checkpoint Hugging Face diterbitkan sebagai mistralai/Mistral-Medium-3.5-128B. Jika Anda melayani bobot terbuka sendiri dengan vLLM atau Unsloth, gunakan ID Hugging Face. Untuk API yang dihosting, gunakan ID pendek.
• Apakah Medium 3.5 kompatibel dengan OpenAI?Dekat, tapi tidak identik. Bentuk endpoint, header, dan sebagian besar parameter sangat cocok dengan OpenAI, sehingga SDK Python dan Node OpenAI berfungsi dengan penggantian URL dasar. Dua perbedaan adalah tool_choice="any" (vs required OpenAI) dan random_seed (vs seed OpenAI).
• Bisakah saya menjalankan Medium 3.5 secara lokal?Ya. Bobotnya terbuka di bawah Lisensi MIT yang Dimodifikasi dengan pengecualian pendapatan besar (large-revenue carve-out). Jumlah parameter 128B berarti Anda membutuhkan memori GPU yang signifikan; build GGUF terkuantisasi dari unsloth/Mistral-Medium-3.5-128B-GGUF berjalan pada satu kartu konsumen kelas atas. Pola dari cara menjalankan DeepSeek V4 secara lokal dapat diterjemahkan secara langsung.
• Apakah ini mendukung streaming dengan panggilan alat?Ya. Streaming mengembalikan fragmen argumen panggilan alat secara inkremental pada delta.tool_calls, bentuk yang sama dengan format panggilan alat streaming OpenAI. Fragmen-fragmen tersebut terakumulasi menjadi objek JSON lengkap setelah stream ditutup.
• Bagaimana cara menghitung token masukan sebelum mengirim?Gunakan tokenizer dari paket Python mistral-common untuk hitungan yang tepat. Ini adalah tokenizer yang sama yang digunakan API, jadi hitungan byte-per-byte sesuai dengan usage.prompt_tokens pada respons.
• Panjang konteks apa yang harus saya rencanakan untuk produksi?Jendela 256K adalah batasnya, tetapi harga meningkat secara linier. Panggilan 200K-token berbiaya $0,30 hanya untuk masukan sebelum model mulai menghasilkan. Sebagian besar beban kerja produksi nyaman di bawah 32K; gunakan konteks panjang hanya ketika tugas benar-benar membutuhkannya.
• Apakah ada tingkatan gratis?Mistral tidak mengiklankan tingkatan gratis permanen, tetapi akun baru biasanya dilengkapi dengan kredit percobaan kecil. Untuk eksperimen gratis berkelanjutan pada model tingkatan serupa, lihat cara menggunakan API DeepSeek V4 secara gratis.