ID ▾

API MiniMax di Python: Gunakan SDK OpenAI

Anda tidak perlu klien khusus untuk memanggil API ini dari Python. Paket openai standar bekerja setelah Anda mengatur base URL dan kunci, dan panduan ini mencakup chat, streaming, JSON, alat, percobaan ulang, dan perhitungan biaya.

Diperbarui

Pita kurung kode bercahaya yang menenun melalui lapisan API bertumpuk, mewakili Python memanggil API

Poin utama

  • Instal openai, lalu teruskan base_url https://api.minimaxapikey.com/v1 dan kunci Anda ke klien.
  • Gunakan ID model uncensored untuk chat, streaming, mode JSON, dan pemanggilan alat.
  • Tangani HTTP 429 dengan backoff, dan batasi utas menjadi 8 untuk kunci penuh, 2 untuk kunci uji coba.
  • Baca usage dari setiap respons dan kalikan dengan $0,15 dan $0,50 per 1M token untuk melacak pengeluaran.

Instal dan buat panggilan pertama

Untuk minimax api python bekerja, rute tercepat adalah paket openai resmi dari PyPI. Layanan di balik situs ini adalah API yang kompatibel dengan OpenAI yang di-host oleh penyedia independen, sehingga tidak ada SDK terpisah yang perlu dipelajari. Ini bukan platform resmi dari vendor, dan satu-satunya perubahan dari skrip OpenAI standar adalah base URL, kunci, dan nama model.

pip install --upgrade openai
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minimaxapikey.com/v1",
    api_key=os.environ["UNCENSORED_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Answer in plain English, briefly."},
        {"role": "user", "content": "What does a context window limit?"},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

Dapatkan kunci dari halaman kunci API. Akun baru dapat mengklaim kredit uji coba senilai $0,50 di sana dengan satu klik, tanpa kartu, dan kunci tersebut berlaku selama 7 hari. Simpan kunci dalam variabel lingkungan seperti yang ditunjukkan, bukan menempelkannya ke file sumber.

Parameter sampling dan max_tokens

Parameter yang umum diteruskan langsung: temperature, top_p, stop, seed, serta penalti frekuensi dan kehadiran. seed tetap dengan suhu rendah memberikan output yang lebih dapat diulang untuk pengujian, meskipun Anda tidak boleh menganggapnya sebagai jaminan teks yang identik.

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "List five verbs for a changelog."}],
    temperature=0.3,
    top_p=0.9,
    stop=["\n\n"],
    seed=42,
    max_tokens=120,
)

max_tokens bersifat opsional. Tanpanya, completion dapat menggunakan sisa dari jendela konteks 100.000 token setelah prompt Anda. Itu berguna untuk dokumen panjang, tetapi tetapkan batas dalam kode produksi. Generasi yang tidak terkendali memakan token output nyata seharga $0,50 per 1M, dan batas memberikan plafon pada kerusakan akibat prompt yang buruk.

Respons streaming

Teruskan stream=True dan iterasi. Respons dikirim sebagai peristiwa yang dikirim server, dan SDK mengubahnya menjadi objek chunk. Cetak teks delta saat tiba untuk antarmuka chat yang terasa responsif.

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a short product description for a notebook."}],
    stream=True,
)

parts = []
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        piece = chunk.choices[0].delta.content
        parts.append(piece)
        print(piece, end="", flush=True)
print()
text = "".join(parts)

Angka usage dikirim di akhir streaming. Jika versi SDK Anda mengekspos atribut usage pada chunk terakhir, bacalah di sana; jika tidak, hitung token di sisi Anda untuk penganggaran. Satu poin praktis: permintaan streaming memegang slot konkurensinya hingga streaming selesai. Jika Anda membuka delapan streaming panjang pada kunci penuh, permintaan kesembilan akan mendapatkan 429 dengan kode concurrency hingga salah satu selesai. Selalu tutup atau konsumsi sepenuhnya streaming agar slot dilepaskan.

Mode JSON untuk output terstruktur

Saat Anda memerlukan output yang dapat dibaca mesin, atur response_format menjadi objek JSON. Sebutkan JSON dalam prompt juga, dan jelaskan kunci yang Anda inginkan, karena flag format menjamin sintaks JSON yang valid tetapi tidak skema Anda.

import json

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Reply only with JSON using keys: title, tags (list of strings)."},
        {"role": "user", "content": "Summarise: a tutorial on caching HTTP responses in Python."},
    ],
    response_format={"type": "json_object"},
)

data = json.loads(resp.choices[0].message.content)
print(data["title"], data["tags"])

Tetap validasi hasilnya. Periksa apakah kunci yang diperlukan ada dan memiliki tipe yang benar sebelum menggunakannya, dan putuskan apa yang dilakukan kode Anda ketika tidak ada, seperti mencoba lagi sekali dengan instruksi yang lebih jelas. Lapisan validasi tipis, bahkan beberapa pemeriksaan isinstance, menghemat banyak debugging produksi.

Pemanggilan alat

