OpenAI Chat Completions API: Fitur dan Panduan Penggunaan

Membangun aplikasi berbasis AI bukan sekadar membuat model menghasilkan respons. Anda juga memerlukan cara yang andal untuk mengelola percakapan, mengarahkan respons, dan menghubungkan semuanya ke aplikasi Anda. OpenAI Chat Completions API memungkinkan hal ini dengan memberi developer kendali atas cara AI menangani pesan dan menghasilkan jawaban. Jika Anda ingin memahami cara kerjanya serta cara menggunakannya dalam proyek sendiri, artikel ini akan memandu Anda melalui semua hal yang perlu diketahui.

OpenAI Chat Completions API memungkinkan developer mengintegrasikan model bahasa OpenAI ke dalam aplikasi dan layanan. API ini menghasilkan respons dari rangkaian pesan dan mendukung tugas seperti percakapan, menjawab pertanyaan, pembuatan konten, serta analisis teks.

Chat Completions tetap didukung. Untuk proyek baru, OpenAI merekomendasikan Responses API. Panduan ini berfokus pada Chat Completions untuk menjelaskan format pesannya, parameter permintaan, dan penggunaannya dengan SDK yang kompatibel.

Berbeda dengan endpoint Completions lama (/v1/completions), yang menerima prompt teks, Chat Completions menerima daftar pesan terstruktur. Setiap pesan memiliki peran, seperti developer, user, atau assistant, yang membantu model menafsirkan instruksi dan konteks percakapan. Peran serta jenis konten yang didukung bergantung pada model yang dipilih.

Developer dapat menggunakan API untuk membangun berbagai fitur berbasis AI, termasuk:

• Aplikasi percakapan: Buat chatbot AI, asisten virtual, dan sistem dukungan pelanggan yang merespons pesan pengguna.

• Pembuatan konten: Buat artikel, deskripsi produk, email, ringkasan, dan konten tertulis lainnya.

• Analisis teks: Klasifikasikan teks, ekstrak informasi, analisis sentimen, dan identifikasi poin-poin utama dalam dokumen.

• Bantuan coding: Buat cuplikan kode, jelaskan konsep pemrograman, dan bantu developer memecahkan masalah error.

• Pemrosesan bahasa: Terjemahkan, tulis ulang, sederhanakan, dan periksa teks dalam berbagai bahasa.

API ini menyediakan cara yang fleksibel untuk menghubungkan model bahasa dengan perangkat lunak yang sudah ada, sehingga developer dapat memasukkan respons yang dihasilkan AI ke dalam aplikasi tanpa perlu membangun dan meng-host model bahasa sendiri.

Chat Completions API menggunakan alur kerja permintaan dan respons. Aplikasi mengirimkan permintaan yang berisi pengenal model dan daftar pesan ke endpoint API. Model yang dipilih memproses input dan mengembalikan respons yang dihasilkan.

Alur kerja dasar mencakup langkah-langkah berikut:

1. Siapkan percakapan: Aplikasi mengumpulkan input pengguna dan menyusunnya menjadi daftar pesan. Pesan percakapan sebelumnya juga dapat disertakan untuk memberikan konteks.

2. Kirim permintaan API: Aplikasi mengirim permintaan POST ke https://api.openai.com/v1/chat/completions dengan model yang dipilih dan daftar pesan. Permintaan menggunakan header Authorization: Bearer <API_KEY>. Metode client.chat.completions.create() dari Python SDK menangani struktur permintaan dan autentikasi ini.

3. Proses input: Model menafsirkan pesan, mempertimbangkan peran dan kontennya, lalu menghasilkan respons berdasarkan konteks dan parameter yang diberikan.

4. Terima respons: Permintaan non-streaming mengembalikan respons JSON yang berisi completion dan metadata yang dihasilkan. Saat streaming diaktifkan, API mengirimkan rangkaian server-sent events (SSE), yang diproses aplikasi saat diterima.

5. Tampilkan atau proses output: Aplikasi mengekstrak pesan yang dihasilkan dan menampilkannya kepada pengguna atau meneruskannya ke komponen aplikasi lain.

Alur kerja ini didasarkan pada model permintaan dan respons OpenAI Chat Completions API.

