Gemini 4 Argon을 지금 이용 가능합니다. 사용해 보기.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Gemini Webhooks API

웹훅을 사용하면 비동기 또는 장기 실행 작업 (LRO)이 완료될 때 Gemini API가 서버에 실시간 알림을 푸시할 수 있습니다. 이렇게 하면 상태 업데이트를 위해 API를 폴링할 필요가 없어 지연 시간과 오버헤드가 줄어듭니다.

마크다운으로 보기 OpenAPI 사양 보기

CreateWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks

새 웹훅을 만듭니다.

요청 본문
응답

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

name string (선택사항)

선택사항입니다. 사용자가 제공한 웹훅 이름입니다.

subscribed_events array (enum (string)) (필수)

필수 항목입니다. 웹훅이 구독하는 이벤트입니다. 사용 가능한 이벤트: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

가능한 값은 다음과 같습니다.

batch.succeeded
일괄 처리가 완료되었습니다.
batch.expired
배치가 48시간 이내에 처리되지 않았습니다.
batch.failed
일괄 작업이 실패했습니다.
interaction.requires_action
상호작용에 작업 (예: 함수 호출)이 필요합니다.
interaction.completed
상호작용이 완료되었습니다.
interaction.failed
상호작용에 실패했습니다.
video.generated
동영상 생성이 완료되었습니다.

uri string (필수)

필수 항목입니다. 웹훅 이벤트가 전송될 URI입니다.

응답

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

create_time string (선택사항)

출력 전용입니다. 웹훅이 생성된 타임스탬프입니다.

id string (선택사항)

출력 전용입니다. 웹훅의 ID입니다.

name string (선택사항)

선택사항입니다. 사용자가 제공한 웹훅 이름입니다.

new_signing_secret string (선택사항)

출력 전용입니다. 웹훅의 새 서명 보안 비밀입니다. 생성 시에만 채워집니다.

signing_secrets array (SigningSecret) (선택사항)

출력 전용입니다. 이 웹훅과 연결된 서명 보안 비밀입니다.

필드

expire_time string (선택사항)

출력 전용입니다. 서명 보안 비밀의 만료일입니다.

truncated_secret string (선택사항)

출력 전용입니다. 서명 보안 비밀의 잘린 버전입니다.

state enum (string) (선택사항)

출력 전용입니다. 웹훅의 상태입니다.

가능한 값은 다음과 같습니다.

enabled
웹훅이 사용 설정되어 있습니다.
disabled
사용자가 웹훅을 사용 중지했습니다.
disabled_due_to_failed_deliveries
전송 실패로 인해 웹훅이 사용 중지되었습니다.

subscribed_events array (enum (string)) (선택사항)

가능한 값은 다음과 같습니다.

batch.succeeded
일괄 처리가 완료되었습니다.
batch.expired
배치가 48시간 이내에 처리되지 않았습니다.
batch.failed
일괄 작업이 실패했습니다.
interaction.requires_action
상호작용에 작업 (예: 함수 호출)이 필요합니다.
interaction.completed
상호작용이 완료되었습니다.
interaction.failed
상호작용에 실패했습니다.
video.generated
동영상 생성이 완료되었습니다.

update_time string (선택사항)

출력 전용입니다. 웹훅이 마지막으로 업데이트된 타임스탬프입니다.

uri string (선택사항)

필수 항목입니다. 웹훅 이벤트가 전송될 URI입니다.

예

응답 예시

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

PingWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:ping

웹훅에 핑 이벤트를 전송합니다.

경로 / 쿼리 매개변수
요청 본문
응답

경로 / 쿼리 매개변수

id 문자열 (필수)

필수 항목입니다. ping할 웹훅의 ID입니다. 형식: `{webhook_id}`

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

응답

성공한 경우 응답은 비어 있습니다.

예

RotateSigningSecret

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret

웹훅의 새 서명 보안 비밀을 생성합니다.

경로 / 쿼리 매개변수
요청 본문
응답

경로 / 쿼리 매개변수

id 문자열 (필수)

필수 항목입니다. 서명 보안 비밀을 생성할 웹훅의 ID입니다. 형식: `{webhook_id}`

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

revocation_behavior enum (string) (선택사항)

선택사항입니다. 이전 서명 보안 비밀의 취소 동작입니다.

가능한 값은 다음과 같습니다.

revoke_previous_secrets_after_h24
새 서명 보안 비밀을 생성하고 24시간 후에 이전 보안 비밀을 모두 취소합니다. 마이그레이션의 기본 및 가장 안전한 옵션입니다.
revoke_previous_secrets_immediately
이전 보안 비밀을 모두 즉시 취소합니다. 진행 중인 알림이 중단될 수 있으므로 주의해서 사용하세요.

응답

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

secret string (선택사항)

출력 전용입니다. 새로 생성된 서명 보안 비밀입니다.