Pemanggilan alat mengikuti bentuk OpenAI. Anda mendeskripsikan fungsi dalam tools, secara opsional memaksa pilihan dengan tool_choice, dan model mengembalikan tool_calls dengan argumen JSON. Anda menjalankan fungsi dan mengirim hasilnya kembali sebagai pesan dengan role: "tool".

import json

def get_rate(currency):
    rates = {"EUR": 0.92, "GBP": 0.79}
    return json.dumps({"currency": currency, "per_usd": rates.get(currency)})

tools = [{
    "type": "function",
    "function": {
        "name": "get_rate",
        "description": "Exchange rate per 1 USD for a currency code.",
        "parameters": {
            "type": "object",
            "properties": {"currency": {"type": "string"}},
            "required": ["currency"],
        },
    },
}]

messages = [{"role": "user", "content": "How many EUR is 50 USD?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
messages.append(msg)

for call in msg.tool_calls or []:
    args = json.loads(call.function.arguments)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": get_rate(args["currency"])})

final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)

Tarif dalam contoh ini dibuat untuk demo. Dalam kode nyata, fungsi akan memanggil layanan Anda sendiri. Urai argumen secara defensif dengan json.loads di dalam blok try, karena model kadang-kadang dapat menghasilkan argumen yang tidak valid.

Batas laju, percobaan ulang, dan pekerjaan paralel

Kunci penuh mengizinkan 8 permintaan konkuren dan 300 per menit; kunci uji coba mengizinkan 2 konkuren dan 60 per menit. Melebihi batas akan mengembalikan HTTP 429. Kode error adalah rate_limited untuk batas per menit dan concurrency untuk terlalu banyak panggilan simultan. Beban berlebih sementara juga memberikan 429, dengan header Retry-After: 5. SDK OpenAI mencoba ulang beberapa kegagalan secara mandiri, dan Anda dapat meningkatkannya dengan max_retries. Untuk pekerjaan batch, tambahkan batas utas Anda sendiri agar Anda tetap di bawah batas secara desain, bukan dengan mencoba ulang.

from concurrent.futures import ThreadPoolExecutor
from openai import OpenAI, RateLimitError
import os, time

client = OpenAI(
    base_url="https://api.minimaxapikey.com/v1",
    api_key=os.environ["UNCENSORED_KEY"],
    max_retries=2,
)

def ask(prompt):
    for attempt in range(4):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=200,
            )
            return r.choices[0].message.content
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    return None

prompts = [f"Write one tagline for product {i}." for i in range(20)]
with ThreadPoolExecutor(max_workers=8) as pool:
    results = list(pool.map(ask, prompts))

Gunakan max_workers=2 pada kunci uji coba. Klien async, AsyncOpenAI, menerima argumen yang sama; pasangkan dengan asyncio.Semaphore(8) untuk menerapkan batas yang sama. Dokumentasi mencantumkan header respons yang dapat Anda periksa untuk batas.

Menyimpan riwayat percakapan

API bersifat stateless. API tidak mengingat panggilan sebelumnya, sehingga obrolan multi-gilir bekerja dengan mengirimkan seluruh percakapan setiap kali. Simpan daftar pesan, tambahkan giliran pengguna, panggil API, lalu tambahkan balasan asisten sebelum putaran berikutnya.

history = [{"role": "system", "content": "You are a patient Python tutor."}]

def chat(user_text):
    history.append({"role": "user", "content": user_text})
    r = client.chat.completions.create(model="uncensored", messages=history)
    reply = r.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

print(chat("What is a list comprehension?"))
print(chat("Show me one with a filter."))

Pola ini memiliki biaya yang tumbuh dengan setiap giliran: setiap permintaan membayar untuk semua giliran sebelumnya lagi sebagai token input. Dengan jendela konteks 100.000 token, Anda memiliki banyak ruang, tetapi sesi panjang menjadi mahal dan lambat. Kebijakan sederhana adalah menyimpan pesan sistem dan N giliran terakhir, atau meminta model untuk ringkasan singkat dari giliran yang lebih lama dan menggantinya dengan ringkasan tersebut. Putuskan kebijakan ini sejak awal, karena menambahkan pemangkasan ke aplikasi chat lebih merepotkan daripada membangunnya sejak awal.

Menangani error di luar 429

SDK mengangkat exception bertipe, dan memilahnya sepadan dengan beberapa baris kode. Masalah autentikasi dan permintaan yang buruk tidak akan memperbaiki diri saat percobaan ulang, sedangkan error jaringan dan beban berlebih biasanya akan. Perlakukan mereka secara berbeda.

import openai

try:
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Hello"}],
        timeout=60,
    )
except openai.AuthenticationError:
    print("Check the API key and the Bearer header.")
except openai.RateLimitError as e:
    print("Slow down:", e.response.headers.get("Retry-After"))
except openai.APIConnectionError:
    print("Network problem, retry with backoff.")
except openai.APIStatusError as e:
    print("Server said", e.status_code, e.response.headers.get("X-Request-Id"))