Untuk menggunakan Chat Completions API secara efektif, developer perlu memahami parameter permintaan utamanya dan dampaknya terhadap perilaku model.

Parameter model menentukan model bahasa yang memproses permintaan. Model yang berbeda dapat menawarkan kemampuan, kecepatan respons, kinerja penalaran, dan harga yang berbeda.

Developer harus memilih model berdasarkan kompleksitas tugas, kualitas respons yang diharapkan, kebutuhan latensi, dan anggaran.

Parameter messages berisi array pesan percakapan. Setiap pesan biasanya mencakup kolom role dan content.

Peran yang umum meliputi:

Pilih peran instruksi yang didukung model Anda; Anda tidak perlu mengirim pesan system dan developer sekaligus untuk instruksi yang sama. Untuk mempertahankan konteks antar-giliran, sertakan riwayat percakapan yang relevan dalam setiap permintaan. Penyedia yang kompatibel mungkin mendukung peran yang berbeda, jadi ikuti dokumentasi model mereka saat menyesuaikan integrasi.

Pada model dan konfigurasi yang mendukungnya, temperature mengontrol keacakan sampling. Referensi API menetapkan rentang 0 hingga 2, dengan nilai default 1. Periksa dukungan parameter model yang dipilih sebelum menetapkan nilai kustom.

• Temperature lebih rendah: Menghasilkan respons yang lebih terfokus dan dapat diprediksi, sehingga berguna untuk klasifikasi, ekstraksi informasi, dan tugas terstruktur.

• Temperature lebih tinggi: Memungkinkan lebih banyak variasi dalam teks yang dihasilkan, yang dapat berguna untuk brainstorming dan penulisan kreatif.

Beberapa konfigurasi penalaran tidak menerima nilai temperature atau top_p kustom. Untuk konfigurasi tersebut, hilangkan parameter sampling ini dan gunakan kontrol yang didukung, seperti upaya penalaran dan batas output.

Jika didukung, top_p mengontrol pemilihan token melalui nucleus sampling. Parameter ini menetapkan ambang probabilitas kumulatif yang digunakan untuk memilih token kandidat.

Sebagai contoh, nilai 0.1 berarti model mempertimbangkan token dalam 10% tertinggi dari massa probabilitas kumulatif. Nilai yang lebih rendah umumnya menghasilkan output yang lebih terfokus, sedangkan nilai yang lebih tinggi memungkinkan variasi yang lebih besar.

OpenAI menyarankan untuk menyesuaikan temperature atau top_p, alih-alih mengubah keduanya secara bersamaan.

Parameter max_completion_tokens menetapkan jumlah maksimum token yang dapat dihasilkan model dalam sebuah respons, termasuk token penalaran jika berlaku.

Menetapkan batas yang sesuai membantu developer mengontrol panjang output dan mengelola konsumsi token. Jika model mencapai batas ini sebelum menyelesaikan responsnya, proses pembuatan respons dapat berakhir dengan alasan selesai length.

Parameter stream menentukan apakah API mengembalikan respons yang dihasilkan sekaligus atau secara bertahap saat respons dibuat.

• false: Mengembalikan respons lengkap setelah pembuatan selesai.

• true: Mengalirkan data respons ke aplikasi melalui server-sent events (SSE).

Streaming berguna untuk antarmuka chat dan aplikasi ketika pengguna lebih diuntungkan dengan melihat respons muncul secara bertahap daripada menunggu seluruh output.

Parameter response_format memilih format output pada model yang didukung. Teks adalah format default. Menetapkan type ke json_object mengaktifkan mode JSON, yang menghasilkan JSON valid tetapi tidak menerapkan skema tertentu. Sertakan instruksi untuk mengembalikan JSON dalam pesan.

Untuk kolom dan tipe data yang dapat diprediksi, gunakan Structured Outputs berbasis JSON Schema dengan type: "json_schema" dan strict: true pada model yang kompatibel. Hanya subset JSON Schema yang didukung yang dapat digunakan dalam mode ketat. Sebelum memproses hasilnya, periksa apakah ada penolakan atau respons yang terpotong. Lihat panduan Structured Outputs untuk detail konfigurasi.

