OpenCode dengan API Kompatibel OpenAI: Pengaturan

Yang Anda butuhkan sebelum memulai

OpenCode adalah agen pemrograman sumber terbuka yang berjalan di terminal Anda. Agen ini dapat berkomunikasi dengan banyak penyedia model, dan memungkinkan Anda menambahkan penyedia kustom jika endpoint mengikuti format chat OpenAI. API ini mendukung format tersebut, sehingga pengaturannya hanya memerlukan pengisian beberapa bidang.

Kumpulkan tiga nilai ini terlebih dahulu:

• URL Dasar: https://api.kimicode.top/v1
• ID Model: uncensored
• Kunci API: buat di halaman kunci API. Akun baru dapat mengklaim kredit uji coba senilai $0.50 di sana dengan satu klik, yang cukup untuk pengujian di bawah ini. Kunci uji coba mengizinkan 2 permintaan konkuren dan 60 permintaan per menit.

Simpan kunci dalam variabel lingkungan daripada menempelkannya ke file yang akan Anda komit:

Copyexport KIMICODE_API_KEY="your-key-here"

Langkah 1: uji endpoint dengan curl

Lakukan ini sebelum mengonfigurasi alat apa pun. Jika curl berhasil dan OpenCode tidak, Anda tahu masalahnya ada di konfigurasi. Jika curl gagal, Anda memperbaiki kunci atau URL sekali, bukan di dua tempat.

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Say hello in five words."}],
    "max_tokens": 40
  }'

Anda harus mendapatkan objek JSON dengan array choices dan blok usage. Kode 401 berarti kunci API salah atau tidak memiliki awalan Bearer. Kode 404 biasanya berarti URL yang diketik salah atau sudah menyertakan /chat/completions.

Agen pemrograman melakukan streaming jawaban dan memanggil alat, jadi periksa kedua hal tersebut juga:

Copycurl -N https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to five."}]
  }'

Anda harus melihat serangkaian baris data:, masing-masing berisi delta JSON kecil, diakhiri dengan angka penggunaan dan penanda akhir. Bendera -N menonaktifkan buffering curl agar chunk muncul saat tiba.

Langkah 2: tambahkan penyedia kustom ke OpenCode

OpenCode membaca file konfigurasi JSON, opencode.json, dari folder proyek Anda atau dari direktori konfigurasi globalnya. Penyedia gaya OpenAI dideklarasikan dengan paket kompatibel OpenAI dari AI SDK, URL dasar, dan daftar model. Tata letak di bawah ini mengikuti dokumentasi publik OpenCode saat penulisan. Nama bidang dapat berubah antar-rilis, jadi bandingkan dengan bagian penyedia di dokumentasi OpenCode terbaru jika ada yang ditolak.

