Live API - WebSockets API reference

Live API는 WebSockets를 사용하는 스테이트풀(Stateful) API입니다. 이 섹션에서는 WebSocket API에 관한 추가 세부정보를 확인할 수 있습니다.

세션

WebSocket 연결은 클라이언트와 Gemini 서버 간에 세션을 설정합니다. 클라이언트가 새 연결을 시작한 후 세션에서 서버와 메시지를 교환하여 다음 작업을 실행할 수 있습니다.

텍스트, 오디오 또는 동영상을 Gemini 서버로 전송합니다.
Gemini 서버로부터 오디오, 텍스트 또는 함수 호출 요청을 수신합니다.

WebSocket 연결

세션을 시작하려면 다음 WebSocket 엔드포인트에 연결하세요.

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

세션 구성

WebSocket 연결을 설정한 후 전송되는 초기 메시지는 모델, 생성 파라미터, 시스템 안내, 도구를 포함하는 세션 구성을 설정합니다.

연결이 열려 있는 동안에는 구성을 업데이트할 수 없습니다. 하지만 세션 재개 메커니즘을 통해 일시중지하고 재개할 때는 모델을 제외한 구성 매개변수를 변경할 수 있습니다.

다음 구성 예시를 참고하세요. SDK의 이름 대소문자는 다를 수 있습니다. Python SDK 구성 옵션은 여기에서 확인할 수 있습니다.


{
  "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]
}

API 필드에 대한 자세한 내용은 generationConfig를 참고하세요.

메시지 보내기

WebSocket 연결을 통해 메시지를 교환하려면 클라이언트가 열린 WebSocket 연결을 통해 JSON 객체를 전송해야 합니다. JSON 객체는 다음 객체 세트의 필드 중 정확히 하나를 포함해야 합니다.


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

지원되는 클라이언트 메시지

지원되는 클라이언트 메시지는 다음 표를 참고하세요.

메시지	설명
`BidiGenerateContentSetup`	첫 번째 메시지에서 전송될 세션 구성
`BidiGenerateContentClientContent`	클라이언트에서 전송된 현재 대화의 증분 콘텐츠 업데이트
`BidiGenerateContentRealtimeInput`	실시간 오디오, 동영상 또는 텍스트 입력
`BidiGenerateContentToolResponse`	서버에서 수신한 `ToolCallMessage`에 대한 응답

메시지 수신

Gemini로부터 메시지를 수신하려면 WebSocket 'message' 이벤트를 수신한 다음 지원되는 서버 메시지의 정의에 따라 결과를 파싱합니다.

다음을 참조하세요.

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)

서버 메시지에는 usageMetadata 필드가 있을 수 있지만, 그 외에는 BidiGenerateContentServerMessage 메시지의 다른 필드 중 정확히 하나가 포함됩니다. (messageType 유니온은 JSON으로 표현되지 않으므로 필드가 메시지의 최상위 수준에 표시됩니다.)

메시지 및 이벤트

ActivityEnd

이 유형에는 필드가 없습니다.

사용자 활동의 종료를 표시합니다.

ActivityHandling

사용자 활동을 처리하는 다양한 방법입니다.

열거형
`ACTIVITY_HANDLING_UNSPECIFIED`	지정되지 않은 경우 기본 동작은 `START_OF_ACTIVITY_INTERRUPTS`입니다.
`START_OF_ACTIVITY_INTERRUPTS`	true인 경우 활동 시작이 모델의 응답을 중단시킵니다('끼어들기'라고도 함). 중단되는 순간 모델의 현재 응답이 잘립니다. 기본 동작으로 설정되어 있습니다.
`NO_INTERRUPTION`	모델의 응답이 중단되지 않습니다.

ActivityStart

이 유형에는 필드가 없습니다.

사용자 활동의 시작을 표시합니다.

AudioTranscriptionConfig

이 유형에는 필드가 없습니다.

오디오 스크립트 작성 구성입니다.

AutomaticActivityDetection

활동 자동 감지를 구성합니다.