Parameter tool_choice mengontrol pemilihan alat ketika model mendukung pemanggilan alat melalui Chat Completions. Dukungan bergantung pada model dan konfigurasi penalarannya; beberapa model yang lebih baru memerlukan Responses API untuk menggunakan alat. Periksa persyaratan ini sebelum menambahkan alat ke permintaan.

Pengaturan umum meliputi:

• none: Mencegah model memanggil alat.

• auto: Memungkinkan model memutuskan apakah akan memanggil alat yang tersedia.

• required: Mengharuskan model memanggil satu atau beberapa alat.

Kemampuan ini mendukung pemanggilan fungsi, yang memungkinkan aplikasi menghubungkan keputusan yang dihasilkan model dengan fungsi, database, dan layanan eksternal. Aplikasi bertanggung jawab menjalankan fungsi yang diminta dan mengembalikan hasilnya kepada model.

Gunakan referensi Chat Completions API untuk definisi parameter dan persyaratan kompatibilitas model. Contoh Python di bawah ini menggunakan permintaan teks dasar tanpa alat.

Developer dapat mengakses Chat Completions API melalui permintaan HTTP atau SDK resmi. Contoh berikut menggunakan Python untuk mengirim permintaan percakapan dan mengambil respons yang dihasilkan.

Langkah 1. Dapatkan kunci API

Buat kunci API di platform OpenAI API dan pastikan akun Anda memiliki akses ke model yang dipilih serta kredit API atau kapasitas penagihan yang memadai. Simpan kunci tersebut dalam variabel lingkungan, bukan dalam kode sumber aplikasi. Di macOS atau Linux, jalankan:

Ganti YOUR_API_KEY dengan kunci Anda sendiri. Di Windows, tetapkan variabel OPENAI_API_KEY yang sama di shell atau lingkungan sistem Anda.

Langkah 2. Instal SDK Python OpenAI

Instal library Python resmi menggunakan pip:

Langkah 3. Inisialisasi klien API

Impor SDK dan inisialisasi klien. OpenAI() secara otomatis membaca variabel lingkungan OPENAI_API_KEY yang ditetapkan pada Langkah 1.

Langkah 4. Kirim permintaan chat completion

Panggil client.chat.completions.create() dengan model dan daftar pesan. Contoh ini menggunakan gpt-6-astra dengan upaya penalaran rendah dan batas total pembuatan 4.096 token. Jika model ini tidak tersedia untuk akun Anda, pilih model yang mendukung Chat Completions dan sesuaikan parameternya dengan dokumentasinya.

Dalam contoh ini:

• model mengidentifikasi model bahasa yang digunakan untuk menghasilkan respons.

• messages menyediakan instruksi dan input pengguna.

• reasoning_effort menetapkan upaya penalaran untuk model yang mendukung parameter ini.

• max_completion_tokens membatasi token yang dihasilkan, termasuk token penalaran. Parameter ini tidak menjamin jumlah teks terlihat tertentu.

• response.choices[0].message.content mengekstrak respons asisten.

Memproses respons API

Untuk permintaan non-streaming ini, API mengembalikan JSON yang berisi completion dan metadata permintaan. Python SDK menguraikannya menjadi objek ChatCompletion, sehingga contoh tersebut mengakses kolom melalui atribut seperti response.choices[0].message.content.

Kolom respons penting meliputi:

Kolom finish_reason dapat membantu developer memahami cara sebuah generasi berakhir. Nilai yang umum mencakup stop, length, dan tool_calls.

Developer juga dapat memeriksa kolom usage untuk memantau konsumsi token input dan output, yang berguna untuk memperkirakan biaya API dan mengoptimalkan penggunaan aplikasi.

Contoh ini menunjukkan respons teks dasar. Saat menambahkan streaming, output terstruktur, atau tools, perbarui logika penanganan permintaan dan respons agar sesuai dengan model dan endpoint yang dipilih.

Bagi developer yang mencari alternatif untuk OpenAI Chat Completions API, Kimi API menyediakan akses ke model bahasa besar Moonshot AI melalui format API yang kompatibel dengan OpenAI.

Kimi menawarkan antarmuka Chat Completions, Responses, dan Messages. Contoh di bawah menggunakan endpoint Chat Completions yang kompatibel dengan OpenAI sehingga Anda dapat menggunakan kembali alur kerja SDK yang diperkenalkan di atas. Konfigurasikan Kimi API key, tetapkan base URL Kimi, lalu pilih model yang didukung. Ikuti dokumentasi Kimi sendiri untuk parameter model, peran pesan, dan dukungan tools.

