Cara Bekerja dengan API Cohere

Cohere memberikan akses kepada pengembang untuk Model Bahasa Besar (LLM) yang canggih, yang mampu memahami dan menghasilkan teks mirip manusia. Untuk berinteraksi dengan model-model ini secara programatik, Anda memerlukan kunci API. Kunci ini berfungsi sebagai pengenal unik dan kata sandi Anda, memungkinkan sistem Cohere untuk mengautentikasi permintaan Anda dan melacak penggunaan Anda.

Panduan ini akan membimbing Anda melalui langkah-langkah penting: mendapatkan kunci API Anda, memahami perbedaan kritis antara jenis kunci (terutama terkait biaya dan batas penggunaan), dan melakukan tes awal sederhana menggunakan alat Apidog untuk memastikan kunci Anda berfungsi dengan benar.

Langkah 1: Mendapatkan Kunci API Cohere Anda

Mendapatkan kunci Anda adalah langkah pertama dan paling penting. Cohere membuat proses ini relatif sederhana melalui dasbor online mereka.

Menuju ke Dasbor Cohere: Buka browser web Anda dan pergi ke titik akses utama platform Cohere. Anda biasanya akan menemukan halaman login atau pendaftaran.
Akses Akun Anda:

Jika Anda sudah memiliki akun Cohere, masuklah menggunakan kredensial Anda.
Jika Anda baru di Cohere, Anda perlu mendaftar untuk akun. Ikuti proses pendaftaran, yang biasanya melibatkan penyediaan alamat email dan menetapkan kata sandi.

Cari Bagian Kunci API: Setelah Anda berhasil masuk ke dasbor Cohere, cari bagian yang secara khusus didedikasikan untuk mengelola Kunci API. Ini mungkin berada di bawah pengaturan akun, bagian pengembang, atau dapat diakses langsung melalui item menu yang diberi label "Kunci API". Antarmukanya dirancang agar mudah digunakan, jadi seharusnya cukup jelas terlihat.

Mulai Generasi Kunci: Di dalam bagian Kunci API, Anda akan menemukan opsi untuk membuat kunci baru. Anda kemungkinan akan melihat pilihan yang membedakan antara jenis kunci, terutama "Kunci Uji Coba" dan kemungkinan "Kunci Produksi". Untuk pengujian awal dan pembelajaran, pilih opsi untuk menghasilkan Kunci Uji Coba.

Tetapkan Nama: Sebuah prompt akan meminta Anda untuk memberi nama pada kunci Anda. Pilih nama deskriptif yang akan membantu Anda mengingat tujuan kunci tersebut nantinya, terutama jika Anda menghasilkan beberapa kunci untuk proyek yang berbeda. Contoh nama termasuk "KunciUjiCobaPertamaSaya", "KunciProyekBelajar", atau "KunciPengujianApidog".

Hasilkan dan Amankan Kunci Anda: Klik tombol untuk mengonfirmasi dan menghasilkan kunci (misalnya, "Hasilkan Kunci Uji Coba"). Cohere kemudian akan menampilkan kunci API baru Anda. Ini adalah satu-satunya waktu kunci lengkap akan ditampilkan. Sangat penting bahwa Anda menyalin kunci ini segera dan menyimpannya di lokasi yang sangat aman, seperti manajer kata sandi atau catatan aman. Perlakukan kunci ini dengan tingkat keamanan yang sama seperti kata sandi. Jangan membagikannya secara publik, menyematkannya langsung dalam kode sisi klien, atau mengkomitnya ke sistem kontrol versi seperti Git. Setelah Anda menutup jendela pop-up atau menavigasi pergi, Anda tidak dapat mengambil kunci lengkapnya lagi karena alasan keamanan (meskipun Anda dapat melihat nama kunci dan mungkin beberapa karakter pertama/terakhir di dasbor). Jika Anda kehilangannya, Anda perlu menghasilkan yang baru.

Dengan kunci API Anda disalin dan diamankan, Anda siap untuk memahami apa yang dapat Anda lakukan dengannya dan aturan yang terkait.

Langkah 2: Memahami Jenis Kunci, Biaya, dan Batas Penggunaan

Tidak semua kunci API Cohere dibuat sama. Jenis kunci yang Anda miliki menentukan seberapa banyak Anda dapat menggunakan API, seberapa cepat, dan apakah itu menimbulkan biaya. Memahami perbedaan ini sangat penting untuk menghindari gangguan atau biaya yang tidak terduga.