필드
`disabled`	`bool` 선택사항입니다. 사용 설정된 경우 (기본값) 감지된 음성 및 텍스트 입력이 활동으로 간주됩니다. 사용 중지된 경우 클라이언트는 활동 신호를 전송해야 합니다.
`startOfSpeechSensitivity`	`StartSensitivity` 선택사항입니다. 음성이 감지될 가능성을 결정합니다.
`prefixPaddingMs`	`int32` 선택사항입니다. 음성 시작이 커밋되기 전 감지된 음성의 필수 지속 시간입니다. 이 값이 낮을수록 음성 시작 감도가 높아지고 더 짧은 음성을 인식할 수 있습니다. 하지만 이렇게 하면 거짓양성이 발생할 가능성도 높아집니다.
`endOfSpeechSensitivity`	`EndSensitivity` 선택사항입니다. 감지된 음성이 종료되었을 가능성을 결정합니다.
`silenceDurationMs`	`int32` 선택사항입니다. 음성 종료가 커밋되기 전 감지된 비음성 (예: 무음)의 필수 지속 시간입니다. 이 값이 클수록 사용자 활동을 방해하지 않고도 음성 간격을 더 길게 할 수 있지만 모델의 지연 시간이 늘어납니다.

BidiGenerateContentClientContent

클라이언트에서 전송된 현재 대화의 증분 업데이트입니다. 여기에 있는 모든 콘텐츠는 무조건 대화 기록에 추가되며 콘텐츠를 생성하기 위한 모델의 프롬프트 일부로 사용됩니다.

여기에 메시지를 입력하면 현재 모델 생성이 중단됩니다.

필드

필드
`turns[]`	`Content` (선택사항) 모델과의 현재 대화에 추가된 콘텐츠입니다. 싱글턴 쿼리의 경우 이는 단일 인스턴스입니다. 멀티턴 쿼리의 경우 이는 대화 기록과 최근 요청이 포함된 반복 필드입니다.
`turnComplete`	`bool` 선택사항입니다. true인 경우 서버 콘텐츠 생성이 현재 누적된 프롬프트로 시작해야 함을 나타냅니다. 그렇지 않으면 서버는 생성을 시작하기 전에 추가 메시지를 기다립니다.

turns[]

Content

(선택사항) 모델과의 현재 대화에 추가된 콘텐츠입니다.

싱글턴 쿼리의 경우 이는 단일 인스턴스입니다. 멀티턴 쿼리의 경우 이는 대화 기록과 최근 요청이 포함된 반복 필드입니다.

turnComplete

bool

선택사항입니다. true인 경우 서버 콘텐츠 생성이 현재 누적된 프롬프트로 시작해야 함을 나타냅니다. 그렇지 않으면 서버는 생성을 시작하기 전에 추가 메시지를 기다립니다.

BidiGenerateContentRealtimeInput

실시간으로 전송되는 사용자 입력입니다.

다양한 형식 (오디오, 동영상, 텍스트)은 동시 스트림으로 처리됩니다. 이러한 스트림 간의 순서는 보장되지 않습니다.

이는 몇 가지 점에서 BidiGenerateContentClientContent와 다릅니다.

모델 생성에 중단 없이 계속 전송할 수 있습니다.
BidiGenerateContentClientContent와 BidiGenerateContentRealtimeInput에서 인터리브 처리된 데이터를 혼합해야 하는 경우 서버는 최적의 응답을 위해 최적화하려고 시도하지만 보장되지는 않습니다.
차례 종료는 명시적으로 지정되지 않으며 대신 사용자 활동(예: 음성 종료)에서 파생됩니다.
차례가 끝나기 전에도 모델의 응답을 빠르게 시작할 수 있도록 데이터가 점진적으로 처리됩니다.