Langkah 1. Dapatkan Kimi API key

Daftar di platform Kimi API dan buat API key di konsol developer. Periksa saldo, akses model, dan batas laju akun sebelum membuat permintaan pertama.

Simpan key Kimi dalam variabel lingkungan terpisah. Di macOS atau Linux, jalankan:

Ganti YOUR_KIMI_API_KEY dengan key Kimi Anda sendiri. Di Windows, tetapkan variabel KIMI_API_KEY yang sama di lingkungan Anda.

Langkah 2. Instal OpenAI Python SDK

Jika SDK belum terinstal, jalankan:

Langkah 3. Konfigurasikan klien Kimi API

Buat kimi_client terpisah menggunakan base URL Kimi dan variabel KIMI_API_KEY yang ditetapkan pada Langkah 1. Membaca key dengan os.environ membuat variabel lingkungan yang tidak ada langsung terlihat sebagai error.

Langkah 4. Kirim permintaan Chat Completions

Gunakan metode SDK yang sama dengan klien Kimi. Permintaan ini memilih kimi-k3, menggunakan peran system Kimi yang didukung untuk instruksi, dan mengembalikan respons teks non-streaming.

• Pilihan model untuk berbagai beban kerja: Kimi K3.1 Pro mendukung penalaran kompleks, coding jangka panjang, dan pekerjaan berbasis pengetahuan. Varian Highspeed-nya menawarkan output yang lebih cepat dengan kemampuan model yang sama. Contoh di atas menggunakan Kimi K3; periksa daftar model terkini untuk ketersediaan dan panduan migrasi.

• Kompatibilitas OpenAI API: Developer yang familier dengan format OpenAI Chat Completions dapat menggunakan kembali struktur permintaan serupa dan alur kerja SDK yang didukung saat mengintegrasikan model Kimi.

• Percakapan multi-giliran: Developer dapat menyediakan riwayat pesan untuk mendukung percakapan yang memahami konteks, asisten virtual, dan aplikasi interaktif.

• Streaming dan pemanggilan fungsi: API mendukung respons streaming dan alur kerja pemanggilan tools, sehingga developer dapat membangun aplikasi yang lebih interaktif dan menghubungkan model dengan fungsi eksternal.

• Input multimodal: Model Kimi yang didukung dapat memproses berbagai jenis input, termasuk teks, gambar, dan video, bergantung pada kemampuan model.

Saat bekerja dengan Chat Completions API, developer dapat menemui error terkait autentikasi, konfigurasi API, ketersediaan model, atau batas permintaan. Memahami masalah umum ini dapat membantu Anda mengidentifikasi masalah dan menjalankan integrasi dengan lancar:

• API key tidak valid atau tidak ada: Error autentikasi, seperti HTTP 401, dapat terjadi jika API key salah, kedaluwarsa, dicabut, atau tidak dikonfigurasikan dengan benar. Periksa bahwa key tersebut valid, variabel lingkungan dimuat dengan benar, dan permintaan menyertakan kredensial autentikasi yang sesuai.

• Base URL API salah: Permintaan yang dikirim ke endpoint yang salah dapat menghasilkan error seperti 404 atau kegagalan koneksi. Verifikasi bahwa base URL sesuai dengan dokumentasi penyedia API dan permintaan menggunakan path endpoint yang benar. Saat beralih antara OpenAI dan penyedia yang kompatibel, ingatlah untuk memperbarui base URL sesuai kebutuhan.

• ID model tidak valid atau tidak tersedia: Permintaan dapat gagal jika nama model yang ditentukan salah, tidak tersedia melalui akun Anda, atau tidak didukung oleh endpoint yang dipilih. Periksa dokumentasi model penyedia dan pastikan ID model sesuai dengan yang tersedia untuk akun API Anda.

• Panjang konteks terlampaui: Jika gabungan pesan input dan output yang dihasilkan melebihi jendela konteks model, API dapat menolak permintaan. Kurangi panjang input, hapus riwayat percakapan yang tidak diperlukan, atau ringkas pesan sebelumnya sebelum mengirimkan permintaan lagi.