Copy{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kimicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kimicode API",
      "options": {
        "baseURL": "https://api.kimicode.top/v1",
        "apiKey": "{env:KIMICODE_API_KEY}"
      },
      "models": {
        "uncensored": {
          "name": "Uncensored",
          "limit": {
            "context": 100000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "kimicode/uncensored"
}

Kunci di bawah models adalah ID model persis yang dikirim ke server, sehingga harus tertulis uncensored. Baris terakhir memilih penyedia dan model sebagai default, ditulis sebagai nama penyedia, garis miring, lalu ID model.

Bentuk {env:KIMICODE_API_KEY} memberi tahu OpenCode untuk membaca variabel dari shell Anda. Jika versi Anda menangani kredensial melalui perintah login sendiri, gunakan rute itu dan biarkan kunci di luar file. Bagaimanapun juga, jangan mengomit kunci asli.

Konfigurasi proyek atau konfigurasi global

Anda dapat menyimpan blok penyedia di dua tempat. File di akar proyek berlaku hanya untuk repositori tersebut, yang cocok untuk tim yang berbagi satu pengaturan. File di direktori konfigurasi pengguna berlaku di mana saja, yang cocok untuk pengaturan default pribadi. Jika keduanya ada, file proyek akan menambahkan atau menimpa yang global.

Utamakan file global untuk definisi penyedia dan variabel lingkungan untuk kunci. Dengan demikian, setiap repositori dapat menggunakan endpoint, dan tidak ada rahasia yang berada di samping kode sumber Anda. Jika beberapa orang bekerja dalam satu proyek, komit hanya blok penyedia tanpa kunci, dan biarkan setiap orang mengatur variabel mereka sendiri. Ini juga membuat rotasi kunci menjadi sederhana: ubah variabel, mulai ulang terminal, dan file konfigurasi tetap tidak berubah.

Langkah 3: pilih model dan jalankan tugas

Mulai OpenCode di folder proyek dan buka pemilih modelnya. Penyedia kustom Anda harus muncul dalam daftar dengan nama tampilan yang Anda atur. Pilih, lalu berikan agen tugas kecil yang dapat diperiksa, seperti menjelaskan fungsi atau menulis uji unit untuk file pendek.

Mulai kecil karena dua alasan. Pertama, Anda dapat melihat apakah pemanggilan fungsi berfungsi: ketika OpenCode meminta model membaca atau mengedit file, hal itu dilakukan melalui antarmuka pemanggilan fungsi. Kedua, agen pemrograman mengirim banyak teks per giliran, termasuk konten file dan riwayat, sehingga sesi panjang mengonsumsi token dengan cepat. Bagian berikutnya memberikan angka untuk itu.

Jika model tidak muncul, periksa apakah file adalah JSON valid, apakah file berada di tempat OpenCode mencari konfigurasi, dan apakah nama penyedia cocok dengan yang Anda ketik di bidang model.

Menguji pemanggilan fungsi dan mode JSON secara langsung

OpenCode bergantung pada pemanggilan fungsi untuk membaca file, menjalankan perintah, dan mengedit kode, sehingga penting untuk mengonfirmasi bahwa endpoint menangani definisi fungsi sebelum menyalahkan agen atas kegagalan. Permintaan ini menawarkan satu fungsi dan mengajukan pertanyaan yang membutuhkannya.

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "Read a text file by path",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Respons yang baik berisi entri tool_calls yang menamai read_file dengan string argumen JSON. Agen menjalankan fungsi, lalu mengirimkan hasilnya kembali sebagai pesan dengan role diatur ke tool, dan model melanjutkan dari sana. Jika Anda hanya melihat teks biasa, coba prompt yang lebih langsung, karena apakah model memutuskan untuk memanggil fungsi adalah bagian dari perilakunya.

Mode JSON adalah sakelar terpisah. Menambahkan "response_format": {"type": "json_object"} meminta output JSON yang valid, dan membantu ketika skrip lain harus memarsing apa yang dikembalikan. Sebutkan JSON dalam prompt Anda juga, agar model mengetahui bentuk yang Anda harapkan.

Ukuran konteks dan biaya sesi

Jendela konteks adalah 100.000 token, menghitung prompt dan respons bersama. Mengatur limit.context menjadi 100000 memberi tahu agen tentang batas nyata, sehingga dapat memangkas atau meringkas riwayat sebelum server harus menolak permintaan. Respons dapat menggunakan ruang yang tersisa, dan max_tokens bersifat opsional.

Penagihan adalah $0.15 per 1M token input dan $0.50 per 1M token output. Agen bersifat input-heavy, karena setiap giliran mengirim ulang percakapan. Berikut adalah contoh perhitungan untuk sesi moderat:

• 40 giliran, masing-masing mengirim sekitar 30.000 token input: 1.200.000 token input, yang merupakan 1,2 x $0,15 = $0,18.
• Setiap giliran mengembalikan sekitar 800 token output: 32.000 token output, yang merupakan 0,032 x $0,50 = $0,016.
• Total: $0,196, jadi sekitar dua puluh sen untuk seluruh sesi.

Angka Anda akan berbeda. Baca nilai usage dalam respons, atau perhatikan header X-Balance-USD, yang melaporkan sisa saldo Anda pada setiap respons. Saldo prabayar dan tidak pernah kedaluwarsa, serta permintaan yang gagal atau ditolak tidak dikenakan biaya. Detailnya ada di halaman harga.

Ekspektasi realistis untuk agen pemrograman

Ini adalah model teks umum yang disesuaikan untuk menjawab tanpa penolakan konten untuk penggunaan dewasa yang sah. Ini bukan model yang dibangun khusus untuk kode, dan halaman ini tidak membuat klaim benchmark. Apakah model ini dapat mengedit repositori Anda secara andal adalah sesuatu yang harus Anda uji pada tugas Anda sendiri, dengan kontrol versi aktif, sebelum Anda menyerahkannya apa pun yang penting.

Model ini menangani infrastruktur yang dibutuhkan agen: pemanggilan fungsi dengan tool_calls yang di-stream, hasil fungsi dikirim kembali sebagai pesan role: "tool", dan mode JSON melalui response_format. Ini hanya teks, tanpa gambar, sehingga fitur yang melampirkan tangkapan layar tidak akan berfungsi.

Dua batas penting untuk agen. Kunci penuh mengizinkan 8 permintaan konkuren dan 300 permintaan per menit. Sub-agen atau menjalankan fungsi paralel yang memicu banyak panggilan sekaligus dapat mencapai batas konkurensi, dan permintaan yang di-stream mempertahankan slotnya hingga stream berakhir. Ketika itu terjadi, Anda mendapatkan HTTP 429 dengan kode concurrency. Kode rate_limited berarti terlalu banyak permintaan per menit. Saat kelebihan beban sementara, Anda juga mungkin melihat 429 dengan Retry-After: 5. Kurangi paralelisme atau tunggu dan coba lagi.

Pemecahan Masalah

Gejala	Penyebab yang mungkin	Perbaikan
401 Tidak Diotorisasi	Kosong atau kunci salah; variabel lingkungan tidak diatur di shell yang meluncurkan OpenCode	Jalankan echo $KIMICODE_API_KEY di terminal yang sama, lalu mulai ulang OpenCode
404 Tidak Ditemukan	URL Dasar termasuk /chat/completions atau tidak memiliki /v1	Gunakan persis https://api.kimicode.top/v1
Model tidak ditemukan	Kunci model berbeda dari uncensored	Samakan kunci di models dengan ID yang dikembalikan oleh GET /v1/models
429 dengan concurrency	Terlalu banyak permintaan sekaligus	Kurangi panggilan alat paralel, atau tunggu hingga streaming selesai
Permintaan terlalu besar	Body lebih dari 8 MB atau riwayat mendekati batas jendela konteks	Mulai sesi baru atau ringkas riwayat

Untuk hal lain yang tidak dibahas di sini, halaman dokumentasi memiliki referensi permintaan lengkap, dan panduan integrasi membahas endpoint yang sama dari sudut pandang klien gaya OpenAI lainnya.

Panduan lainnya

• Apa Arti Kompatibel OpenAI untuk API?
• Alternatif Kimicode: API LLM Terhosting Tanpa Sensor
• API LLM Tanpa Sensor: Integrasi & Harga Kompatibel OpenAI