필드
`mediaChunks[]`	`Blob` (선택사항) 미디어 입력을 위한 인라인 바이트 데이터입니다. 여러 `mediaChunks`는 지원되지 않으며 첫 번째를 제외한 모든 항목은 무시됩니다. 지원 중단됨: `audio`, `video`, `text` 중 하나를 대신 사용하세요.
`audio`	`Blob` 선택사항입니다. 이러한 입력이 실시간 오디오 입력 스트림을 구성합니다.
`video`	`Blob` 선택사항입니다. 이러한 프레임은 실시간 동영상 입력 스트림을 구성합니다.
`activityStart`	`ActivityStart` 선택사항입니다. 사용자 활동의 시작을 표시합니다. 자동(즉, 서버 측) 활동 감지가 사용 중지된 경우에만 전송할 수 있습니다.
`activityEnd`	`ActivityEnd` (선택사항) 사용자 활동의 종료를 표시합니다. 자동(즉, 서버 측) 활동 감지가 사용 중지된 경우에만 전송할 수 있습니다.
`audioStreamEnd`	`bool` 선택사항입니다. 마이크가 꺼져 오디오 스트림이 종료되었음을 나타냅니다. 자동 활동 감지가 사용 설정된 경우에만 전송해야 합니다 (기본값). 클라이언트는 오디오 메시지를 전송하여 스트림을 다시 열 수 있습니다.
`text`	`string` 선택사항입니다. 이러한 스트림이 실시간 문자 입력 스트림을 구성합니다.

BidiGenerateContentServerContent

클라이언트 메시지에 대한 응답으로 모델에서 생성된 증분 서버 업데이트입니다.

콘텐츠는 실시간이 아닌 최대한 빨리 생성됩니다. 클라이언트는 버퍼링 및 실시간 재생을 선택할 수 있습니다.

필드
`generationComplete`	`bool` 출력 전용입니다. true인 경우 모델이 생성을 완료했음을 나타냅니다. 생성 중에 모델이 중단되면 중단된 턴에 'generation_complete' 메시지가 표시되지 않으며 'interrupted > turn_complete' 과정을 거칩니다. 모델이 실시간 재생을 가정하면 모델이 재생이 완료되기를 기다리는 동안 generation_complete와 turn_complete 사이에 지연이 발생합니다.
`turnComplete`	`bool` 출력 전용입니다. true인 경우 모델이 턴을 완료했음을 나타냅니다. 생성은 추가 클라이언트 메시지에 대한 응답으로만 시작됩니다.
`interrupted`	`bool` 출력 전용입니다. true인 경우 클라이언트 메시지로 인해 현재 모델 생성이 중단되었음을 나타냅니다. 클라이언트가 콘텐츠를 실시간으로 재생하는 경우 이 신호에 따라 현재 재생 큐를 중지하고 비우는 것이 좋습니다.
`groundingMetadata`	`GroundingMetadata` 출력 전용입니다. 생성된 콘텐츠의 그라운딩 메타데이터입니다.
`inputTranscription`	`BidiGenerateContentTranscription` 출력 전용입니다. 입력 오디오 스크립트 작성입니다. 텍스트 변환은 다른 서버 메시지와 별도로 전송되며 순서가 보장되지 않습니다.
`outputTranscription`	`BidiGenerateContentTranscription` 출력 전용입니다. 오디오 스크립트 작성을 출력합니다. 트랜스크립션은 다른 서버 메시지와 독립적으로 전송되며 순서가 보장되지 않습니다. 특히 `serverContent`와 이 `outputTranscription` 사이에는 순서가 보장되지 않습니다.
`urlContextMetadata`	`UrlContextMetadata`
`modelTurn`	`Content` 출력 전용입니다. 모델이 사용자와의 현재 대화 중에 생성한 콘텐츠입니다.

BidiGenerateContentServerMessage

BidiGenerateContent 호출의 응답 메시지입니다.