A. Kunci API Uji Coba: Gratis untuk Evaluasi

Ketika Anda pertama kali mendaftar atau menghasilkan kunci tanpa mengatur penagihan, Anda biasanya menerima Kunci Uji Coba. Kunci ini dirancang untuk eksplorasi, pembelajaran, dan pengujian skala kecil.

Biaya: Kunci uji coba adalah gratis untuk digunakan. Anda tidak akan dikenakan biaya untuk penggunaan yang terkait dengan kunci uji coba.
Batas Penggunaan Keseluruhan: Pembatasan terbesar adalah batas bulanan 1.000 total panggilan API di seluruh semua endpoint Cohere yang digabungkan. Ini berarti setiap permintaan yang Anda buat (baik ke Chat, Embed, Rerank, dll.) dihitung terhadap total bulanan ini. Setelah Anda mencapai 1.000 panggilan dalam satu bulan kalender, kunci Anda akan berhenti berfungsi hingga bulan berikutnya dimulai.
Batas Laju (Permintaan Per Menit - RPM): Untuk memastikan penggunaan yang adil dan stabilitas sistem, kunci uji coba juga memiliki batas laju yang ketat, membatasi berapa banyak permintaan yang dapat Anda kirim dalam jendela satu menit ke endpoint tertentu. Ini penting untuk diperhatikan, karena melampaui batas ini akan menghasilkan kesalahan 429 Terlalu Banyak Permintaan. Batas laju kunci Uji Coba meliputi:
Endpoint Chat (/v2/chat): 20 permintaan per menit. Ini adalah endpoint yang digunakan untuk AI percakapan, generasi teks, ringkasan, dll.
Endpoint Embed (/v2/embed) - Teks: 100 permintaan per menit. Digunakan untuk menghasilkan embedding vektor untuk data teks (pencarian semantik, pengelompokan).
Endpoint Embed (/v2/embed) - Gambar: 5 permintaan per menit. Digunakan untuk menghasilkan embedding vektor untuk data gambar (pencarian multimodal).
Endpoint Rerank (/v2/rerank): 10 permintaan per menit. Digunakan untuk meningkatkan peringkat relevansi hasil pencarian.
Endpoint Tokenize (/v2/tokenize): 100 permintaan per menit. Digunakan untuk melihat bagaimana teks dipecah menjadi token oleh model Cohere.
Endpoint Classify (/v1/classify): 100 permintaan per menit. Digunakan untuk tugas klasifikasi teks (legacy, fine-tuning lebih disukai sekarang).
Endpoint Legacy (Ringkas, Hasilkan): 5 permintaan per menit.
Lainnya/Default: Batas mungkin berlaku untuk endpoint lain yang kurang umum atau manajemen.

Kunci uji coba ideal untuk:

Mempelajari cara kerja API Cohere.
Mencoba berbagai model dan parameter di Playground atau melalui panggilan langsung.
Membangun proyek pribadi kecil atau prototipe dengan penggunaan yang diharapkan terbatas.
Evaluasi kemampuan Cohere sebelum berkomitmen pada penggunaan berbayar.

Jika Anda secara konsisten mencapai batas bulanan atau batas laju per menit, ini adalah indikator kuat bahwa Anda perlu meningkatkan ke kunci Produksi.

B. Kunci API Produksi: Untuk Membangun dan Meningkatkan

Ketika Anda siap untuk membangun aplikasi dengan pengguna nyata, menangani beban kerja yang lebih besar, atau melampaui batas uji coba, Anda akan memerlukan Kunci Produksi. Ini memerlukan pengaturan informasi penagihan di akun Cohere Anda.