• Output terpotong: Respons dapat berhenti sebelum konten yang diminta selesai jika mencapai batas max_completion_tokens. Tingkatkan batas token jika didukung, atau bagi tugas generasi panjang menjadi permintaan yang lebih kecil. Anda juga dapat memeriksa choices[].finish_reason untuk mengetahui apakah respons berakhir karena batas length.

• Batas laju atau kuota terlampaui: Untuk OpenAI, HTTP 429 dapat menunjukkan batas laju permintaan atau token, batas pengeluaran, atau pembatasan penggunaan lainnya. Periksa jenis dan kode error sebelum mencoba lagi. Untuk batas laju sementara, kurangi frekuensi permintaan dan ikuti Retry-After jika tersedia, atau gunakan exponential backoff.

Jika error menunjukkan kredit habis atau adanya batas penagihan atau pengeluaran, periksa saldo dan pengaturan penagihan akun; mencoba lagi berulang kali tidak akan memulihkan akses. Saat menggunakan Kimi atau penyedia kompatibel lainnya, ikuti dokumentasi kode error penyedia tersebut karena kode status dan aturan kuota dapat berbeda.

Untuk debugging yang lebih efisien, periksa kode status HTTP dan pesan error yang dikembalikan oleh API sebelum mengubah parameter permintaan. Detail ini dapat membantu membedakan masalah autentikasi, error konfigurasi, dan batas penggunaan.

Chat Completions API dapat mendukung berbagai skenario aplikasi. Format pesannya yang terstruktur dan parameter generasi yang dapat disesuaikan membuatnya cocok untuk fitur berbasis teks sederhana maupun alur kerja AI yang lebih kompleks.

• Chatbot AI dan asisten virtual: Developer dapat menggunakan API untuk membangun asisten percakapan bagi situs web, aplikasi seluler, dan platform layanan pelanggan. Dengan meneruskan pesan sebelumnya ke permintaan berikutnya, aplikasi dapat mempertahankan konteks percakapan dan memberikan respons yang lebih relevan.

• Pembuatan konten dan penyuntingan teks: API dapat menghasilkan dan mengubah teks berdasarkan instruksi pengguna. Aplikasi dapat menggunakannya untuk menyusun draf artikel blog, menulis materi pemasaran, merangkum konten panjang, menulis ulang paragraf, dan menyesuaikan gaya penulisan untuk berbagai audiens dan tujuan.

• Klasifikasi teks dan ekstraksi informasi: Bisnis dapat mengintegrasikan API ke dalam alur kerja yang memproses teks dalam volume besar. Misalnya, API dapat mengklasifikasikan masukan pelanggan, mengidentifikasi sentimen, mengekstrak informasi penting dari pesan, dan mengelompokkan konten tidak terstruktur ke dalam kategori yang telah ditentukan.

• Asisten coding: API dapat mendukung alat pengembangan perangkat lunak dengan menghasilkan kode, menjelaskan konsep pemrograman, menyarankan solusi, dan membantu developer mengidentifikasi kesalahan. Aplikasi juga dapat menghubungkan model ke alat pengembangan eksternal melalui pemanggilan fungsi.

• Alur kerja bisnis berbasis AI: Developer dapat mengintegrasikan API ke dalam aplikasi bisnis untuk mengotomatiskan tugas berulang yang berkaitan dengan bahasa. Contohnya mencakup pemrosesan pertanyaan pelanggan, pembuatan laporan, ekstraksi informasi dari dokumen, dan penyusunan respons berdasarkan instruksi yang telah ditentukan.

OpenAI Chat Completions API memberi developer cara praktis untuk menghadirkan AI percakapan ke dalam aplikasi mereka dan menciptakan pengalaman pengguna yang lebih bermanfaat. Memilih model yang tepat, memahami parameternya, dan menangani respons API dengan cermat dapat memberikan perbedaan nyata pada performa aplikasi. Namun, developer tidak harus bergantung pada satu penyedia saat membangun solusi berbasis AI. Jika ingin menjajaki pilihan lain, cobalah Kimi API dan lihat bagaimana pengaturannya yang kompatibel dengan OpenAI sesuai dengan kebutuhan pengembangan Anda.