필드
`usageMetadata`	`UsageMetadata` 출력 전용입니다. 대답에 관한 사용 메타데이터입니다.
통합 필드 `messageType`. 메시지 유형입니다. `messageType`은 다음 중 하나여야 합니다.
`setupComplete`	`BidiGenerateContentSetupComplete` 출력 전용입니다. 설정이 완료되면 클라이언트의 `BidiGenerateContentSetup` 메시지에 대한 응답으로 전송됩니다.
`serverContent`	`BidiGenerateContentServerContent` 출력 전용입니다. 클라이언트 메시지에 대한 응답으로 모델에서 생성된 콘텐츠입니다.
`toolCall`	`BidiGenerateContentToolCall` 출력 전용입니다. 클라이언트가 `functionCalls`를 실행하고 일치하는 `id`를 가진 응답을 반환하도록 요청합니다.
`toolCallCancellation`	`BidiGenerateContentToolCallCancellation` 출력 전용입니다. 지정된 `id`가 포함된 이전에 발급된 `ToolCallMessage`가 취소되어야 한다는 클라이언트 알림입니다.
`goAway`	`GoAway` 출력 전용입니다. 서버가 곧 연결 해제된다는 알림입니다.
`sessionResumptionUpdate`	`SessionResumptionUpdate` 출력 전용입니다. 세션 재개 상태의 업데이트입니다.

BidiGenerateContentSetup

첫 번째 (및 첫 번째에만) BidiGenerateContentClientMessage에서 전송할 메시지입니다. 스트리밍 RPC 기간에 적용되는 구성을 포함합니다.

클라이언트는 추가 메시지를 보내기 전에 BidiGenerateContentSetupComplete 메시지를 기다려야 합니다.

필드
`model`	`string` 필수 항목입니다. 모델의 리소스 이름입니다. 이는 모델에서 사용할 ID로 사용됩니다. 형식: `models/{model}`
`generationConfig`	`GenerationConfig` 선택사항입니다. 생성 구성 다음 필드는 지원되지 않습니다. `responseLogprobs` `responseMimeType` `logprobs` `responseSchema` `stopSequence` `routingConfig` `audioTimestamp`
`systemInstruction`	`Content` 선택사항입니다. 사용자가 모델의 시스템 지침을 제공했습니다. 참고: 부분에는 텍스트만 사용해야 하며 각 부분의 콘텐츠는 별도의 단락에 위치합니다.
`tools[]`	`Tool` 선택사항입니다. 모델이 다음 응답을 생성하는 데 사용할 수 있는 `Tools` 목록입니다. `Tool`은 시스템이 모델의 지식과 범위를 벗어나 외부 시스템과 상호작용하여 작업 또는 작업 집합을 수행할 수 있도록 하는 코드 조각입니다.
`realtimeInputConfig`	`RealtimeInputConfig` 선택사항입니다. 실시간 입력 처리를 구성합니다.
`sessionResumption`	`SessionResumptionConfig` 선택사항입니다. 세션 재개 메커니즘을 구성합니다. 포함된 경우 서버는 `SessionResumptionUpdate` 메시지를 전송합니다.
`contextWindowCompression`	`ContextWindowCompressionConfig` 선택사항입니다. 컨텍스트 윈도우 압축 메커니즘을 구성합니다. 포함된 경우 서버는 구성된 길이를 초과하면 컨텍스트 크기를 자동으로 줄입니다.
`inputAudioTranscription`	`AudioTranscriptionConfig` 선택사항입니다. 설정된 경우 음성 입력의 스크립트 작성을 사용 설정합니다. 스크립트 작성은 구성된 경우 입력 오디오 언어와 일치합니다.
`outputAudioTranscription`	`AudioTranscriptionConfig` 선택사항입니다. 설정된 경우 모델의 오디오 출력의 스크립트 작성을 사용 설정합니다. 스크립트 작성은 구성된 경우 출력 오디오에 지정된 언어 코드와 일치합니다.
`proactivity`	`ProactivityConfig` 선택사항입니다. 모델의 사전 대응성을 구성합니다. 이를 통해 모델은 입력에 능동적으로 응답하고 관련 없는 입력을 무시할 수 있습니다.

BidiGenerateContentSetupComplete

이 유형에는 필드가 없습니다.

클라이언트의 BidiGenerateContentSetup 메시지에 대한 응답으로 전송됩니다.