Biaya: Kunci produksi beroperasi dengan model bayar sesuai penggunaan yang terutama didasarkan pada penggunaan token. Token adalah unit teks (yang kira-kira sesuai dengan kata atau bagian dari kata) yang diproses oleh model. Anda dikenakan biaya untuk token yang Anda kirim ke model (token input) dan token yang dihasilkan model dalam responsnya (token output).
Harga Bervariasi menurut Model: Model yang lebih kuat umumnya lebih mahal per token dibandingkan dengan model yang lebih ringan dan lebih cepat.
Contoh Harga (Ilustratif - periksa halaman harga resmi Cohere untuk tarif terkini):
Model Command R: Mungkin dikenakan biaya sekitar $0,50 per juta token input dan $1,50 per juta token output. (Catatan: Hasil pencarian sebelumnya menunjukkan $2,50 input / $10,00 output untuk Command R - menggunakan nilai tersebut: $2,50 / 1M token input, $10,00 / 1M token output.)
Model Command R+: Menjadi lebih mampu, mungkin memiliki harga yang lebih tinggi, mungkin $3,00 per juta token input dan $15,00 per juta token output.
Model Embed (misalnya, embed-english-v3.0): Model embedding biasanya hanya dihargai berdasarkan token input, karena mereka tidak menghasilkan output teks yang panjang. Harga mungkin sekitar $0,10 per juta token input.
Perhitungan Token: Cohere menyediakan endpoint Tokenizer dan dokumentasi untuk membantu Anda memahami bagaimana teks diterjemahkan menjadi token untuk estimasi biaya yang akurat. Input dan output yang lebih panjang secara alami dikenakan biaya lebih.
Batas Penggunaan Keseluruhan: Tidak ada batas total panggilan bulanan untuk kunci produksi. Anda dapat melakukan sebanyak mungkin panggilan yang diperlukan, asalkan Anda tetap dalam batas laju dan mengelola biaya Anda.
Batas Laju (Permintaan Per Menit - RPM): Kunci produksi mendapatkan manfaat dari batas laju yang jauh lebih tinggi, memungkinkan aplikasi untuk menangani lebih banyak lalu lintas:
Endpoint Chat (/v2/chat): 500 permintaan per menit (dibandingkan dengan 20/menit untuk Uji Coba).
Endpoint Embed (/v2/embed) - Teks: 2.000 permintaan per menit (dibandingkan dengan 100/menit).
Endpoint Embed (/v2/embed) - Gambar: 400 permintaan per menit (dibandingkan dengan 5/menit).
Endpoint Rerank (/v2/rerank): 1.000 permintaan per menit (dibandingkan dengan 10/menit).
Endpoint Tokenize (/v2/tokenize): 2.000 permintaan per menit.
Endpoint Classify (/v1/classify): 1.000 permintaan per menit.
Peningkatan Batas Laju: Untuk aplikasi dengan volume sangat tinggi, mungkin dimungkinkan untuk meminta peningkatan batas laju lebih lanjut dengan menghubungi dukungan Cohere.

Kunci produksi diperlukan untuk:

Mengembangkan dan menerapkan aplikasi yang ditujukan untuk pengguna akhir.
Menangani volume permintaan API yang konsisten atau tinggi.
Apa pun kasus penggunaan komersial.
Membuka potensi kinerja penuh tanpa terhambat oleh batas uji coba.

C. Memilih Kunci yang Tepat:

Mulailah dengan Uji Coba: Selalu mulai dengan kunci Uji Coba untuk pembelajaran dan pengembangan awal.
Pantau Penggunaan: Perhatikan volume dan frekuensi panggilan Anda.
Tingkatkan Saat Diperlukan: Jika aplikasi Anda secara konsisten mencapai batas laju, melebihi batas 1.000 panggilan bulanan, atau jika Anda sedang bersiap untuk diluncurkan secara publik atau komersial, tingkatkan ke kunci Produksi dengan menambahkan rincian penagihan di dasbor Cohere.

Oke, berikut adalah bagian Langkah 3 yang direvisi yang berfokus pada pengujian permintaan chat streaming yang diberikan dalam perintah curl menggunakan Apidog, disajikan dalam Markdown:

Langkah 3: Melakukan Panggilan Tes API Dasar untuk Chat Streaming dengan Apidog

Sebelum mengintegrasikan API ke dalam kode kompleks, terutama untuk respons streaming, bermanfaat untuk melakukan tes langsung. Apidog memungkinkan Anda untuk mereplikasi struktur perintah curl untuk memverifikasi kunci Anda dan memahami alur permintaan/respons dasar untuk streaming.

Jalankan Apidog: Buka aplikasi Apidog di komputer Anda.
Buat Permintaan Baru: Klik tombol '+' atau yang setara untuk membuat permintaan API baru. Beri nama yang deskriptif, seperti "Tes Chat Streaming Cohere".
Konfigurasikan Endpoint:

Metode HTTP: Pilih POST.
URL: Masukkan URL endpoint Chat v2 Cohere: https://api.cohere.ai/v2/chat

4. Atur Header:

Pindah ke tab "Header". Anda perlu menambahkan beberapa header berdasarkan perintah curl:
Accept: Kunci: Accept, Nilai: application/json
Content-Type: Kunci: Content-Type, Nilai: application/json
Authorization: Kunci: Authorization, Nilai: Bearer YOUR_API_KEY (Ganti YOUR_API_KEY dengan kunci API Cohere Anda yang sebenarnya. Pastikan ada spasi setelah Bearer).

5. Buat Badan Permintaan (dengan Streaming Diaktifkan):

Pindah ke tab "Badan".
Pilih opsi untuk input "raw".
Pilih JSON sebagai format.
Tempelkan payload JSON berikut, meniru data perintah curl, termasuk flag penting "stream": true:

{
  "stream": true,
  "model": "command-r",
  "messages": [
    {
      "role": "user",
      "content": "Hello world!"
    }
  ]
}

(Catatan: Contoh curl menggunakan "role": "user" (huruf kecil) dan model "command-a-03-2025". Saya tetap menggunakan "role": "USER" dan model "command-r" untuk konsistensi dengan contoh sebelumnya, tetapi Anda harus menyesuaikan casing model dan role dalam JSON di atas untuk mencocokkan dengan permintaan spesifik yang ingin Anda uji jika berbeda.)

6. Eksekusi Permintaan: Klik tombol "Kirim" di Apidog.

7. Analisis Respons (Spesifikasi Streaming):

Kode Status: Anda seharusnya tetap menerima kode status 200 OK jika permintaan awal diterima oleh server.
Header Respons: Periksa header respons untuk tanda-tanda streaming, seperti Transfer-Encoding: chunked.
Badan Respons: Cara Apidog menampilkan respons streaming mungkin bervariasi. Itu mungkin:
Menunggu hingga streaming selesai dan menampilkan teks yang sepenuhnya terhubung atau payload acara terakhir.
Menampilkan potongan mentah atau Server-Sent Events (SSE) saat mereka tiba, yang mungkin terlihat seperti beberapa objek JSON satu setelah yang lain.
Ini mungkin tidak merender teks dengan mulus token demi token seperti aplikasi yang dirancang khusus.
Konten: Telusuri konten badan respons. Anda seharusnya melihat acara terkait streaming, seperti acara text-generation yang berisi bagian dari respons "Hello world!", dan akhirnya acara stream-end yang menunjukkan proses selesai.
Kesalahan: Jika Anda mendapatkan kesalahan (401, 403, 400, 429), diagnosis sesuai dengan yang dijelaskan sebelumnya (periksa kunci API, validitas JSON, batas laju). Kesalahan 400 Bad Request mungkin terjadi jika model yang ditentukan tidak mendukung streaming atau jika parameter lainnya tidak kompatibel.

Pengujian ini membantu mengonfirmasi bahwa API menerima permintaan streaming Anda dan bahwa kunci Anda valid untuk jenis interaksi ini, meskipun Apidog sendiri bukanlah alat ideal untuk memvisualisasikan sifat waktu nyata streaming. Ini memverifikasi bahwa pengaturan permintaan dasar sudah benar.

Kesimpulan

Anda sekarang memiliki kunci API Cohere Anda dan memahami perbedaan penting antara kunci Uji Coba dan Produksi, terutama terkait batas 1.000 panggilan bulanan dan batas laju per menit pada kunci Uji Coba dibandingkan dengan model bayar sesuai penggunaan, berbasis token, dan batas yang lebih tinggi dari kunci Produksi. Anda juga telah melakukan tes dasar tetapi penting menggunakan Apidog untuk mengonfirmasi bahwa kunci Anda berfungsi dan Anda dapat menyusun panggilan API sederhana.

Dasar ini sangat penting untuk berinteraksi secara efektif dengan API Cohere. Ingatlah untuk menjaga kunci Anda aman, memantau penggunaan Anda terhadap batas (terutama pada kunci Uji Coba), dan merujuk ke dokumentasi Cohere untuk informasi rinci tentang model tertentu, parameter lanjutan, dan penggunaan SDK saat Anda mulai membangun aplikasi yang lebih canggih.