A API Gemini oferece suporte à geração de conteúdo com imagens, áudio, código, ferramentas e muito mais. Para obter detalhes sobre cada um desses recursos, continue lendo e confira o exemplo de código focado em tarefas ou leia os guias abrangentes.
- Geração de texto
- Vision
- Áudio
- Contexto longo
- Execução de código
- Modo JSON
- Chamadas de função
- Instruções do sistema
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 de modelo conforme uma entrada GenerateContentRequest
. Consulte o guia de geração de texto para informações de uso detalhadas. 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árias interações, como chat, esse é um campo repetido que contém o histórico da conversa e a solicitação mais recente.
tools[]
object (Tool
)
Opcional. Uma lista de Tools
que o Model
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 da Model
. Os Tool
s aceitos são Function
e codeExecution
. Consulte os guias Chamada de função e Execução de código para saber mais.
toolConfig
object (ToolConfig
)
Opcional. Configuração de ferramenta para qualquer Tool
especificado na solicitação. Consulte o guia sobre chamadas de função para conferir um exemplo de uso.
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. Consulte o guia para ver informações detalhadas sobre as configurações de segurança disponíveis. Consulte também as Diretrizes de segurança para saber como incorporar considerações de segurança aos seus aplicativos de IA.
systemInstruction
object (Content
)
Opcional. Instruções do sistema definidas pelo desenvolvedor. 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 para usar como contexto e disponibilizar a previsão. Formato: cachedContents/{cachedContent}
Exemplo de solicitação
Texto
Python
Node.js
Go
Concha
Kotlin
Swift
Dart
Java
Imagem
Python
Node.js
Go
Concha
Kotlin
Swift
Dart
Java
Áudio
Python
Node.js
Concha
Vídeo
Python
Node.js
Go
Concha
Python
Concha
Chat
Python
Node.js
Go
Concha
Kotlin
Swift
Dart
Java
Cache
Python
Node.js
Modelo ajustado
Python
Modo JSON
Python
Node.js
Go
Concha
Kotlin
Swift
Dart
Java
Execução de código
Python
Kotlin
Java
chamada de função
Python
Node.js
Concha
Kotlin
Swift
Dart
Java
Configuração de geração
Python
Node.js
Go
Concha
Kotlin
Swift
Dart
Java
Configurações de segurança
Python
Node.js
Go
Concha
Kotlin
Swift
Dart
Java
Instrução do sistema
Python
Node.js
Go
Concha
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 em streaming a partir do modelo que recebe um GenerateContentRequest
de entrada.
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árias interações, como chat, esse é um campo repetido que contém o histórico da conversa e a solicitação mais recente.
tools[]
object (Tool
)
Opcional. Uma lista de Tools
que o Model
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 da Model
. Os Tool
s aceitos são Function
e codeExecution
. Consulte os guias Chamada de função e Execução de código para saber mais.
toolConfig
object (ToolConfig
)
Opcional. Configuração de ferramenta para qualquer Tool
especificado na solicitação. Consulte o guia sobre chamadas de função para conferir um exemplo de uso.
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. Consulte o guia para ver informações detalhadas sobre as configurações de segurança disponíveis. Consulte também as Diretrizes de segurança para saber como incorporar considerações de segurança aos seus aplicativos de IA.
systemInstruction
object (Content
)
Opcional. Instruções do sistema definidas pelo desenvolvedor. 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 para usar como contexto e disponibilizar a previsão. Formato: cachedContents/{cachedContent}
Exemplo de solicitação
Texto
Python
Node.js
Go
Concha
Kotlin
Swift
Dart
Java
Imagem
Python
Node.js
Go
Concha
Kotlin
Swift
Dart
Java
Áudio
Python
Concha
Vídeo
Python
Node.js
Go
Concha
Python
Concha
Chat
Python
Node.js
Go
Concha
Kotlin
Swift
Dart
Java
Corpo da resposta
Se a solicitação for bem-sucedida, o corpo da resposta incluirá um fluxo de instâncias de GenerateContentResponse
.
GenerateContentResponse
Resposta do modelo com suporte a várias respostas candidatas.
As classificações de segurança e a filtragem de conteúdo são informadas para o comando em GenerateContentResponse.prompt_feedback
e para cada candidato em finishReason
e safetyRatings
. A API: - Retorna todos os candidatos solicitados ou nenhum deles - Não retorna nenhum candidato somente se houver algo de errado com o comando (verifique promptFeedback
) - Informa feedback sobre cada candidato em finishReason
e safetyRatings
.
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. Os metadados sobre as solicitações de geração o uso de tokens.
Representação JSON |
---|
{ "candidates": [ { object ( |
PromptFeedback
Um conjunto de metadados de feedback do comando especificado em GenerateContentRequest.content
.
blockReason
enum (BlockReason
)
Opcional. Se definido, a solicitação será bloqueada e nenhum candidato será retornado. Reformule o comando.
safetyRatings[]
object (SafetyRating
)
Classificações para segurança do comando. Existe no máximo uma classificação por categoria.
Representação JSON |
---|
{ "blockReason": enum ( |
BlockReason
Especifica o motivo pelo qual a solicitação foi bloqueada.
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. |
BLOCKLIST |
A solicitação foi bloqueada devido aos termos incluídos na lista de bloqueio de terminologia. |
PROHIBITED_CONTENT |
A solicitação foi bloqueada devido ao conteúdo proibido. |
UsageMetadata
Metadados sobre o uso do token da solicitação de geração.
promptTokenCount
integer
Número de tokens no comando. Quando cachedContent
está definido, esse ainda é o tamanho total efetivo do comando, o que 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 (o conteúdo em cache)
candidatesTokenCount
integer
Número total de tokens em todos os candidatos de resposta gerados.
totalTokenCount
integer
Contagem total de tokens para a solicitação de geração (comando + candidatos de resposta).
Representação JSON |
---|
{ "promptTokenCount": integer, "cachedContentTokenCount": integer, "candidatesTokenCount": integer, "totalTokenCount": integer } |
Candidato
- Representação JSON
- FinishReason
- GroundingAttribution
- AttributionSourceId
- GroundingPassageId
- SemanticRetrieverChunk
Um candidato de resposta gerado a partir do modelo.
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 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 de candidatos de resposta.
Representação JSON |
---|
{ "content": { object ( |
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 de resposta foi sinalizado por motivos de segurança. |
RECITATION |
O conteúdo do candidato de resposta foi sinalizado por motivos de recitação. |
LANGUAGE |
O conteúdo do candidato de resposta foi sinalizado por usar um idioma sem suporte. |
OTHER |
Motivo desconhecido. |
BLOCKLIST |
A geração do token foi interrompida porque o conteúdo contém termos proibidos. |
PROHIBITED_CONTENT |
A geração de tokens foi interrompida por conter conteúdo proibido. |
SPII |
A geração de token foi interrompida porque o conteúdo pode apresentar informações sensíveis de identificação pessoal (SPII, na sigla em inglês). |
MALFORMED_FUNCTION_CALL |
A chamada de função gerada pelo modelo é inválida. |
GroundingAttribution
Atribuição a uma fonte que contribuiu para uma resposta.
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.
Representação JSON |
---|
{ "sourceId": { object ( |
AttributionSourceId
Identificador da fonte que contribui para essa atribuição.
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.
Representação JSON |
---|
{ // Union field |
GroundingPassageId
Identificador de uma parte em um GroundingPassage
.
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
.
Representação JSON |
---|
{ "passageId": string, "partIndex": integer } |
SemanticRetrieverChunk
Identificador de uma Chunk
extraída pelo recuperador semântico especificado no GenerateAnswerRequest
usando SemanticRetrieverConfig
.
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
Representação JSON |
---|
{ "source": string, "chunk": string } |
CitationMetadata
Uma coleção de atribuições de fonte para um conteúdo.
citationSources[]
object (CitationSource
)
Citações de fontes para uma resposta específica.
Representação JSON |
---|
{
"citationSources": [
{
object ( |
CitationSource
Uma citação de uma fonte para parte de uma resposta específica.
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.
Representação JSON |
---|
{ "startIndex": integer, "endIndex": integer, "uri": string, "license": string } |
GenerationConfig
Opções de configuração para geração e saídas de modelos. Nem todos os parâmetros podem ser configurados para todos os modelos.
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 será interrompida na primeira aparição de um stop_sequence
. A sequência de parada não será incluída como parte da resposta.
responseMimeType
string
Opcional. Tipo MIME do texto candidato gerado. Os tipos MIME com suporte são: text/plain
(padrão): saída de texto. application/json
: resposta JSON nos candidatos de resposta. Consulte os documentos para ver uma lista de todos os tipos MIME de texto compatíveis.
responseSchema
object (Schema
)
Opcional. Esquema de saída do texto candidato gerado. Os esquemas precisam ser um subconjunto do esquema OpenAPI e podem ser objetos, primitivos ou matrizes.
Se definido, um responseMimeType
compatível também precisa ser definido. Tipos MIME compatíveis: application/json
: esquema para a resposta JSON. Consulte o guia de geração de texto JSON para mais detalhes.
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 uma resposta candidata.
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 a amostragem combinada de Top-k e Top-p (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 por Model
e é especificado pelo atributo Model.top_p
retornado da função getModel
. Um atributo topK
vazio indica que o modelo não aplica amostragem top-k e não permite a configuração de topK
nas solicitações.
topK
integer
Opcional. O número máximo de tokens a serem considerados na amostragem.
Os modelos do Gemini usam a amostragem de Top-p (núcleo) ou uma combinação de amostragem 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 por Model
e é especificado pelo atributo Model.top_p
retornado da função getModel
. Um atributo topK
vazio indica que o modelo não aplica amostragem top-k e não permite a configuração de topK
nas solicitações.
Representação JSON |
---|
{
"stopSequences": [
string
],
"responseMimeType": string,
"responseSchema": {
object ( |
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.
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?
Representação JSON |
---|
{ "category": enum ( |
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.
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.
Representação JSON |
---|
{ "category": enum ( |
HarmBlockThreshold
Bloquear com base em uma probabilidade de danos especificada ou superior.
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 NEGLIGÍVEL, BAIXO e MÉDIO será permitido. |
BLOCK_NONE |
Todo o conteúdo será permitido. |