BidiGenerateContentToolCall

클라이언트가 functionCalls를 실행하고 일치하는 id를 가진 응답을 반환하도록 요청합니다.

필드

필드
`functionCalls[]`	`FunctionCall` 출력 전용입니다. 실행할 함수 호출입니다.

functionCalls[]

FunctionCall

출력 전용입니다. 실행할 함수 호출입니다.

BidiGenerateContentToolCallCancellation

지정된 id가 포함된 이전에 발급된 ToolCallMessage가 실행되지 않았으며 취소되어야 한다는 클라이언트 알림입니다. 이러한 도구 호출에 부작용이 있는 경우 클라이언트는 도구 호출을 실행취소하려고 시도할 수 있습니다. 이 메시지는 클라이언트가 서버 전환을 중단하는 경우에만 발생합니다.

필드

필드
`ids[]`	`string` 출력 전용입니다. 취소할 도구 호출의 ID입니다.

ids[]

string

출력 전용입니다. 취소할 도구 호출의 ID입니다.

BidiGenerateContentToolResponse

서버에서 수신한 ToolCall에 대한 클라이언트 생성 응답입니다. 개별 FunctionResponse 객체는 id 필드를 통해 각각의 FunctionCall 객체와 일치합니다.

단항 및 서버 스트리밍 GenerateContent API 함수 호출이 Content 부분을 교환하여 발생하는 반면, bidi GenerateContent API 함수 호출은 이러한 전용 메시지 세트를 통해 발생합니다.

필드

필드
`functionResponses[]`	`FunctionResponse` (선택사항) 함수 호출에 대한 응답입니다.

functionResponses[]

FunctionResponse

(선택사항) 함수 호출에 대한 응답입니다.

BidiGenerateContentTranscription

오디오 스크립트 (입력 또는 출력)

필드

필드
`text`	`string` 스크립트 작성 텍스트입니다.

text

string

스크립트 작성 텍스트입니다.

ContextWindowCompressionConfig

컨텍스트 윈도우 압축을 사용 설정합니다. 컨텍스트 윈도우 압축은 모델의 컨텍스트 윈도우가 지정된 길이를 초과하지 않도록 관리하는 메커니즘입니다.

필드

필드
통합 필드 `compressionMechanism`. 사용된 컨텍스트 윈도우 압축 메커니즘입니다. `compressionMechanism`은 다음 중 하나여야 합니다.
`slidingWindow`	`SlidingWindow` 슬라이딩 윈도우 메커니즘
`triggerTokens`	`int64` 컨텍스트 윈도우 압축을 트리거하는 데 필요한 토큰 수 (턴 실행 전)입니다. 이를 통해 짧은 컨텍스트 윈도우로 인해 모델 응답이 빨라질 수 있으므로 품질과 지연 시간의 균형을 맞출 수 있습니다. 하지만 압축 작업은 일시적인 지연 시간 증가를 유발하므로 자주 트리거해서는 안 됩니다. 설정하지 않으면 모델의 컨텍스트 윈도우 한도의 80% 가 기본값입니다. 따라서 다음 사용자 요청/모델 응답에 20% 가 남습니다.

통합 필드 compressionMechanism. 사용된 컨텍스트 윈도우 압축 메커니즘입니다. compressionMechanism은 다음 중 하나여야 합니다.

slidingWindow

SlidingWindow

슬라이딩 윈도우 메커니즘

triggerTokens

int64

컨텍스트 윈도우 압축을 트리거하는 데 필요한 토큰 수 (턴 실행 전)입니다.

이를 통해 짧은 컨텍스트 윈도우로 인해 모델 응답이 빨라질 수 있으므로 품질과 지연 시간의 균형을 맞출 수 있습니다. 하지만 압축 작업은 일시적인 지연 시간 증가를 유발하므로 자주 트리거해서는 안 됩니다.

설정하지 않으면 모델의 컨텍스트 윈도우 한도의 80% 가 기본값입니다. 따라서 다음 사용자 요청/모델 응답에 20% 가 남습니다.

