Suara dan katalog

GET /v1/chat/catalog mencantumkan model publik, suara, dan harga kredit saat ini. Obrolan teks menggunakan POST /v1/chat/completions; pidato menggunakan titik akhir di bawah ini.

Model dan harga

Katalog model langsung · harga kredit

Memuat katalog model…

Pidato ke teks

POST /v1/chat/transcribe menerima { "audio": "data:audio/webm;base64,..." }. Base64 biasa juga didukung, hingga 10MB didekodekan. Mengembalikan text dan language.

Teks ke ucapan

Katalog model langsung · harga kredit

Memuat katalog model…

Perluas model untuk melihat suaranya yang diaktifkan. Administrator dapat mengubah nama dan deskripsi suara. Suara yang dinonaktifkan dihilangkan dari katalog dan tidak dapat digunakan untuk permintaan sintesis baru; segarkan halaman ini untuk melihat pengaturan saat ini. Menonaktifkan model juga menghapus semua suaranya dari dokumentasi dan daftar suara katalog serta menolak permintaan sintesis baru. Mengaktifkan kembali model akan mempertahankan pengaturan suara individual. Jika suara default atau modelnya dinonaktifkan, suara yang diaktifkan dari model lain yang diaktifkan akan dipilih.

POST /v1/chat/speech menerima { "text": "Hello", "voice": "speech-light:af_bella" } (hingga 2.000 karakter). Hilangkan voice untuk default yang dikonfigurasi. Gunakan voices[].id dari katalog; modelId mengidentifikasi model dan kecepatan ucapannya. Keluarga: Pidato Standar, Pidato Ringan, Pidato Pro, dan Pidato Ekspresif. Model ucapan dan obrolan bersifat independen.

Responsnya meliputi audio (URI data MP3, data:audio/mpeg;base64,...), voice dan billing: { model, credits, characters, price, unit: "1000_characters" }. Semua suara, termasuk Speech Pro, menghasilkan MP3. Tetapkan audio ke src elemen audio, atau dekode base64 setelah koma dan simpan sebagai .mp3. Speech Pro tidak memerlukan konversi sisi klien; ID suara dan harga berdasarkan karakter tidak berubah. Lihat contoh Python yang dapat dijalankan.

Streaming pidato

Kirim "stream": true ke titik akhir POST /v1/chat/speech yang sama. Pidato Standar, Pidato Ringan, Pidato Pro, dan Pidato Ekspresif mendukung streaming; katalog memperlihatkan speechModels[].streaming. Menghilangkan stream, atau menyetelnya ke false, akan mempertahankan respons JSON di atas.

{ "text": "Hello. How was your day?", "voice": "speech-pro:Ashley", "stream": true }

Responsnya adalah aliran biner MP3 berkelanjutan dengan Content-Type: audio/mpeg, bukan JSON, base64, atau SSE. Proxy meneruskan audio yang diterima; Speech Pro dikonversi secara bertahap ke MP3. Hal ini tidak menjamin latensi pembuatan model. Teks dikirim sebagai satu permintaan, tanpa pemisahan kalimat otomatis.

Dengan curl dan FFmpeg terinstal, contoh ini memutar audio saat tiba:

curl --fail --no-buffer https://api.coldstart.win/v1/chat/speech \
  -H "Authorization: Bearer $COLDSTART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello. How was your day?","voice":"speech-pro:Ashley","stream":true}' \
  | ffplay -nodisp -autoexit -f mp3 -i pipe:0

Untuk klien panggilan suara, gunakan isi respons secara bertahap dan masukkan dekoder/pemutar MP3 yang persisten. Di browser, gunakan response.body.getReader() dengan implementasi pemutaran streaming; response.blob(), arrayBuffer() dan json() menunggu seluruh respons. Potongan jaringan adalah rentang byte yang berubah-ubah, bukan file MP3 yang berdiri sendiri. Batalkan pengambilan/pembaca ketika pengguna menyela atau menutup telepon. Pemutaran browser masih memerlukan interaksi pengguna biasa untuk membuka kunci audio.

Header respons menampilkan X-Speech-Voice (ID suara publik yang dikodekan URL), X-Speech-Credits, X-Speech-Characters, dan X-Speech-Usage-Id. Jumlah kredit adalah debit awal; permintaan yang diselesaikan menggunakan harga berbasis karakter yang sama dengan permintaan non-streaming. Streaming yang gagal atau pemutusan koneksi sebelum server menyelesaikan pemrosesan akan mengembalikan dana permintaan dan mencatat penggunaan yang gagal. Pembatalan setelah server selesai tidak membatalkan tagihan yang berhasil.

Sebelum audio dimulai, kesalahan menggunakan status HTTP normal dan isi kesalahan JSON. Setelah audio dimulai, kegagalan tiba-tiba menutup koneksi; buang keluaran yang tidak lengkap dan periksa Riwayat tugas untuk hasil penagihan akhir. Jangan perlakukan HTTP 200 atau menerima potongan pertama sebagai bukti keberhasilan penyelesaian. Proksi tambahan harus menonaktifkan buffering dan kompresi respons untuk rute ini; API mengirimkan X-Accel-Buffering: no dan Cache-Control: no-store, no-transform.

Jika teks ucapan secara eksplisit ditolak oleh kebijakan konten, kedua mode respons akan menampilkan HTTP 400 dengan kode kesalahan content_policy_violation sebelum audio dimulai. Biaya tersebut dikembalikan. Jangan mencoba ulang teks yang sama secara otomatis; merevisinya untuk mematuhi kebijakan konten. Dukungan streaming tidak menghilangkan batasan konten.

Permintaan ucapan bersifat independen; secara eksplisit meneruskan ID suara publik yang diinginkan. Speech JSON berisi URI data audio dan penagihan; streaming mengembalikan byte audio.

Kredit ucapan = jumlah karakter teks yang dapat ditagih yang dinormalisasi × harga model / 1.000, dibulatkan ke atas menjadi 8 tempat desimal. Speech Light, Speech Pro, dan Speech Expressive menghitung unit kode UTF-16, sesuai dengan model yang dipilih: karakter China/Inggris biasa dihitung sebagai satu, dan karakter tambahan seperti 😀 dihitung sebagai dua. Standar Pidato menggunakan poin kode Unicode. speechModels[].characterCounting pada katalog dan billing.character_counting pada respons mengidentifikasi aturan penghitungan (utf16_code_units atau unicode_codepoints); billing.characters adalah jumlah yang ditagih. Pemformatan dan arahan tahapan dihapus sebelum sintesis dan penghitungan. Sintesis yang gagal atau kosong dikembalikan. Setiap permintaan sintesis ditagih; memutar ulang audio yang dikembalikan tidak memerlukan biaya apa pun. Konsol menyimpan cache audio melalui pesan dan suara untuk sesi halaman saat ini.