예

응답 예시

{
  "secret": "string"
}

ListWebhooks

get https://generativelanguage.googleapis.com/v1beta/webhooks

모든 웹훅을 나열합니다.

경로 / 쿼리 매개변수
응답

경로 / 쿼리 매개변수

page_size integer (선택사항)

선택사항입니다. 반환할 최대 웹훅 수입니다. 서비스가 이 값보다 더 적게 반환할 수 있습니다. 지정하지 않으면 최대 50개의 웹훅이 반환됩니다. 최댓값은 1,000입니다.

page_token string (선택사항)

선택사항입니다. 이전 `ListWebhooks` 호출에서 수신된 페이지 토큰입니다. 후속 페이지를 검색하려면 이를 입력합니다.

응답

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

next_page_token string (선택사항)

토큰입니다. 다음 페이지를 가져오기 위해 `page_token` 으로 전송할 수 있습니다. 이 필드를 생략하면 후속 페이지가 표시되지 않습니다.

웹훅 배열 (Webhook) (선택사항)

웹훅입니다.

예

응답 예시

{
  "next_page_token": "string",
  "webhooks": [
    {
      "create_time": "string",
      "id": "string",
      "name": "string",
      "new_signing_secret": "string",
      "signing_secrets": [
        {
          "expire_time": "string",
          "truncated_secret": "string"
        }
      ],
      "state": "enabled",
      "subscribed_events": [
        "batch.succeeded"
      ],
      "update_time": "string",
      "uri": "string"
    }
  ]
}

GetWebhook

get https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

특정 Webhook을 가져옵니다.

경로 / 쿼리 매개변수
응답

경로 / 쿼리 매개변수

id 문자열 (필수)

필수 항목입니다. 가져올 웹훅의 ID입니다.

응답

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

create_time string (선택사항)

출력 전용입니다. 웹훅이 생성된 타임스탬프입니다.

id string (선택사항)

출력 전용입니다. 웹훅의 ID입니다.

name string (선택사항)

선택사항입니다. 사용자가 제공한 웹훅 이름입니다.

new_signing_secret string (선택사항)

출력 전용입니다. 웹훅의 새 서명 보안 비밀입니다. 생성 시에만 채워집니다.

signing_secrets array (SigningSecret) (선택사항)

출력 전용입니다. 이 웹훅과 연결된 서명 보안 비밀입니다.

필드

expire_time string (선택사항)

출력 전용입니다. 서명 보안 비밀의 만료일입니다.

truncated_secret string (선택사항)

출력 전용입니다. 서명 보안 비밀의 잘린 버전입니다.

state enum (string) (선택사항)

출력 전용입니다. 웹훅의 상태입니다.

가능한 값은 다음과 같습니다.

enabled
웹훅이 사용 설정되어 있습니다.
disabled
사용자가 웹훅을 사용 중지했습니다.
disabled_due_to_failed_deliveries
전송 실패로 인해 웹훅이 사용 중지되었습니다.

subscribed_events array (enum (string)) (선택사항)

가능한 값은 다음과 같습니다.

batch.succeeded
일괄 처리가 완료되었습니다.
batch.expired
배치가 48시간 이내에 처리되지 않았습니다.
batch.failed
일괄 작업이 실패했습니다.
interaction.requires_action
상호작용에 작업 (예: 함수 호출)이 필요합니다.
interaction.completed
상호작용이 완료되었습니다.
interaction.failed
상호작용에 실패했습니다.
video.generated
동영상 생성이 완료되었습니다.

update_time string (선택사항)

출력 전용입니다. 웹훅이 마지막으로 업데이트된 타임스탬프입니다.

uri string (선택사항)

필수 항목입니다. 웹훅 이벤트가 전송될 URI입니다.

예

응답 예시

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

UpdateWebhook

patch https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

기존 웹훅을 업데이트합니다.

경로 / 쿼리 매개변수
요청 본문
응답

경로 / 쿼리 매개변수

id 문자열 (필수)

필수 항목입니다. 업데이트할 웹훅의 ID입니다.

update_mask string (선택사항)

선택사항입니다. 업데이트할 필드 목록입니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

name string (선택사항)

선택사항입니다. 사용자가 제공한 웹훅 이름입니다.

state enum (string) (선택사항)

선택사항입니다. 웹훅의 상태입니다.

가능한 값은 다음과 같습니다.

enabled
웹훅이 사용 설정되어 있습니다.
disabled
사용자가 웹훅을 사용 중지했습니다.
disabled_due_to_failed_deliveries
전송 실패로 인해 웹훅이 사용 중지되었습니다.

subscribed_events array (enum (string)) (선택사항)

선택사항입니다. 웹훅이 구독하는 이벤트입니다. 사용 가능한 이벤트: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

가능한 값은 다음과 같습니다.