EndSensitivity

음성 종료를 감지하는 방법을 결정합니다.

열거형
`END_SENSITIVITY_UNSPECIFIED`	기본값은 END_SENSITIVITY_HIGH입니다.
`END_SENSITIVITY_HIGH`	자동 감지 기능은 음성을 더 많은 빈도로 종료합니다.
`END_SENSITIVITY_LOW`	자동 감지 기능은 음성을 더 적은 빈도로 종료합니다.

GoAway

서버가 곧 연결 해제된다는 알림입니다.

필드

필드
`timeLeft`	`Duration` 연결이 ABORTED로 종료되기까지 남은 시간입니다. 이 기간은 모델별 최소값보다 작을 수 없으며, 모델의 비율 제한과 함께 지정됩니다.

timeLeft

Duration

연결이 ABORTED로 종료되기까지 남은 시간입니다.

이 기간은 모델별 최소값보다 작을 수 없으며, 모델의 비율 제한과 함께 지정됩니다.

ProactivityConfig

선제적 기능 구성입니다.

필드

필드
`proactiveAudio`	`bool` 선택사항입니다. 사용 설정하면 모델이 마지막 프롬프트에 대한 응답을 거부할 수 있습니다. 예를 들어 이를 통해 모델은 맥락에 맞지 않는 음성을 무시하거나 사용자가 아직 요청하지 않은 경우 무음 상태를 유지할 수 있습니다.

proactiveAudio

bool

선택사항입니다. 사용 설정하면 모델이 마지막 프롬프트에 대한 응답을 거부할 수 있습니다. 예를 들어 이를 통해 모델은 맥락에 맞지 않는 음성을 무시하거나 사용자가 아직 요청하지 않은 경우 무음 상태를 유지할 수 있습니다.

RealtimeInputConfig

BidiGenerateContent에서 실시간 입력 동작을 구성합니다.

필드

필드
`automaticActivityDetection`	`AutomaticActivityDetection` (선택사항) 설정하지 않으면 기본적으로 자동 활동 감지가 사용 설정됩니다. 자동 음성 감지가 사용 중지된 경우 클라이언트는 활동 신호를 전송해야 합니다.
`activityHandling`	`ActivityHandling` (선택사항) 활동이 미치는 영향을 정의합니다.
`turnCoverage`	`TurnCoverage` (선택사항) 사용자 턴에 포함된 입력을 정의합니다.

automaticActivityDetection

AutomaticActivityDetection

(선택사항) 설정하지 않으면 기본적으로 자동 활동 감지가 사용 설정됩니다. 자동 음성 감지가 사용 중지된 경우 클라이언트는 활동 신호를 전송해야 합니다.

activityHandling

ActivityHandling

(선택사항) 활동이 미치는 영향을 정의합니다.

turnCoverage

TurnCoverage

(선택사항) 사용자 턴에 포함된 입력을 정의합니다.

SessionResumptionConfig

세션 재개 구성입니다.

이 메시지는 세션 구성에 BidiGenerateContentSetup.sessionResumption로 포함됩니다. 구성된 경우 서버는 SessionResumptionUpdate 메시지를 전송합니다.

필드

필드
`handle`	`string` 이전 세션의 핸들입니다. 값이 없으면 새 세션이 생성됩니다. 세션 핸들은 이전 연결의 `SessionResumptionUpdate.token` 값에서 가져옵니다.

handle

string

이전 세션의 핸들입니다. 값이 없으면 새 세션이 생성됩니다.

세션 핸들은 이전 연결의 SessionResumptionUpdate.token 값에서 가져옵니다.

SessionResumptionUpdate

세션 재개 상태의 업데이트입니다.

BidiGenerateContentSetup.sessionResumption가 설정된 경우에만 전송됩니다.

필드

