Panduan inti
Membangun integrasi TokenLab yang andal
Kendalikan biaya, percobaan ulang (retries), kunci API, dan catatan permintaan
Integrasi yang baik membuat pilihan harga dan model terlihat jelas, mampu bertahan dari kegagalan jaringan biasa, dan tidak pernah mengekspos kunci API di browser. Praktik-praktik di bawah ini berlaku untuk chat, gambar, video, audio, dan API TokenLab lainnya.
Pilih model dengan data terkini
Nama, kapabilitas, dan harga model dapat berubah. Bacalah Models API atau halaman model alih-alih menyimpan daftar permanen dalam kode atau dokumentasi.
Untuk kasus penggunaan baru:
- Filter model berdasarkan kapabilitas yang dibutuhkan produk Anda.
- Bandingkan harga TokenLab mereka saat ini.
- Uji sekumpulan kecil dengan permintaan pengguna yang representatif.
- Pastikan ID model eksplisit dalam setiap permintaan.
Jangan mengganti model secara diam-diam. Penggantian dapat mengubah kualitas output, harga, panjang konteks, alat yang tersedia, atau dukungan media.
Tetapkan batas atas biaya
Untuk model teks, batasi output sesuai panjang yang benar-benar dapat digunakan oleh produk Anda. Nama parameter bergantung pada API dan model, jadi periksa halaman model sebelum mengirim max_tokens atau max_output_tokens.
Instruksi yang lebih pendek tidak otomatis lebih baik, tetapi konteks yang diduplikasi dan boilerplate yang diulang selalu menambah token input. Buat instruksi yang stabil tetap ringkas dan kirimkan hanya riwayat yang diperlukan untuk jawaban berikutnya.
Untuk permintaan gambar, video, musik, 3D, dan Worlds, biaya sering kali bergantung pada jumlah output, durasi, resolusi, atau opsi media lainnya. Tampilkan estimasi saat ini sebelum pengguna mengonfirmasi pembuatan yang mahal kapan pun API dapat menyediakannya.
Streaming respons teks panjang
Streaming menampilkan jawaban saat tiba dan menghindari pengguna menunggu respons lengkap. Ini tidak mengurangi biaya token.
Untuk contoh lengkap dengan pengaturan klien dan pemeriksaan penyelesaian, lihat Streaming.
Tangani pemutusan koneksi sebagai jawaban yang tidak lengkap. Jangan menyajikan output parsial sebagai sesuatu yang sudah selesai dengan sukses, dan jangan mengulangi permintaan secara otomatis jika hal tersebut dapat menimbulkan efek samping atau biaya kedua.
Lakukan percobaan ulang (retry) hanya jika aman
Lakukan percobaan ulang pada respons 429 setelah Retry-After atau retry_after. Exponential backoff singkat sangat tepat untuk respons 5xx yang bersifat sementara. Kesalahan autentikasi, validasi, saldo, dan panjang konteks memerlukan perubahan dari aplikasi atau pengguna; mengirimkan permintaan yang sama lagi tidak akan memperbaikinya.
Lihat Batas laju (Rate limits) untuk contoh percobaan ulang terbatas yang mematuhi Retry-After dan menonaktifkan percobaan ulang SDK duplikat.
Tetapkan batas percobaan ulang dan batas waktu total. Untuk pembuatan media, simpan ID tugas yang dikembalikan. Untuk permintaan yang tercantum dalam Retry safely with an idempotency key, kirimkan Idempotency-Key, sehingga percobaan ulang setelah timeout tidak dapat menjalankan atau menagih permintaan yang sama dua kali.
Simpan kunci API di server
Jangan pernah menyematkan kunci API TokenLab di JavaScript browser, bundel aplikasi seluler, repositori publik, atau log yang terlihat oleh klien.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
)Gunakan kunci API terpisah untuk pengembangan, produksi, dan aplikasi independen. Berikan setiap kunci hanya model dan batas pengeluaran yang dibutuhkannya. Cabut kunci segera jika kunci tersebut mungkin telah terekspos.
Simpan catatan permintaan yang berguna
Simpan pengenal yang memungkinkan Anda menghubungkan tindakan pengguna ke catatan penggunaan dan dukungan:
request_iduntuk permintaan APItask_iduntuk pembuatan asinkronbilling_transaction_idsaat dikembalikan- ID model dan endpoint
- ID pengguna, proyek, atau pekerjaan Anda sendiri
Jangan mencatat kunci API, token manajemen, prompt pribadi lengkap, media pribadi, atau URL yang ditandatangani. Catatan penggunaan di Console dan Management API adalah sumber untuk jumlah yang ditagih; jumlah token respons model saja mungkin tidak menggambarkan biaya akhir.
Rancang untuk pekerjaan asinkron
API gambar, video, musik, 3D, dan Worlds mungkin kembali sebelum hasilnya siap. Simpan ID tugas, lakukan polling pada GET /v1/tasks/{id}, dan berhenti hanya pada status completed atau failed. Pencarian status gagal tidak berarti pembuatan itu sendiri gagal.
Lihat Async jobs and polling untuk penanganan pembatalan, timeout, dan permintaan duplikat.
Sebelum peluncuran
- Jalankan permintaan representatif dengan model dan format API yang tepat yang akan Anda rilis.
- Periksa respons sukses maupun respons kesalahan umum.
- Konfirmasi bahwa harga yang ditampilkan di produk Anda sesuai dengan harga TokenLab saat ini.
- Pastikan penyegaran, timeout jaringan, dan klik berulang aman.
- Pastikan Anda dapat melacak hasil yang terlihat oleh pengguna kembali ke Request ID-nya.