Método: models.generateContent
- Endpoint
- Parâmetros de caminho
- Corpo da solicitação
- Corpo da resposta
- Escopos de autorização
- Exemplo de solicitação
Gera uma resposta do modelo que recebe uma entrada GenerateContentRequest
.
Os recursos de entrada diferem entre os modelos, incluindo os ajustados. Consulte o guia de modelo e o guia de ajuste para mais detalhes.
Endpoint
postar
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:generateContent
Parâmetros de caminho
model
string
Obrigatório. O nome da Model
que será usada para gerar a conclusão.
Formato: name=models/{model}
. Ele tem o formato models/{model}
.
Corpo da solicitação
O corpo da solicitação contém dados com a seguinte estrutura:
contents[]
object (Content
)
Obrigatório. O conteúdo da conversa atual com o modelo.
Para consultas de turno único, esta é uma instância única. Para consultas de vários turnos, esse é um campo repetido que contém o histórico de conversas + a solicitação mais recente.
tools[]
object (Tool
)
Opcional. Uma lista de Tools
que o modelo pode usar para gerar a próxima resposta.
Um Tool
é um trecho de código que permite ao sistema interagir com sistemas externos para realizar uma ação, ou conjunto de ações, fora do conhecimento e do escopo do modelo. No momento, a única ferramenta compatível é Function
.
toolConfig
object (ToolConfig
)
Opcional. Configuração de ferramenta para qualquer Tool
especificado na solicitação.
safetySettings[]
object (SafetySetting
)
Opcional. Uma lista de instâncias SafetySetting
exclusivas para bloquear conteúdo não seguro.
Isso será aplicado no GenerateContentRequest.contents
e no GenerateContentResponse.candidates
. Não pode haver mais de uma configuração para cada tipo de SafetyCategory
. A API vai bloquear todos os conteúdos e respostas que não atenderem aos limites definidos por essas configurações. Essa lista substitui as configurações padrão de cada SafetyCategory
especificada em safetySettings. Se não houver SafetySetting
para um determinado SafetyCategory
fornecido na lista, a API vai usar a configuração de segurança padrão para essa categoria. As categorias de dano HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT e HARM_CATEGORY_HARASSMENT são compatíveis.
systemInstruction
object (Content
)
Opcional. O desenvolvedor definiu as instruções do sistema. No momento, somente texto.
generationConfig
object (GenerationConfig
)
Opcional. Opções de configuração para geração e saídas de modelos.
cachedContent
string
Opcional. O nome do conteúdo armazenado em cache usado como contexto para disponibilizar a previsão. Observação: usado apenas em armazenamento em cache explícito, em que os usuários podem ter controle sobre o armazenamento em cache (por exemplo, qual conteúdo armazenar em cache) e aproveitar a economia de custos garantida. Formato: cachedContents/{cachedContent}
Exemplo de solicitação
Texto
Python
Node.js
Kotlin
Swift
Dart
Java
Imagem
Python
Node.js
Kotlin
Swift
Dart
Java
Áudio
Python
Node.js
Vídeo
Python
Node.js
Chat
Python
Node.js
Concha
Kotlin
Swift
Dart
Java
Cache
Python
Node.js
Modelo ajustado
Python
Modo JSON
Python
Node.js
Kotlin
Swift
Dart
Java
Execução de código
Python
Kotlin
Java
chamada de função
Python
Node.js
Kotlin
Swift
Dart
Java
Configuração de geração
Python
Node.js
Concha
Kotlin
Swift
Dart
Java
Configurações de segurança
Python
Node.js
Concha
Kotlin
Swift
Dart
Java
Instrução do sistema
Python
Node.js
Kotlin
Swift
Dart
Java
Corpo da resposta
Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de GenerateContentResponse
.
Método: models.streamGenerateContent
- Endpoint
- Parâmetros de caminho
- Corpo da solicitação
- Corpo da resposta
- Escopos de autorização
- Exemplo de solicitação
Gera uma resposta transmitida a partir do modelo que recebe uma entrada GenerateContentRequest
.
Endpoint
postar
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:streamGenerateContent
Parâmetros de caminho
model
string
Obrigatório. O nome da Model
que será usada para gerar a conclusão.
Formato: name=models/{model}
. Ele tem o formato models/{model}
.
Corpo da solicitação
O corpo da solicitação contém dados com a seguinte estrutura:
contents[]
object (Content
)
Obrigatório. O conteúdo da conversa atual com o modelo.
Para consultas de turno único, esta é uma instância única. Para consultas de vários turnos, esse é um campo repetido que contém o histórico de conversas + a solicitação mais recente.
tools[]
object (Tool
)
Opcional. Uma lista de Tools
que o modelo pode usar para gerar a próxima resposta.
Um Tool
é um trecho de código que permite ao sistema interagir com sistemas externos para realizar uma ação, ou conjunto de ações, fora do conhecimento e do escopo do modelo. No momento, a única ferramenta compatível é Function
.
toolConfig
object (ToolConfig
)
Opcional. Configuração de ferramenta para qualquer Tool
especificado na solicitação.
safetySettings[]
object (SafetySetting
)
Opcional. Uma lista de instâncias SafetySetting
exclusivas para bloquear conteúdo não seguro.
Isso será aplicado no GenerateContentRequest.contents
e no GenerateContentResponse.candidates
. Não pode haver mais de uma configuração para cada tipo de SafetyCategory
. A API vai bloquear todos os conteúdos e respostas que não atenderem aos limites definidos por essas configurações. Essa lista substitui as configurações padrão de cada SafetyCategory
especificada em safetySettings. Se não houver SafetySetting
para um determinado SafetyCategory
fornecido na lista, a API vai usar a configuração de segurança padrão para essa categoria. As categorias de dano HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT e HARM_CATEGORY_HARASSMENT são compatíveis.
systemInstruction
object (Content
)
Opcional. O desenvolvedor definiu as instruções do sistema. No momento, somente texto.
generationConfig
object (GenerationConfig
)
Opcional. Opções de configuração para geração e saídas de modelos.
cachedContent
string
Opcional. O nome do conteúdo armazenado em cache usado como contexto para disponibilizar a previsão. Observação: usado apenas em armazenamento em cache explícito, em que os usuários podem ter controle sobre o armazenamento em cache (por exemplo, qual conteúdo armazenar em cache) e aproveitar a economia de custos garantida. Formato: cachedContents/{cachedContent}
Exemplo de solicitação
Texto
Python
Node.js
Kotlin
Swift
Dart
Java
Imagem
Python
Node.js
Kotlin
Swift
Dart
Java
Vídeo
Python
Node.js
Kotlin
Java
Chat
Python
Node.js
Concha
Kotlin
Swift
Dart
Java
Corpo da resposta
Se a solicitação for bem-sucedida, o corpo da resposta incluirá um stream de instâncias de GenerateContentResponse
.
GenerateContentResponse
Resposta do modelo que oferece suporte a vários candidatos.
Observação sobre as classificações de segurança e a filtragem de conteúdo. Eles são informados para o comando em GenerateContentResponse.prompt_feedback
e para cada candidato em finishReason
e em safetyRatings
. O contrato da API determina que: todos os candidatos solicitados são devolvidos ou nenhum candidato é retornado; nenhum candidato é retornado apenas se houver algo de errado com a solicitação (consulte promptFeedback
); o feedback sobre cada candidato é informado em finishReason
e safetyRatings
.
Representação JSON |
---|
{ "candidates": [ { object ( |
candidates[]
object (Candidate
)
Respostas dos candidatos do modelo.
promptFeedback
object (PromptFeedback
)
Retorna o feedback do comando relacionado aos filtros de conteúdo.
usageMetadata
object (UsageMetadata
)
Apenas saída. Metadados sobre as solicitações de geração o uso de tokens.
PromptFeedback
Um conjunto de metadados de feedback do comando especificado em GenerateContentRequest.content
.
Representação JSON |
---|
{ "blockReason": enum ( |
blockReason
enum (BlockReason
)
Opcional. Se definido, a solicitação será bloqueada e nenhum candidato será retornado. Reformule seu comando.
safetyRatings[]
object (SafetyRating
)
Classificações para segurança do comando. Existe no máximo uma classificação por categoria.
BlockReason
Especifica o motivo do bloqueio da solicitação.
Enums | |
---|---|
BLOCK_REASON_UNSPECIFIED |
Valor padrão. Esse valor não é usado. |
SAFETY |
O comando foi bloqueado por motivos de segurança. Inspecione o safetyRatings para entender qual categoria de segurança o bloqueou. |
OTHER |
A solicitação foi bloqueada por motivos desconhecidos. |
UsageMetadata
Metadados sobre o uso do token da solicitação de geração.
Representação JSON |
---|
{ "promptTokenCount": integer, "cachedContentTokenCount": integer, "candidatesTokenCount": integer, "totalTokenCount": integer } |
promptTokenCount
integer
Número de tokens no comando. Quando cacheContent é definido, esse ainda é o tamanho total efetivo da solicitação. Por exemplo: isso inclui o número de tokens no conteúdo armazenado em cache.
cachedContentTokenCount
integer
Número de tokens na parte armazenada em cache do comando, ou seja, no conteúdo armazenado em cache.
candidatesTokenCount
integer
Número total de tokens nos candidatos gerados.
totalTokenCount
integer
Contagem total de tokens para a solicitação de geração (comando + candidatos).
Candidato
- Representação JSON
- FinishReason
- GroundingAttribution
- AttributionSourceId
- GroundingPassageId
- SemanticRetrieverChunk
Um candidato de resposta gerado a partir do modelo.
Representação JSON |
---|
{ "content": { object ( |
content
object (Content
)
Apenas saída. Conteúdo gerado retornado do modelo.
finishReason
enum (FinishReason
)
Opcional. Apenas saída. É o motivo pelo qual o modelo parou de gerar tokens.
Se estiver vazio, o modelo não parou de gerar os tokens.
safetyRatings[]
object (SafetyRating
)
Lista de classificações para a segurança de um candidato de resposta.
Existe no máximo uma classificação por categoria.
citationMetadata
object (CitationMetadata
)
Apenas saída. Informações da citação do candidato gerado pelo modelo.
Este campo pode ser preenchido com informações de recitação de qualquer texto incluído no content
. Esses são os trechos que são "recitados" com base em material protegido por direitos autorais nos dados de treinamento do LLM básico.
tokenCount
integer
Apenas saída. Contagem de tokens para este candidato.
groundingAttributions[]
object (GroundingAttribution
)
Apenas saída. Informações de atribuição de fontes que contribuíram para uma resposta embasada.
Esse campo é preenchido para chamadas GenerateAnswer
.
index
integer
Apenas saída. Índice do candidato na lista.
FinishReason
Define o motivo pelo qual o modelo parou de gerar tokens.
Enums | |
---|---|
FINISH_REASON_UNSPECIFIED |
Valor padrão. Esse valor não é usado. |
STOP |
Ponto de parada natural do modelo ou sequência de parada fornecida. |
MAX_TOKENS |
O número máximo de tokens especificado na solicitação foi atingido. |
SAFETY |
O conteúdo do candidato foi sinalizado por motivos de segurança. |
RECITATION |
O conteúdo do candidato foi sinalizado por motivos de recitação. |
LANGUAGE |
O conteúdo do candidato foi sinalizado por usar um idioma sem suporte. |
OTHER |
Motivo desconhecido. |
GroundingAttribution
Atribuição a uma fonte que contribuiu para uma resposta.
Representação JSON |
---|
{ "sourceId": { object ( |
sourceId
object (AttributionSourceId
)
Apenas saída. Identificador da fonte que contribui para essa atribuição.
content
object (Content
)
Conteúdo da fonte de embasamento que compõe essa atribuição.
AttributionSourceId
Identificador da fonte que contribui para essa atribuição.
Representação JSON |
---|
{ // Union field |
Campo de união source
.
source
pode ser apenas de um dos tipos a seguir:
groundingPassage
object (GroundingPassageId
)
Identificador de um trecho inline.
semanticRetrieverChunk
object (SemanticRetrieverChunk
)
Identificador de um Chunk
buscado pelo Recuperador Semântico.
GroundingPassageId
Identificador de uma parte em um GroundingPassage
.
Representação JSON |
---|
{ "passageId": string, "partIndex": integer } |
passageId
string
Apenas saída. ID do trecho correspondente ao GroundingPassage.id
de GenerateAnswerRequest
.
partIndex
integer
Apenas saída. Índice da peça no GroundingPassage.content
do GenerateAnswerRequest
.
SemanticRetrieverChunk
Identificador de uma Chunk
extraída pelo recuperador semântico especificado no GenerateAnswerRequest
usando SemanticRetrieverConfig
.
Representação JSON |
---|
{ "source": string, "chunk": string } |
source
string
Apenas saída. Nome da origem que corresponde ao SemanticRetrieverConfig.source
da solicitação. Exemplo: corpora/123
ou corpora/123/documents/abc
chunk
string
Apenas saída. Nome do Chunk
que contém o texto atribuído. Exemplo: corpora/123/documents/abc/chunks/xyz
CitationMetadata
Uma coleção de atribuições de fonte para um conteúdo.
Representação JSON |
---|
{
"citationSources": [
{
object ( |
citationSources[]
object (CitationSource
)
Citações de fontes para uma resposta específica.
CitationSource
Uma citação de uma fonte para parte de uma resposta específica.
Representação JSON |
---|
{ "startIndex": integer, "endIndex": integer, "uri": string, "license": string } |
startIndex
integer
Opcional. Início do trecho da resposta atribuído a essa origem.
Índice indica o início do segmento, medido em bytes.
endIndex
integer
Opcional. Fim do segmento atribuído, exclusivo.
uri
string
Opcional. URI atribuído como uma origem para uma parte do texto.
license
string
Opcional. Licença para o projeto do GitHub que é atribuída como uma origem para o segmento.
As informações da licença são necessárias para citações de código.
GenerationConfig
Opções de configuração para geração e saídas de modelos. Nem todos os parâmetros podem ser configurados para cada modelo.
Representação JSON |
---|
{
"stopSequences": [
string
],
"responseMimeType": string,
"responseSchema": {
object ( |
stopSequences[]
string
Opcional. O conjunto de sequências de caracteres (até 5) que vai interromper a geração de saída. Se especificado, a API vai parar na primeira aparição de uma sequência de paradas. A sequência de parada não será incluída como parte da resposta.
responseMimeType
string
Opcional. Tipo MIME da resposta de saída do texto candidato gerado. Tipo MIME compatível: text/plain
(padrão): saída de texto. application/json
: resposta JSON nos candidatos.
responseSchema
object (Schema
)
Opcional. Esquema de resposta de saída do texto candidato gerado quando o tipo MIME da resposta pode ter esquema. O esquema pode ser objetos, primitivos ou matrizes e é um subconjunto do esquema OpenAPI.
Se definido, um responseMimeType compatível também precisa ser definido. Mimetypes compatíveis: application/json
: esquema para resposta JSON.
candidateCount
integer
Opcional. Número de respostas geradas a serem retornadas.
Atualmente, esse valor só pode ser definido como 1. Se não for definido, o padrão será 1.
maxOutputTokens
integer
Opcional. O número máximo de tokens a serem incluídos em um candidato.
Observação: o valor padrão varia de acordo com o modelo. Consulte o atributo Model.output_token_limit
do Model
retornado da função getModel
.
temperature
number
Opcional. Controla a aleatoriedade da saída.
Observação: o valor padrão varia de acordo com o modelo. Consulte o atributo Model.temperature
do Model
retornado da função getModel
.
Os valores podem variar de [0,0, 2,0].
topP
number
Opcional. A probabilidade cumulativa máxima dos tokens a serem considerados na amostragem.
O modelo usa amostragem combinada de Top-K e Núcleo.
Os tokens são classificados com base nas probabilidades atribuídas, de modo que apenas os tokens mais prováveis sejam considerados. A amostragem top-k limita diretamente o número máximo de tokens a serem considerados, enquanto a amostragem do Nucleus limita o número de tokens com base na probabilidade cumulativa.
Observação: o valor padrão varia de acordo com o modelo. Consulte o atributo Model.top_p
do Model
retornado da função getModel
.
topK
integer
Opcional. O número máximo de tokens a serem considerados na amostragem.
Os modelos usam amostragem de núcleos ou amostragem combinada de Top-K e Núcleo. A amostragem top-k considera o conjunto de topK
tokens mais prováveis. Modelos executados com amostragem de núcleo não permitem a configuração de TopK.
Observação: o valor padrão varia de acordo com o modelo. Consulte o atributo Model.top_k
do Model
retornado da função getModel
. O campo topK
vazio em Model
indica que o modelo não aplica amostragem top-k e não permite a configuração de topK
nas solicitações.
HarmCategory
A categoria de uma classificação.
Essas categorias abrangem vários tipos de danos que os desenvolvedores podem querer ajustar.
Enums | |
---|---|
HARM_CATEGORY_UNSPECIFIED |
A categoria não foi especificada. |
HARM_CATEGORY_DEROGATORY |
Comentários negativos ou prejudiciais voltados à identidade e/ou atributos protegidos. |
HARM_CATEGORY_TOXICITY |
Conteúdo grosseiro, desrespeitoso ou linguagem obscena. |
HARM_CATEGORY_VIOLENCE |
Descreve cenários que retratam violência contra um indivíduo ou grupo ou descrições gerais de sangue em excesso. |
HARM_CATEGORY_SEXUAL |
Contém referências a atos sexuais ou outro conteúdo sexual. |
HARM_CATEGORY_MEDICAL |
Promovem aconselhamento médico sem cuidado. |
HARM_CATEGORY_DANGEROUS |
Conteúdo perigoso que promova, facilite ou incentive atos nocivos. |
HARM_CATEGORY_HARASSMENT |
Conteúdo de assédio. |
HARM_CATEGORY_HATE_SPEECH |
Incitação ao ódio e conteúdo. |
HARM_CATEGORY_SEXUALLY_EXPLICIT |
Conteúdo sexualmente explícito. |
HARM_CATEGORY_DANGEROUS_CONTENT |
Conteúdo perigoso. |
SafetyRating
É a classificação de segurança para um conteúdo.
A classificação de segurança contém a categoria do dano e o nível de probabilidade de danos dessa categoria para um conteúdo. O conteúdo é classificado em relação à segurança em várias categorias de danos, e a probabilidade da classificação está incluída aqui.
Representação JSON |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
Obrigatório. A categoria dessa classificação.
probability
enum (HarmProbability
)
Obrigatório. A probabilidade de dano para o conteúdo.
blocked
boolean
O conteúdo foi bloqueado por causa da classificação?
HarmProbability
A probabilidade de um conteúdo ser nocivo.
O sistema de classificação informa a probabilidade de o conteúdo não ser seguro. Isso não indica a gravidade dos danos a um conteúdo.
Enums | |
---|---|
HARM_PROBABILITY_UNSPECIFIED |
A probabilidade não foi especificada. |
NEGLIGIBLE |
O conteúdo tem uma chance insignificante de não ser seguro. |
LOW |
O conteúdo tem uma chance baixa de não ser seguro. |
MEDIUM |
O conteúdo tem uma chance média de não ser seguro. |
HIGH |
O conteúdo tem uma chance alta de não ser seguro. |
SafetySetting
Configuração de segurança que afeta o comportamento de bloqueio de segurança.
Transmitir uma configuração de segurança para uma categoria altera a probabilidade permitida de que o conteúdo seja bloqueado.
Representação JSON |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
Obrigatório. A categoria dessa configuração.
threshold
enum (HarmBlockThreshold
)
Obrigatório. Controla o limite de probabilidade em que os danos são bloqueados.
HarmBlockThreshold
Bloquear com base em uma probabilidade de danos especificada e além dela.
Enums | |
---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED |
O limite não foi especificado. |
BLOCK_LOW_AND_ABOVE |
O conteúdo NEGLIGÍVEL será permitido. |
BLOCK_MEDIUM_AND_ABOVE |
O conteúdo NEGLIGÍVEL e BAIXO será permitido. |
BLOCK_ONLY_HIGH |
O conteúdo com nível NEGLIGÍVEL, BAIXO e MÉDIO será permitido. |
BLOCK_NONE |
Todo o conteúdo será permitido. |