필드
`newHandle`	`string` 재개할 수 있는 상태를 나타내는 새 핸들입니다. `resumable`=false인 경우 비어 있습니다.
`resumable`	`bool` 이 시점에서 현재 세션을 재개할 수 있으면 true입니다. 세션의 일부 시점에서는 재개가 불가능합니다. 예를 들어 모델이 함수 호출을 실행하거나 생성하는 경우입니다. 이러한 상태에서 세션을 재개하면 (이전 세션 토큰 사용) 일부 데이터 손실이 발생합니다. 이 경우 `newHandle`은 비어 있고 `resumable`은 false입니다.

newHandle

string

재개할 수 있는 상태를 나타내는 새 핸들입니다. resumable=false인 경우 비어 있습니다.

resumable

bool

이 시점에서 현재 세션을 재개할 수 있으면 true입니다.

세션의 일부 시점에서는 재개가 불가능합니다. 예를 들어 모델이 함수 호출을 실행하거나 생성하는 경우입니다. 이러한 상태에서 세션을 재개하면 (이전 세션 토큰 사용) 일부 데이터 손실이 발생합니다. 이 경우 newHandle은 비어 있고 resumable은 false입니다.

SlidingWindow

SlidingWindow 메서드는 컨텍스트 창의 시작 부분에서 콘텐츠를 삭제하여 작동합니다. 결과 컨텍스트는 항상 USER 역할 턴의 시작 부분에서 시작됩니다. 시스템 안내와 BidiGenerateContentSetup.prefixTurns는 항상 결과의 시작 부분에 유지됩니다.

필드

필드
`targetTokens`	`int64` 유지할 대상 토큰 수입니다. 기본값은 trigger_tokens/2입니다. 컨텍스트 윈도우의 일부를 삭제하면 일시적으로 지연 시간이 증가하므로 이 값은 빈번한 압축 작업을 방지하도록 보정해야 합니다.

targetTokens

int64

유지할 대상 토큰 수입니다. 기본값은 trigger_tokens/2입니다.

컨텍스트 윈도우의 일부를 삭제하면 일시적으로 지연 시간이 증가하므로 이 값은 빈번한 압축 작업을 방지하도록 보정해야 합니다.

StartSensitivity

음성 시작이 감지되는 방식을 결정합니다.

열거형
`START_SENSITIVITY_UNSPECIFIED`	기본값은 START_SENSITIVITY_HIGH입니다.
`START_SENSITIVITY_HIGH`	자동 감지 기능은 음성 시작을 더 많은 빈도로 감지합니다.
`START_SENSITIVITY_LOW`	자동 감지 기능은 음성 시작을 더 적은 빈도로 감지합니다.

TurnCoverage

사용자 턴에 포함되는 입력에 관한 옵션입니다.

열거형
`TURN_COVERAGE_UNSPECIFIED`	지정되지 않은 경우 기본 동작은 `TURN_INCLUDES_ONLY_ACTIVITY`입니다.
`TURN_INCLUDES_ONLY_ACTIVITY`	사용자 턴에는 마지막 턴 이후의 활동만 포함되며 비활성 상태(예: 무음의 오디오 스트림)는 제외됩니다. 이것이 기본 동작입니다.
`TURN_INCLUDES_ALL_INPUT`	사용자 턴에는 비활성 상태(예: 무음의 오디오 스트림)를 포함하여 마지막 턴 이후의 모든 실시간 입력이 포함됩니다.

UrlContextMetadata

URL 컨텍스트 가져오기 도구와 관련된 메타데이터입니다.

필드

urlMetadata[]

UrlMetadata

URL 컨텍스트 목록입니다.

UsageMetadata

응답에 관한 사용 메타데이터입니다.