batch.succeeded
일괄 처리가 완료되었습니다.
batch.expired
배치가 48시간 이내에 처리되지 않았습니다.
batch.failed
일괄 작업이 실패했습니다.
interaction.requires_action
상호작용에 작업 (예: 함수 호출)이 필요합니다.
interaction.completed
상호작용이 완료되었습니다.
interaction.failed
상호작용에 실패했습니다.
video.generated
동영상 생성이 완료되었습니다.

uri string (선택사항)

선택사항입니다. 웹훅 이벤트가 전송될 URI입니다.

응답

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

create_time string (선택사항)

출력 전용입니다. 웹훅이 생성된 타임스탬프입니다.

id string (선택사항)

출력 전용입니다. 웹훅의 ID입니다.

name string (선택사항)

선택사항입니다. 사용자가 제공한 웹훅 이름입니다.

new_signing_secret string (선택사항)

출력 전용입니다. 웹훅의 새 서명 보안 비밀입니다. 생성 시에만 채워집니다.

signing_secrets array (SigningSecret) (선택사항)

출력 전용입니다. 이 웹훅과 연결된 서명 보안 비밀입니다.

필드

expire_time string (선택사항)

출력 전용입니다. 서명 보안 비밀의 만료일입니다.

truncated_secret string (선택사항)

출력 전용입니다. 서명 보안 비밀의 잘린 버전입니다.

state enum (string) (선택사항)

출력 전용입니다. 웹훅의 상태입니다.

가능한 값은 다음과 같습니다.

enabled
웹훅이 사용 설정되어 있습니다.
disabled
사용자가 웹훅을 사용 중지했습니다.
disabled_due_to_failed_deliveries
전송 실패로 인해 웹훅이 사용 중지되었습니다.

subscribed_events array (enum (string)) (선택사항)

가능한 값은 다음과 같습니다.

batch.succeeded
일괄 처리가 완료되었습니다.
batch.expired
배치가 48시간 이내에 처리되지 않았습니다.
batch.failed
일괄 작업이 실패했습니다.
interaction.requires_action
상호작용에 작업 (예: 함수 호출)이 필요합니다.
interaction.completed
상호작용이 완료되었습니다.
interaction.failed
상호작용에 실패했습니다.
video.generated
동영상 생성이 완료되었습니다.

update_time string (선택사항)

출력 전용입니다. 웹훅이 마지막으로 업데이트된 타임스탬프입니다.

uri string (선택사항)

필수 항목입니다. 웹훅 이벤트가 전송될 URI입니다.

예

응답 예시

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

DeleteWebhook

delete https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

웹훅을 삭제합니다.

경로 / 쿼리 매개변수
응답

경로 / 쿼리 매개변수

id 문자열 (필수)

필수 항목입니다. 삭제할 웹훅의 ID입니다. 형식: `{webhook_id}`

응답

성공한 경우 응답은 비어 있습니다.

예

리소스

웹훅

웹훅 리소스입니다.

필드

create_time string (선택사항)

출력 전용입니다. 웹훅이 생성된 타임스탬프입니다.

id string (선택사항)

출력 전용입니다. 웹훅의 ID입니다.

name string (선택사항)

선택사항입니다. 사용자가 제공한 웹훅 이름입니다.

new_signing_secret string (선택사항)

출력 전용입니다. 웹훅의 새 서명 보안 비밀입니다. 생성 시에만 채워집니다.

signing_secrets array (SigningSecret) (선택사항)

출력 전용입니다. 이 웹훅과 연결된 서명 보안 비밀입니다.

필드

expire_time string (선택사항)

출력 전용입니다. 서명 보안 비밀의 만료일입니다.

truncated_secret string (선택사항)

출력 전용입니다. 서명 보안 비밀의 잘린 버전입니다.

state enum (string) (선택사항)

출력 전용입니다. 웹훅의 상태입니다.

가능한 값은 다음과 같습니다.

enabled
웹훅이 사용 설정되어 있습니다.
disabled
사용자가 웹훅을 사용 중지했습니다.
disabled_due_to_failed_deliveries
전송 실패로 인해 웹훅이 사용 중지되었습니다.

subscribed_events array (enum (string)) (선택사항)

가능한 값은 다음과 같습니다.

batch.succeeded
일괄 처리가 완료되었습니다.
batch.expired
배치가 48시간 이내에 처리되지 않았습니다.
batch.failed
일괄 작업이 실패했습니다.
interaction.requires_action
상호작용에 작업 (예: 함수 호출)이 필요합니다.
interaction.completed
상호작용이 완료되었습니다.
interaction.failed
상호작용에 실패했습니다.
video.generated
동영상 생성이 완료되었습니다.

update_time string (선택사항)

출력 전용입니다. 웹훅이 마지막으로 업데이트된 타임스탬프입니다.

uri string (선택사항)

필수 항목입니다. 웹훅 이벤트가 전송될 URI입니다.