Live API - WebSockets API reference

Live API adalah API stateful yang menggunakan WebSockets. Di bagian ini, Anda akan menemukan detail tambahan terkait WebSockets API.

Sesi

Koneksi WebSocket membuat sesi antara klien dan server Gemini. Setelah klien memulai koneksi baru, sesi dapat bertukar pesan dengan server untuk:

  • Mengirim teks, audio, atau video ke server Gemini.
  • Menerima permintaan panggilan audio, teks, atau fungsi dari server Gemini.

Koneksi WebSocket

Untuk memulai sesi, hubungkan ke endpoint websocket ini:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

Konfigurasi sesi

Pesan awal setelah koneksi menetapkan konfigurasi sesi, yang mencakup model, parameter pembuatan, petunjuk sistem, dan alat.

Anda dapat mengubah parameter konfigurasi kecuali model selama sesi.

Lihat contoh konfigurasi berikut. Perhatikan bahwa casing nama di SDK dapat bervariasi. Anda dapat mencari opsi konfigurasi Python SDK di sini.


{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object,
    "mediaResolution": object
  },
  "systemInstruction": string,
  "tools": [object]
}

Untuk informasi selengkapnya tentang kolom API, lihat generationConfig.

Mengirim pesan

Untuk bertukar pesan melalui koneksi WebSocket, klien harus mengirim objek JSON melalui koneksi WebSocket yang terbuka. Objek JSON harus memiliki tepat satu kolom dari kumpulan objek berikut:


{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Pesan klien yang didukung

Lihat pesan klien yang didukung dalam tabel berikut:

Pesan Deskripsi
BidiGenerateContentSetup Konfigurasi sesi yang akan dikirim dalam pesan pertama
BidiGenerateContentClientContent Pembaruan konten inkremental dari percakapan saat ini yang dikirim dari klien
BidiGenerateContentRealtimeInput Input audio, video, atau teks real time
BidiGenerateContentToolResponse Respons terhadap ToolCallMessage yang diterima dari server

Menerima pesan

Untuk menerima pesan dari Gemini, dengarkan peristiwa 'pesan' WebSocket, lalu uraikan hasilnya sesuai dengan definisi pesan server yang didukung.

Lihat referensi berikut:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

Pesan server mungkin memiliki kolom usageMetadata, tetapi akan menyertakan tepat satu kolom lain dari pesan BidiGenerateContentServerMessage. (Gabungan messageType tidak dinyatakan dalam JSON sehingga kolom akan muncul di tingkat teratas pesan.)

Pesan dan peristiwa

ActivityEnd

Jenis ini tidak memiliki kolom.

Menandai akhir aktivitas pengguna.

ActivityHandling

Berbagai cara untuk menangani aktivitas pengguna.

Enum
ACTIVITY_HANDLING_UNSPECIFIED Jika tidak ditentukan, perilaku default-nya adalah START_OF_ACTIVITY_INTERRUPTS.
START_OF_ACTIVITY_INTERRUPTS Jika true (benar), awal aktivitas akan mengganggu respons model (juga disebut "barge in"). Respons model saat ini akan terputus pada saat gangguan. Ini merupakan perilaku default.
NO_INTERRUPTION Respons model tidak akan terganggu.

ActivityStart

Jenis ini tidak memiliki kolom.

Menandai awal aktivitas pengguna.

AudioTranscriptionConfig

Jenis ini tidak memiliki kolom.

Konfigurasi transkripsi audio.

AutomaticActivityDetection

Mengonfigurasi deteksi aktivitas otomatis.

Kolom
disabled

bool

Opsional. Jika diaktifkan (default), input suara dan teks yang terdeteksi akan dihitung sebagai aktivitas. Jika dinonaktifkan, klien harus mengirim sinyal aktivitas.
startOfSpeechSensitivity

StartSensitivity

Opsional. Menentukan kemungkinan ucapan terdeteksi.
prefixPaddingMs

int32

Opsional. Durasi ucapan yang terdeteksi yang diperlukan sebelum awal ucapan di-commit. Makin rendah nilai ini, makin sensitif deteksi awal ucapan dan ucapan yang lebih pendek dapat dikenali. Namun, hal ini juga meningkatkan kemungkinan positif palsu.
endOfSpeechSensitivity

EndSensitivity

Opsional. Menentukan kemungkinan ucapan yang terdeteksi berakhir.
silenceDurationMs

int32

Opsional. Durasi yang diperlukan untuk non-ucapan yang terdeteksi (misalnya, keheningan) sebelum akhir ucapan dilakukan. Makin besar nilai ini, makin lama jeda ucapan tanpa mengganggu aktivitas pengguna, tetapi hal ini akan meningkatkan latensi model.

BidiGenerateContentClientContent

Pembaruan inkremental dari percakapan saat ini yang dikirim dari klien. Semua konten di sini ditambahkan tanpa syarat ke histori percakapan dan digunakan sebagai bagian dari perintah ke model untuk membuat konten.

Pesan di sini akan mengganggu pembuatan model saat ini.

Kolom
turns[]

Content

Opsional. Konten yang ditambahkan ke percakapan saat ini dengan model.

Untuk kueri satu giliran, ini adalah satu instance. Untuk kueri multi-giliran, ini adalah kolom berulang yang berisi histori percakapan dan permintaan terbaru.
turnComplete

bool

Opsional. Jika benar, menunjukkan bahwa pembuatan konten server harus dimulai dengan perintah yang saat ini diakumulasikan. Jika tidak, server akan menunggu pesan tambahan sebelum memulai pembuatan.

BidiGenerateContentRealtimeInput

Input pengguna yang dikirim secara real time.

Berbagai modalitas (audio, video, dan teks) ditangani sebagai streaming serentak. Pengurutan di seluruh aliran ini tidak dijamin.

Dalam beberapa hal, hal ini berbeda dengan BidiGenerateContentClientContent:

  • Dapat dikirim secara terus-menerus tanpa gangguan pada pembuatan model.
  • Jika perlu mencampur data yang diselingi di seluruh BidiGenerateContentClientContent dan BidiGenerateContentRealtimeInput, server akan mencoba mengoptimalkan respons terbaik, tetapi tidak ada jaminan.
  • Akhir giliran tidak ditentukan secara eksplisit, tetapi berasal dari aktivitas pengguna (misalnya, akhir ucapan).
  • Bahkan sebelum akhir giliran, data diproses secara bertahap untuk mengoptimalkan awal respons yang cepat dari model.
Kolom
mediaChunks[]

Blob

Opsional. Data byte yang disisipkan untuk input media. Beberapa mediaChunks tidak didukung, semua kecuali yang pertama akan diabaikan.

TIDAK DIGUNAKAN LAGI: Sebagai gantinya, gunakan salah satu dari audio, video, atau text.
audio

Blob

Opsional. Ini membentuk streaming input audio real-time.
video

Blob

Opsional. Ini membentuk streaming input video real-time.
activityStart

ActivityStart

Opsional. Menandai awal aktivitas pengguna. Ini hanya dapat dikirim jika deteksi aktivitas otomatis (yaitu sisi server) dinonaktifkan.
activityEnd

ActivityEnd

Opsional. Menandai akhir aktivitas pengguna. Ini hanya dapat dikirim jika deteksi aktivitas otomatis (yaitu sisi server) dinonaktifkan.
audioStreamEnd

bool

Opsional. Menunjukkan bahwa streaming audio telah berakhir, misalnya karena mikrofon dinonaktifkan.

Ini hanya boleh dikirim jika deteksi aktivitas otomatis diaktifkan (yang merupakan setelan default).

Klien dapat membuka kembali streaming dengan mengirim pesan audio.
text

string

Opsional. Ini membentuk aliran input teks real-time.

BidiGenerateContentServerContent

Update server inkremental yang dihasilkan oleh model sebagai respons terhadap pesan klien.

Konten dibuat secepat mungkin, dan bukan secara real time. Klien dapat memilih untuk melakukan buffering dan memutarnya secara real time.

Kolom
generationComplete

bool

Hanya output. Jika true, menunjukkan bahwa model telah selesai dibuat.

Jika model terganggu saat membuat, tidak akan ada pesan 'generation_complete' di giliran yang terganggu, model akan melalui 'interrupted > turn_complete'.

Saat model mengasumsikan pemutaran real-time, akan ada penundaan antara generation_complete dan turn_complete yang disebabkan oleh model yang menunggu pemutaran selesai.
turnComplete

bool

Hanya output. Jika benar, menunjukkan bahwa model telah menyelesaikan giliran. Pembuatan hanya akan dimulai sebagai respons terhadap pesan klien tambahan.
interrupted

bool

Hanya output. Jika benar, menunjukkan bahwa pesan klien telah mengganggu pembuatan model saat ini. Jika klien memutar konten secara real time, ini adalah sinyal yang baik untuk menghentikan dan mengosongkan antrean pemutaran saat ini.
groundingMetadata

GroundingMetadata

Hanya output. Metadata dasar untuk konten yang dihasilkan.
outputTranscription

BidiGenerateContentTranscription

Hanya output. Output transkripsi audio. Transkripsi dikirim secara terpisah dari pesan server lainnya dan tidak ada urutan yang dijamin, terutama tidak antara serverContent dan outputTranscription ini.
modelTurn

Content

Hanya output. Konten yang telah dibuat model sebagai bagian dari percakapan saat ini dengan pengguna.

BidiGenerateContentServerMessage

Pesan respons untuk panggilan BidiGenerateContent.

Kolom
usageMetadata

UsageMetadata

Hanya output. Metadata penggunaan tentang respons.
Kolom union messageType. Jenis pesan. messageType hanya dapat berupa salah satu dari berikut:
setupComplete

BidiGenerateContentSetupComplete

Hanya output. Dikirim sebagai respons terhadap pesan BidiGenerateContentSetup dari klien saat penyiapan selesai.
serverContent

BidiGenerateContentServerContent

Hanya output. Konten yang dihasilkan oleh model sebagai respons terhadap pesan klien.
toolCall

BidiGenerateContentToolCall

Hanya output. Minta klien untuk menjalankan functionCalls dan menampilkan respons dengan id yang cocok.
toolCallCancellation

BidiGenerateContentToolCallCancellation

Hanya output. Notifikasi untuk klien bahwa ToolCallMessage yang dikeluarkan sebelumnya dengan id yang ditentukan harus dibatalkan.
goAway

GoAway

Hanya output. Pemberitahuan bahwa server akan segera terputus.
sessionResumptionUpdate

SessionResumptionUpdate

Hanya output. Pembaruan status kelanjutan sesi.

BidiGenerateContentSetup

Pesan yang akan dikirim di BidiGenerateContentClientMessage pertama (dan hanya di BidiGenerateContentClientMessage pertama). Berisi konfigurasi yang akan berlaku selama durasi RPC streaming.

Klien harus menunggu pesan BidiGenerateContentSetupComplete sebelum mengirim pesan tambahan.

Kolom
model

string

Wajib. Nama resource model. ID ini berfungsi sebagai ID yang akan digunakan Model.

Format: models/{model}
generationConfig

GenerationConfig

Opsional. Konfigurasi pembuatan.

Kolom berikut tidak didukung:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
systemInstruction

Content

Opsional. Pengguna memberikan petunjuk sistem untuk model.

Catatan: Hanya teks yang boleh digunakan dalam bagian dan konten di setiap bagian akan berada dalam paragraf terpisah.
tools[]

Tool

Opsional. Daftar Tools yang dapat digunakan model untuk menghasilkan respons berikutnya.

Tool adalah potongan kode yang memungkinkan sistem berinteraksi dengan sistem eksternal untuk melakukan tindakan, atau serangkaian tindakan, di luar pengetahuan dan cakupan model.
realtimeInputConfig

RealtimeInputConfig

Opsional. Mengonfigurasi penanganan input realtime.
sessionResumption

SessionResumptionConfig

Opsional. Mengonfigurasi mekanisme melanjutkan sesi.

Jika disertakan, server akan mengirim pesan SessionResumptionUpdate.
contextWindowCompression

ContextWindowCompressionConfig

Opsional. Mengonfigurasi mekanisme kompresi jendela konteks.

Jika disertakan, server akan otomatis mengurangi ukuran konteks jika melebihi panjang yang dikonfigurasi.
outputAudioTranscription

AudioTranscriptionConfig

Opsional. Jika ditetapkan, akan mengaktifkan transkripsi output audio model. Transkripsi akan sesuai dengan kode bahasa yang ditentukan untuk audio output, jika dikonfigurasi.

BidiGenerateContentSetupComplete

Jenis ini tidak memiliki kolom.

Dikirim sebagai respons terhadap pesan BidiGenerateContentSetup dari klien.

BidiGenerateContentToolCall

Minta klien untuk menjalankan functionCalls dan menampilkan respons dengan id yang cocok.

Kolom
functionCalls[]

FunctionCall

Hanya output. Panggilan fungsi yang akan dieksekusi.

BidiGenerateContentToolCallCancellation

Notifikasi untuk klien bahwa ToolCallMessage yang dikeluarkan sebelumnya dengan id yang ditentukan seharusnya tidak dieksekusi dan harus dibatalkan. Jika ada efek samping pada panggilan alat tersebut, klien dapat mencoba mengurungkan panggilan alat. Pesan ini hanya terjadi jika klien mengganggu giliran server.

Kolom
ids[]

string

Hanya output. ID panggilan alat yang akan dibatalkan.

BidiGenerateContentToolResponse

Respons yang dibuat klien untuk ToolCall yang diterima dari server. Setiap objek FunctionResponse dicocokkan dengan objek FunctionCall masing-masing oleh kolom id.

Perhatikan bahwa dalam panggilan fungsi GenerateContent API streaming server dan unary terjadi dengan bertukar bagian Content, sedangkan dalam panggilan fungsi GenerateContent API bidi terjadi melalui kumpulan pesan khusus ini.

Kolom
functionResponses[]

FunctionResponse

Opsional. Respons terhadap panggilan fungsi.

BidiGenerateContentTranscription

Transkripsi audio (input atau output).

Kolom
text

string

Teks transkripsi.

ContextWindowCompressionConfig

Mengaktifkan kompresi jendela konteks — mekanisme untuk mengelola jendela konteks model agar tidak melebihi durasi tertentu.

Kolom
Kolom union compressionMechanism. Mekanisme kompresi jendela konteks yang digunakan. compressionMechanism hanya dapat berupa salah satu dari berikut:
slidingWindow

SlidingWindow

Mekanisme jendela geser.
triggerTokens

int64

Jumlah token (sebelum menjalankan giliran) yang diperlukan untuk memicu kompresi jendela konteks.

Hal ini dapat digunakan untuk menyeimbangkan kualitas dengan latensi karena periode konteks yang lebih singkat dapat menghasilkan respons model yang lebih cepat. Namun, setiap operasi kompresi akan menyebabkan peningkatan latensi sementara, sehingga tidak boleh sering dipicu.

Jika tidak ditetapkan, defaultnya adalah 80% dari batas jendela konteks model. Hal ini menyisakan 20% untuk permintaan pengguna/respons model berikutnya.

EndSensitivity

Menentukan cara akhir ucapan terdeteksi.

Enum
END_SENSITIVITY_UNSPECIFIED Setelan defaultnya adalah END_SENSITIVITY_HIGH.
END_SENSITIVITY_HIGH Deteksi otomatis lebih sering mengakhiri ucapan.
END_SENSITIVITY_LOW Deteksi otomatis lebih jarang mengakhiri ucapan.

GoAway

Pemberitahuan bahwa server akan segera terputus.

Kolom
timeLeft

Duration

Waktu yang tersisa sebelum koneksi akan dihentikan sebagai ABORTED.

Durasi ini tidak akan pernah kurang dari minimum khusus model, yang akan ditentukan bersama dengan batas kapasitas untuk model.

RealtimeInputConfig

Mengonfigurasi perilaku input realtime di BidiGenerateContent.

Kolom
automaticActivityDetection

AutomaticActivityDetection

Opsional. Jika tidak ditetapkan, deteksi aktivitas otomatis diaktifkan secara default. Jika deteksi suara otomatis dinonaktifkan, klien harus mengirim sinyal aktivitas.
activityHandling

ActivityHandling

Opsional. Menentukan efek aktivitas.
turnCoverage

TurnCoverage

Opsional. Menentukan input yang disertakan dalam giliran pengguna.

SessionResumptionConfig

Konfigurasi kelanjutan sesi.

Pesan ini disertakan dalam konfigurasi sesi sebagai BidiGenerateContentSetup.sessionResumption. Jika dikonfigurasi, server akan mengirim pesan SessionResumptionUpdate.

Kolom
handle

string

Nama sebutan sesi sebelumnya. Jika tidak ada, sesi baru akan dibuat.

ID sesi berasal dari nilai SessionResumptionUpdate.token dalam koneksi sebelumnya.

SessionResumptionUpdate

Pembaruan status kelanjutan sesi.

Hanya dikirim jika BidiGenerateContentSetup.sessionResumption ditetapkan.

Kolom
newHandle

string

Nama sebutan channel baru yang mewakili status yang dapat dilanjutkan. Kosong jika resumable=salah.
resumable

bool

Benar jika sesi saat ini dapat dilanjutkan pada tahap ini.

Lanjutan tidak dapat dilakukan pada beberapa titik dalam sesi. Misalnya, saat model mengeksekusi panggilan fungsi atau membuat. Melanjutkan sesi (menggunakan token sesi sebelumnya) dalam status tersebut akan mengakibatkan beberapa data hilang. Dalam kasus ini, newHandle akan kosong dan resumable akan bernilai salah.

SlidingWindow

Metode SlidingWindow beroperasi dengan menghapus konten di awal jendela konteks. Konteks yang dihasilkan akan selalu dimulai di awal giliran peran PENGGUNA. Petunjuk sistem dan BidiGenerateContentSetup.prefixTurns apa pun akan selalu tetap berada di awal hasil.

Kolom
targetTokens

int64

Target jumlah token yang akan disimpan. Nilai defaultnya adalah trigger_tokens/2.

Menghapus bagian jendela konteks menyebabkan peningkatan latensi sementara sehingga nilai ini harus dikalibrasi untuk menghindari operasi kompresi yang sering terjadi.

StartSensitivity

Menentukan cara awal ucapan terdeteksi.

Enum
START_SENSITIVITY_UNSPECIFIED Setelan defaultnya adalah START_SENSITIVITY_HIGH.
START_SENSITIVITY_HIGH Deteksi otomatis akan lebih sering mendeteksi awal ucapan.
START_SENSITIVITY_LOW Deteksi otomatis akan mendeteksi awal ucapan lebih jarang.

TurnCoverage

Opsi tentang input mana yang disertakan dalam giliran pengguna.

Enum
TURN_COVERAGE_UNSPECIFIED Jika tidak ditentukan, perilaku default-nya adalah TURN_INCLUDES_ONLY_ACTIVITY.
TURN_INCLUDES_ONLY_ACTIVITY Giliran pengguna hanya mencakup aktivitas sejak giliran terakhir, tidak termasuk ketidakaktifan (misalnya, keheningan pada streaming audio). Ini merupakan perilaku default.
TURN_INCLUDES_ALL_INPUT Giliran pengguna mencakup semua input realtime sejak giliran terakhir, termasuk ketidakaktifan (misalnya, keheningan pada streaming audio).

UsageMetadata

Metadata penggunaan tentang respons.

Kolom
promptTokenCount

int32

Hanya output. Jumlah token dalam perintah. Saat cachedContent ditetapkan, ini masih merupakan total ukuran perintah yang efektif, yang berarti mencakup jumlah token dalam konten yang di-cache.
cachedContentTokenCount

int32

Jumlah token di bagian perintah yang di-cache (konten yang di-cache)
responseTokenCount

int32

Hanya output. Jumlah total token di semua kandidat respons yang dihasilkan.
toolUsePromptTokenCount

int32

Hanya output. Jumlah token yang ada dalam perintah penggunaan alat.
thoughtsTokenCount

int32

Hanya output. Jumlah token pemikiran untuk model pemikiran.
totalTokenCount

int32

Hanya output. Jumlah total token untuk permintaan pembuatan (kandidat perintah + respons).
promptTokensDetails[]

ModalityTokenCount

Hanya output. Daftar modalitas yang diproses dalam input permintaan.
cacheTokensDetails[]

ModalityTokenCount

Hanya output. Daftar modalitas konten yang di-cache dalam input permintaan.
responseTokensDetails[]

ModalityTokenCount

Hanya output. Daftar modalitas yang ditampilkan dalam respons.
toolUsePromptTokensDetails[]

ModalityTokenCount

Hanya output. Daftar modalitas yang diproses untuk input permintaan penggunaan alat.

Informasi selengkapnya tentang jenis umum

Untuk informasi selengkapnya tentang jenis resource API yang umum digunakan Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, ModalityTokenCount, dan Tool, lihat Membuat konten.