필드
`promptTokenCount`	`int32` 출력 전용입니다. 프롬프트의 토큰 수입니다. `cachedContent`가 설정된 경우에도 이는 여전히 총 유효 프롬프트 크기이며 캐시된 콘텐츠의 토큰 수를 포함합니다.
`cachedContentTokenCount`	`int32` 프롬프트의 캐시된 부분 (캐시된 콘텐츠)에 있는 토큰 수
`responseTokenCount`	`int32` 출력 전용입니다. 생성된 모든 대답 후보의 총 토큰 수입니다.
`toolUsePromptTokenCount`	`int32` 출력 전용입니다. 도구 사용 프롬프트에 있는 토큰 수입니다.
`thoughtsTokenCount`	`int32` 출력 전용입니다. 사고 모델의 사고 토큰 수입니다.
`totalTokenCount`	`int32` 출력 전용입니다. 생성 요청 (프롬프트 + 응답 후보)의 총 토큰 수입니다.
`promptTokensDetails[]`	`ModalityTokenCount` 출력 전용입니다. 요청 입력에서 처리된 모달리티 목록입니다.
`cacheTokensDetails[]`	`ModalityTokenCount` 출력 전용입니다. 요청 입력에 있는 캐시된 콘텐츠의 모달리티 목록입니다.
`responseTokensDetails[]`	`ModalityTokenCount` 출력 전용입니다. 대답에 반환된 모달리티 목록입니다.
`toolUsePromptTokensDetails[]`	`ModalityTokenCount` 출력 전용입니다. 도구 사용 요청 입력에 대해 처리된 모달리티 목록입니다.

임시 인증 토큰

임시 인증 토큰은 AuthTokenService.CreateToken를 호출하여 획득할 수 있으며, access_token 쿼리 매개변수에서 토큰을 전달하거나 HTTP Authorization 헤더에서 앞에 'Token'을 붙여 GenerativeService.BidiGenerateContentConstrained와 함께 사용할 수 있습니다.

CreateAuthTokenRequest

일시적인 인증 토큰을 만듭니다.

필드

필드
`authToken`	`AuthToken` 필수 항목입니다. 생성할 토큰입니다.

authToken

AuthToken

필수 항목입니다. 생성할 토큰입니다.

AuthToken

임시 인증 토큰을 생성하는 요청입니다.

필드
`name`	`string` 출력 전용입니다. 식별자. 토큰 자체입니다.
`expireTime`	`Timestamp` 선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 결과 토큰을 사용할 때 BidiGenerateContent 세션의 메시지가 거부되는 선택적 시간입니다. (이 시간이 지나면 Gemini가 세션을 선제적으로 종료할 수 있습니다.) 설정하지 않으면 기본적으로 30분 후로 설정됩니다. 설정된 경우 이 값은 20시간 이내의 미래여야 합니다.
`newSessionExpireTime`	`Timestamp` 선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 이 요청으로 생성된 토큰을 사용하는 새 Live API 세션이 거부되는 시간입니다. 설정하지 않으면 기본값은 60초 후로 설정됩니다. 설정된 경우 이 값은 20시간 이내의 미래여야 합니다.
`fieldMask`	`FieldMask` 선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. field_mask가 비어 있고 `bidiGenerateContentSetup`가 없으면 유효한 `BidiGenerateContentSetup` 메시지가 Live API 연결에서 가져옵니다. field_mask가 비어 있고 `bidiGenerateContentSetup`가 있으면 `BidiGenerateContentSetup` 메시지가 이 요청의 `bidiGenerateContentSetup`에서 완전히 가져옵니다. Live API 연결의 설정 메시지가 무시됩니다. field_mask가 비어 있지 않으면 `bidiGenerateContentSetup`의 해당 필드가 Live API 연결의 설정 메시지 필드를 덮어씁니다.
통합 필드 `config`. 결과 토큰의 메서드별 구성입니다. `config`은 다음 중 하나여야 합니다.
`bidiGenerateContentSetup`	`BidiGenerateContentSetup` 선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. `BidiGenerateContent` 관련 구성입니다.
`uses`	`int32` 선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 토큰을 사용할 수 있는 횟수입니다. 이 값이 0이면 제한이 적용되지 않습니다. Live API 세션을 재개하는 것은 사용으로 간주되지 않습니다. 지정하지 않으면 기본값은 1입니다.

일반적인 유형에 대한 추가 정보

일반적으로 사용되는 API 리소스 유형 Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, ModalityTokenCount, Tool에 관한 자세한 내용은 콘텐츠 생성을 참고하세요.