Saat Anda menghubungi dukungan, sertakan nilai X-Request-Id dari panggilan yang gagal. Itu mengidentifikasi permintaan persis itu. Tetapkan timeout eksplisit seperti yang ditunjukkan, karena defaultnya lama, dan panggilan yang macet yang memegang slot konkurensi secara diam-diam mengurangi throughput Anda. Permintaan yang gagal atau ditolak tidak dibebankan biaya, sehingga mencoba ulang panggilan yang gagal tidak menggandakan tagihan.

Tata letak proyek kecil yang dapat diskalakan

Skrip berkembang menjadi layanan. Sedikit struktur di awal menjaga detail API di satu tempat, sehingga perubahan selanjutnya pada nama model, timeout, atau batas hanya menyentuh satu file, bukan dua puluh.

# llm.py
import os
from openai import OpenAI

BASE_URL = "https://api.minimaxapikey.com/v1"
MODEL = "uncensored"

_client = OpenAI(base_url=BASE_URL, api_key=os.environ["UNCENSORED_KEY"], timeout=60, max_retries=2)

def complete(messages, **kwargs):
    r = _client.chat.completions.create(model=MODEL, messages=messages, **kwargs)
    return r.choices[0].message.content, r.usage

Setiap modul lain mengimpor complete dan tidak pernah membuat klien. Titik penghubung tunggal ini adalah tempat Anda menambahkan logging, penghitung pengeluaran, atau semaphore nanti. Jika Anda ingin lebih banyak materi referensi, halaman dokumentasi menampilkan endpoint yang sama dalam bentuk curl, yang berguna untuk membandingkan panggilan Python yang gagal dengan permintaan yang diketahui baik.

Penguncian versi juga membantu. Pin versi paket openai di file requirements Anda dan tingkatkan secara sengaja, membaca catatan rilis terlebih dahulu, karena perubahan SDK dapat mengubah nama exception atau perilaku percobaan ulang default. Padukan itu dengan catatan README singkat yang menyatakan base URL dan ID model yang diharapkan proyek, sehingga rekan tim baru dapat menjalankannya pada hari pertama tanpa bertanya.

Satu poin terakhir tentang pengujian. Tulis setidaknya satu tes yang berjalan dengan klien tiruan, agar suite Anda tidak menghabiskan kredit atau bergantung pada jaringan. Jaga satu smoke test langsung, dijalankan secara manual atau dalam pekerjaan malam hari, untuk menangkap perubahan di API nyata sejak dini.

Melacak saldo dan biaya dalam kode

Setiap respons membawa X-Balance-USD, dan SDK memungkinkan Anda membaca header melalui with_raw_response. Mencatatnya setelah setiap panggilan adalah cara murah untuk menangkap saldo yang habis sebelum pengguna Anda melakukannya.

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Say hello in French."}],
)
print("balance:", raw.headers.get("X-Balance-USD"))
print("request id:", raw.headers.get("X-Request-Id"))
resp = raw.parse()

def cost_usd(usage):
    return usage.prompt_tokens * 0.15 / 1_000_000 + usage.completion_tokens * 0.50 / 1_000_000

print(cost_usd(resp.usage))

Contoh perhitungan untuk memeriksa rumus: panggilan dengan 2.000 token input dan 500 token output berbiaya 2.000 x 0,15 / 1.000.000 = $0,0003 untuk input, ditambah 500 x 0,50 / 1.000.000 = $0,00025 untuk output, sehingga $0,00055. Seribu panggilan seperti itu mencapai $0,55. Permintaan yang gagal atau ditolak tidak dibebankan biaya, sehingga log yang dibangun dari objek usage yang berhasil akan sangat mendekati tagihan.

Penagihan bersifat bayar sesuai penggunaan dari saldo prabayar tanpa langganan. Top-up dimulai dari $20 hingga $500 dalam jumlah bulat apa pun, dengan bonus mulai dari $50, dan kredit tidak pernah habis; detailnya ada di halaman harga. Prompt tidak digunakan untuk pelatihan.

Tanya jawab

Apakah ada paket Python MiniMax terpisah?

Anda tidak membutuhkannya di sini. Layanan ini kompatibel dengan OpenAI, sehingga paket openai biasa bekerja dengan base_url kustom. Ini adalah layanan independen, bukan SDK resmi dari vendor.

Apakah klien async berfungsi?

Ya. AsyncOpenAI menerima argumen base_url dan api_key yang sama. Jaga jumlah permintaan yang sedang berjalan tetap sama dengan atau di bawah batas konkurensi Anda.

Bagaimana cara mendapatkan hitungan token?

Setiap respons non-streaming memiliki objek usage dengan prompt_tokens dan completion_tokens. Untuk streaming, usage dikirim di akhir, jadi bacalah dari chunk terakhir jika klien Anda menampilkannya.

Panjang konteks apa yang bisa saya gunakan?

Jendela konteksnya adalah 100.000 token, dibagi antara prompt dan completion. max_tokens bersifat opsional.

Kunci Anda hanya selangkah lagi dari satu formulir

Buat akun, salin kunci, ubah URL dasar. Itu saja seluruh proses pengaturannya.

Dapatkan kunci API