​

Google Vertex AI API: Generate Content

​

非流式：

POST https://api.agipower.ai/v1beta/models/{model}:generateContent

​

流式：

POST https://api.agipower.ai/v1beta/models/{model}:streamGenerateContent

​

Path parameters

​

provider string 必填

​

model string 必填

​

Request headers

​

Authorization string 必填

​

Content-Type string 必填

​

Request body

​

contents array<Content> 必填

​

role string 可选

• user：表示消息是由真人发送的，通常是用户生成的消息。
• model：表示消息是由模型生成的。

​

parts Part[] 必填

​

part

• text string可选 文本提示或代码段。
• inlineData Blob可选 原始字节中的内嵌数据。
  • mimeType string 可选 在 data 或 fileUri 字段中指定的文件的媒体类型。可接受的值包括：
    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
    • video/x-ms-wmv
  • data bytes 可选 原始字节中的内嵌数据。
• fileData FileData可选 存储在文件中的数据。
  • mimeType string 可选
  • fileUri string 可选 要包含在提示中的文件的 URI 或网址。
• functionCall FunctionCall可选 它包含表示 FunctionDeclaration.name 字段的字符串，以及包含模型预测的函数调用的所有参数的结构化 JSON 对象。
  • name string 可选 要调用的函数名称。
  • args Record<string,any> 可选 以 JSON 对象格式表示的函数参数和值。
• functionResponse FunctionResponse可选 FunctionCall 的结果输出，其中包含表示 FunctionDeclaration.name 字段的字符串和包含函数调用的任何输出的结构化 JSON 对象。它用作模型的上下文。
  • name string 可选 要调用的函数名称。
  • response Record<string,any> 可选 以 JSON 对象格式表示的函数响应。
• videoMetadata VideoMetadata 可选 对于视频输入，为视频的开始和结束偏移量（采用时长格式），以及视频的帧速率。
  • startOffset number 可选 视频开始偏移量（时长格式）。
  • endOffset number 可选 视频结束偏移量（时长格式）。
  • fps number 可选 视频帧速率。
• mediaResolution enum可选 控制输入媒体的处理方式。如果指定，则此配置会替换 generationConfig 中的 mediaResolution 设置。 LOW 会减少每个图片/视频的 token 数量，这可能会导致细节丢失，但允许在上下文中包含更长的视频。支持的值：HIGH、MEDIUM、LOW。

​

cachedContent string 可选

• projects/\{project\}/locations/\{location\}/cachedContents/\{cachedContent\}

​

tools array<Tool> 可选

​

toolConfig ToolConfig 可选

​

safetySettings array<SafetySetting> 可选

​

category string 必选

• HARM_CATEGORY_UNSPECIFIED： 未指定有害类别。
• HARM_CATEGORY_HATE_SPEECH：有害类别为仇恨言论。
• HARM_CATEGORY_HARASSMENT：有害类别为骚扰。
• HARM_CATEGORY_SEXUALLY_EXPLICIT：有害类别为露骨色情内容。
• HARM_CATEGORY_DANGEROUS_CONTENT：有害类别为危险内容。

​

threshold string 必选

• OFF：在所有类别都已停用的情况下关闭安全设置
• BLOCK_NONE：全部不屏蔽。
• BLOCK_ONLY_HIGH：仅屏蔽高阈值内容（即屏蔽较少的内容）。
• BLOCK_MEDIUM_AND_ABOVE：屏蔽中等阈值及以上的内容。
• BLOCK_LOW_AND_ABOVE：屏蔽低阈值及以上的内容（即屏蔽较多的内容）。
• HARM_BLOCK_THRESHOLD_UNSPECIFIED：未指定的有害屏蔽阈值。

​

method string 可选

• HARM_BLOCK_METHOD_UNSPECIFIED：未指定有害内容屏蔽方法。
• SEVERITY：有害内容屏蔽方法同时使用可能性得分和严重程度得分。
• PROBABILITY：有害内容屏蔽方法使用概率得分。

​

generationConfig GenerationConfig 可选

​

temperature number 可选

​

topP number 可选

​

topK integer 可选

​

candidateCount integer 可选

​

maxOutputTokens integer 可选

​

stopSequences array<string> 可选

​

presencePenalty number 可选

​

frequencyPenalty number 可选

​

seed integer 可选

​

responseMimeType string 可选

• text/plain（默认）：纯文本输出
• application/json：以 JSON 形式输出（用于结构化输出/JSON mode）
• text/x.enum：分类任务中按 responseSchema 定义输出枚举值

​

responseSchema Schema 可选

​

Schema 对象字段

• type enum (Type) 必填 数据类型。支持值：
  • STRING：字符串类型，支持 enum、format（如 date-time、email、byte）、minLength、maxLength、pattern 等约束。
  • INTEGER：整数类型，支持 format（如 int32、int64）、minimum、maximum 等约束。
  • NUMBER：浮点数类型，支持 format（如 float、double）、minimum、maximum 等约束。
  • BOOLEAN：布尔类型。
  • ARRAY：数组类型，支持 items、minItems、maxItems 等约束。
  • OBJECT：对象类型，支持 properties、required、propertyOrdering、nullable 等约束。
• format string 可选 数据格式补充。对 NUMBER 可用 float、double；对 INTEGER 可用 int32、int64；对 STRING 可用 email、byte、date、date-time、password 等。
• description string 可选 属性/字段的文本描述，帮助模型理解需要生成的内容。
• enum array<string> 可选 枚举值列表；模型只能从中选择一个输出。通常配合 type: STRING 使用。
• items Schema 可选 当 type 为 ARRAY 时，指定数组元素的 schema。
• properties map<string, Schema> 可选 当 type 为 OBJECT 时，定义对象中各属性及其 schema。
• required array<string> 可选 对象中必填属性列表。
• propertyOrdering array<string> 可选 指定对象属性的输出顺序。
• nullable boolean 可选 是否允许值为 null。
• minimum number 可选 当 type 为 INTEGER 或 NUMBER 时，指定允许的最小值。
• maximum number 可选 当 type 为 INTEGER 或 NUMBER 时，指定允许的最大值。
• minItems integer 可选 当 type 为 ARRAY 时，指定数组最少元素数。
• maxItems integer 可选 当 type 为 ARRAY 时，指定数组最多元素数。
• minLength integer 可选 当 type 为 STRING 时，指定字符串最小长度。
• maxLength integer 可选 当 type 为 STRING 时，指定字符串最大长度。
• pattern string 可选 当 type 为 STRING 时，指定正则约束。例如："^[\\w\\s,.-]+$"。
• title string 可选 schema 的标题标签。
• anyOf array<Schema> 可选 联合类型 / 条件类型：值必须满足 anyOf 中至少一个 schema。oneOf 也会按照 anyOf 的语义被解释。

注意：Schema 复杂度过高（属性名过长、enum 值过多、嵌套层级过深等）可能导致 InvalidArgument: 400 错误。建议尽量简化 schema。不支持循环引用（仅在非必填属性中允许有限展开）。

​

responseJsonSchema object 可选

​

responseLogprobs boolean 可选

​

logprobs integer 可选

​

responseModalities array<enum> 可选

• TEXT：文本输出（默认）。
• IMAGE：图像输出；使用时必须同时包含 TEXT，即 ["TEXT", "IMAGE"]。仅支持部分模型（如 gemini-2.5-flash-image、gemini-3-pro-image-preview）。
• AUDIO：音频输出；主要用于 Live API（实时流式）场景。

​

audioTimestamp boolean 可选

​

thinkingConfig ThinkingConfig 可选

• thinkingBudget integer 可选 thinking 的 token 预算（适用于 Gemini 2.5 系列）。不同模型范围：
  • Gemini 2.5 Pro：128 ~ 32768（不可关闭 thinking）
  • Gemini 2.5 Flash：0 ~ 24576（0 = 关闭 thinking）
  • Gemini 2.5 Flash Lite：512 ~ 24576
  设为 -1 表示动态 thinking（模型根据请求复杂度自动调整预算）。不传时默认由模型自动控制。

  注意：不可与 thinkingLevel 同时使用；thinkingBudget 仅适用于 Gemini 2.5 系列。

• thinkingLevel enum (ThinkingLevel) 可选 控制内部推理强度（适用于 Gemini 3 系列，推荐用法）。支持值：
  • THINKING_LEVEL_UNSPECIFIED：未指定，使用模型默认的动态行为。
  • MINIMAL：尽可能少地使用 thinking token（仅 Gemini 3 Flash 支持）。
  • LOW：低推理强度，适合简单任务。
  • MEDIUM：中等推理强度（仅 Gemini 3 Flash 支持）。
  • HIGH：高推理强度（Gemini 3 默认值），适合数学、代码、逻辑分析等复杂任务。

  注意：不可与 thinkingBudget 同时使用；thinkingLevel 仅适用于 Gemini 3 系列。

• includeThoughts boolean 可选 是否在响应中返回思考过程摘要。设为 true 时，在可用的情况下会返回 thought 摘要。属于 best-effort 能力，即使设置了也不保证一定会返回 thoughts。

​

mediaResolution enum (MediaResolution) 可选

• MEDIA_RESOLUTION_UNSPECIFIED：未指定，使用模型默认设置（不同代模型默认 token 数不同）。
• MEDIA_RESOLUTION_LOW：低分辨率，更少 token，更快更省成本。
• MEDIA_RESOLUTION_MEDIUM：中分辨率，质量与成本的平衡。
• MEDIA_RESOLUTION_HIGH：高分辨率，更多 token，更精细。
• MEDIA_RESOLUTION_ULTRA_HIGH：超高分辨率（仅 Gemini 3 支持）。

Gemini 3 参考 token 数（图像）：ULTRA_HIGH ≈ 2240、HIGH ≈ 1120、MEDIUM ≈ 560。

​

speechConfig SpeechConfig 可选

• voiceConfig VoiceConfig 可选 单一语音配置（与 multiSpeakerVoiceConfig 互斥）。
  • prebuiltVoiceConfig PrebuiltVoiceConfig 可选 预置语音配置。
    • voiceName string 可选 预置语音名称（如 Kore、Puck、Charon 等）。
  • replicatedVoiceConfig ReplicatedVoiceConfig 可选 复刻语音配置（通过音频样本复刻语音）。
    • mimeType string 可选 语音样本的 MIME 类型；目前仅支持 audio/wav（16-bit signed little-endian，24kHz 采样率）。
    • voiceSample string(bytes) 可选 自定义语音样本（base64 编码）。
• multiSpeakerVoiceConfig MultiSpeakerVoiceConfig 可选 多人语音配置（与 voiceConfig 互斥）；用于多角色 TTS 场景。
  • speakerVoiceConfigs array<SpeakerVoiceConfig> 每个说话人的语音配置列表。
    • speaker string：说话人名称。
    • voiceConfig VoiceConfig：该说话人使用的语音配置（结构同上）。
• languageCode string 可选 语音输出的语言代码（如 en-US）。

​

routingConfig RoutingConfig 可选

注意：此字段已废弃（deprecated），Google 建议使用 modelConfig 替代。

• autoMode AutoRoutingMode 可选 自动路由：由预训练的路由模型和用户偏好共同决定路由。
  • modelRoutingPreference enum (ModelRoutingPreference) 可选 路由偏好。支持值：BALANCED 等。
• manualMode ManualRoutingMode 可选 手动路由：直接指定目标模型。
  • modelName string 可选 目标模型名称（如 gemini-1.5-pro-001）。

​

imageConfig ImageConfig 可选

• aspectRatio string 可选 生成图像的宽高比。支持值：1:1、2:3、3:2、3:4、4:3、9:16、16:9、21:9；部分模型还支持 4:5、5:4。
• imageSize string 可选 生成图像的尺寸。支持值：1K、2K、4K。默认 1K。
• outputCompressionQuality number 可选 生成图像的压缩质量（仅 image/jpeg 格式适用）。
• outputMimeType string 可选 生成图像的 MIME 类型。

​

enableAffectiveDialog boolean 可选

​

systemInstruction Content 可选

​

Response（非流式）

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": string
          }
        ]
      },
      "finishReason": enum (FinishReason),
      "safetyRatings": [
        {
          "category": enum (HarmCategory),
          "probability": enum (HarmProbability),
          "blocked": boolean
        }
      ],
      "citationMetadata": {
        "citations": [
          {
            "startIndex": integer,
            "endIndex": integer,
            "uri": string,
            "title": string,
            "license": string,
            "publicationDate": {
              "year": integer,
              "month": integer,
              "day": integer
            }
          }
        ]
      },
      "avgLogprobs": double,
      "logprobsResult": {
        "topCandidates": [
          {
            "candidates": [
              {
                "token": string,
                "logProbability": float
              }
            ]
          }
        ],
        "chosenCandidates": [
          {
            "token": string,
            "logProbability": float
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": integer,
    "candidatesTokenCount": integer,
    "totalTokenCount": integer

    // （可能出现的扩展统计）
    // "cachedContentTokenCount": integer,
    // "thoughtsTokenCount": integer,
    // "toolUsePromptTokenCount": integer,
    // "promptTokensDetails": [...],
    // "candidatesTokensDetails": [...],
    // "toolUsePromptTokensDetails": [...]
  },
  "modelVersion": string,
  "createTime": string,
  "responseId": string
}

​

candidates array<Candidate>

​

Candidate.content object

• content.parts array
  内容分块数组。
  • parts[].text string
    生成的文本。

​

Candidate.finishReason enum (FinishReason)

• FINISH_REASON_STOP：自然停止点或命中 stop 序列
• FINISH_REASON_MAX_TOKENS：达到请求指定 token 上限
• FINISH_REASON_SAFETY：因安全原因停止（若过滤器阻止输出，则 Candidate.content 为空）
• FINISH_REASON_RECITATION：因未经授权的引用被标记而停止
• FINISH_REASON_BLOCKLIST：包含禁用词
• FINISH_REASON_PROHIBITED_CONTENT：包含被禁止内容（例如 CSAM）
• FINISH_REASON_IMAGE_PROHIBITED_CONTENT：提示中的图片包含被禁止内容
• FINISH_REASON_NO_IMAGE：提示应包含图片但未提供
• FINISH_REASON_SPII：包含敏感个人身份信息 (SPII)
• FINISH_REASON_MALFORMED_FUNCTION_CALL：函数调用格式错误且不可解析
• FINISH_REASON_OTHER：其他原因
• FINISH_REASON_UNSPECIFIED：未指定

​

Candidate.safetyRatings array<SafetyRating>

• safetyRatings[].category enum (HarmCategory)
  安全类别（例如：HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_DANGEROUS_CONTENT）。
• safetyRatings[].probability enum (HarmProbability)
  有害概率级别：NEGLIGIBLE / LOW / MEDIUM / HIGH 等。
• safetyRatings[].blocked boolean
  指示模型输入或输出是否被阻止。

​

Candidate.citationMetadata object

• citationMetadata.citations array<Citation>
  • citations[].startIndex integer
    引用在 content 中的起始位置；以 UTF-8 响应的字节为单位计算。
  • citations[].endIndex integer
    引用在 content 中的结束位置；同样以字节为单位。
  • citations[].uri string
    引用来源网址（官网说明字段为 url/网址；示例结构里该字段名为 uri）。
  • citations[].title string
    引用来源标题。
  • citations[].license string
    引用关联的许可。
  • citations[].publicationDate object
    引用发布日期（有效格式：YYYY / YYYY-MM / YYYY-MM-DD）。
    • publicationDate.year integer
    • publicationDate.month integer
    • publicationDate.day integer

​

Candidate.avgLogprobs double

​

Candidate.logprobsResult object

• logprobsResult.topCandidates array
  • topCandidates[].candidates array
    • candidates[].token string：token（字符/字词/短语等）
    • candidates[].logProbability float：该 token 的对数概率（置信度）
• logprobsResult.chosenCandidates array
  • chosenCandidates[].token string
  • chosenCandidates[].logProbability float

​

usageMetadata object

• usageMetadata.promptTokenCount integer
  请求中的 token 数。
• usageMetadata.candidatesTokenCount integer
  响应中的 token 数。
• usageMetadata.totalTokenCount integer
  请求 + 响应的 token 总数。
• （可能出现）thoughtsTokenCount / toolUsePromptTokenCount / cachedContentTokenCount 及各模态明细。

注：官网补充说明——出于结算目的，Gemini 3 Pro 及更高版本模型处理“文档输入”消耗的 token 会计为图片 token。

​

modelVersion string

​

createTime string

​

responseId string

​

Response（流式：每个 stream chunk 的响应正文）

{
  "candidates": [
    {
      "index": integer,
      "content": {
        "role": string,
        "parts": [
          {
            "thought": boolean,
            "thoughtSignature": string, // bytes(base64)
            "mediaResolution": {
              "level": enum,
              "numTokens": integer
            },

            // Union field data（以下字段同一 time 只会出现一个）
            "text": string,
            "inlineData": { "mimeType": string, "data": string, "displayName": string },
            "fileData": { "mimeType": string, "fileUri": string, "displayName": string },
            "functionCall": {
              "id": string,
              "name": string,
              "args": object,
              "partialArgs": [
                {
                  "jsonPath": string,
                  "stringValue": string,
                  "numberValue": number,
                  "boolValue": boolean,
                  "nullValue": string,
                  "willContinue": boolean
                }
              ],
              "willContinue": boolean
            },
            "functionResponse": {
              "id": string,
              "name": string,
              "response": object,
              "parts": [
                {
                  "inlineData": { /* bytes blob */ },
                  "fileData": { /* file ref */ }
                }
              ],
              "scheduling": enum,
              "willContinue": boolean
            },
            "executableCode": { "language": enum, "code": string },
            "codeExecutionResult": { "outcome": enum, "output": string },

            // Union field metadata（仅在 inlineData/fileData 为视频时）
            "videoMetadata": {
              "startOffset": string,
              "endOffset": string,
              "fps": number
            }
          }
        ]
      },
      "avgLogprobs": number,
      "logprobsResult": {
        "topCandidates": [
          {
            "candidates": [
              { "token": string, "tokenId": integer, "logProbability": number }
            ]
          }
        ],
        "chosenCandidates": [
          { "token": string, "tokenId": integer, "logProbability": number }
        ]
      },
      "finishReason": enum,
      "safetyRatings": [
        { "category": enum, "probability": enum, "blocked": boolean }
      ],
      "citationMetadata": {
        "citations": [
          {
            "startIndex": integer,
            "endIndex": integer,
            "uri": string,
            "title": string,
            "license": string,
            "publicationDate": { "year": integer, "month": integer, "day": integer }
          }
        ]
      },
      "groundingMetadata": {
        "webSearchQueries": [ string ],
        "retrievalQueries": [ string ],
        "groundingChunks": [
          {
            "web": { "uri": string, "title": string, "domain": string },
            "retrievedContext": object,
            "maps": object
          }
        ],
        "groundingSupports": [ object ],
        "sourceFlaggingUris": [ object ],
        "searchEntryPoint": { "renderedContent": string, "sdkBlob": string },
        "retrievalMetadata": { "googleSearchDynamicRetrievalScore": number },
        "googleMapsWidgetContextToken": string
      },
      "urlContextMetadata": {
        "urlMetadata": [
          { "retrievedUrl": string, "urlRetrievalStatus": enum }
        ]
      },
      "finishMessage": string
    }
  ],
  "modelVersion": string,
  "createTime": string,
  "responseId": string,
  "promptFeedback": {
    "blockReason": enum,
    "blockReasonMessage": string,
    "safetyRatings": [
      { "category": enum, "probability": enum, "blocked": boolean }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": integer,
    "candidatesTokenCount": integer,
    "totalTokenCount": integer

    // （可能出现的扩展统计）
    // "cachedContentTokenCount": integer,
    // "thoughtsTokenCount": integer,
    // "toolUsePromptTokenCount": integer,
    // "promptTokensDetails": [...],
    // "candidatesTokensDetails": [...],
    // "toolUsePromptTokensDetails": [...]
  }
}

promptFeedback：只会在第一个 stream chunk 返回，并且只在 因内容违规导致没有生成任何 candidates 时出现。
finishMessage：仅当 finishReason 有值时才返回。

​

candidates array<Candidate>

​

Candidate.index integer

​

Candidate.content object

content.role string

content.parts array<Part>

​

Part object（content.parts[]）

​

Part.thought boolean

​

Part.thoughtSignature string(bytes)

​

Part.mediaResolution PartMediaResolution

• mediaResolution.level enum (PartMediaResolutionLevel)：LOW / MEDIUM / HIGH / ULTRA_HIGH / UNSPECIFIED。
• mediaResolution.numTokens integer：期望媒体 token 序列长度。

​

Part.data（Union）同一 part 只会出现一个

Part.text string

Part.inlineData Blob

• inlineData.mimeType string：IANA MIME Type。
• inlineData.data string(bytes)：base64 bytes。
• inlineData.displayName string：可选展示名（部分场景才返回）。

Part.fileData FileData

• fileData.mimeType string：IANA MIME Type。
• fileData.fileUri string：文件 URI。
• fileData.displayName string：可选展示名。

Part.functionCall FunctionCall

• functionCall.id string：函数调用 id（用于和 functionResponse 匹配）。
• functionCall.name string：函数名。
• functionCall.args object：函数参数（JSON object）。
• functionCall.partialArgs array<PartialArg>：流式函数参数增量（部分 API/模式可用）。
• functionCall.willContinue boolean：是否后续还有该 FunctionCall 的增量片段。

PartialArg（用于 functionCall.partialArgs）

• jsonPath string：指向正在增量传输的参数路径（RFC 9535）。
• stringValue / numberValue / boolValue / nullValue：本次增量的值（四选一）。
• willContinue boolean：该 jsonPath 是否还有后续增量。

Part.functionResponse FunctionResponse

• functionResponse.id string：对应的 functionCall.id。
• functionResponse.name string：函数名（与 functionCall.name 匹配）。
• functionResponse.response object：函数返回（JSON object；约定 output/error）。
• functionResponse.parts array<FunctionResponsePart>：函数响应的多 part 形式（可包含文件/内联数据）。
• functionResponse.scheduling enum (FunctionResponseScheduling)：SILENT / WHEN_IDLE / INTERRUPT / …
• functionResponse.willContinue boolean：是否还有后续响应片段。

Part.executableCode ExecutableCode

• executableCode.language enum (Language)：如 PYTHON。
• executableCode.code string：代码字符串。

Part.codeExecutionResult CodeExecutionResult

• codeExecutionResult.outcome enum (Outcome)：OUTCOME_OK / OUTCOME_FAILED / OUTCOME_DEADLINE_EXCEEDED。
• codeExecutionResult.output string：stdout 或错误信息。

​

Part.metadata（Union）

Part.videoMetadata VideoMetadata

• videoMetadata.startOffset string：起始偏移。
• videoMetadata.endOffset string：结束偏移。
• videoMetadata.fps number：帧率。

​

Candidate.avgLogprobs number

​

Candidate.logprobsResult LogprobsResult

• logprobsResult.topCandidates array<LogprobsResultTopCandidates>：每步 top token 列表。
  • topCandidates[].candidates array<LogprobsResultCandidate>：按 logProbability 降序。
• logprobsResult.chosenCandidates array<LogprobsResultCandidate>：每步最终采样/选择的 token。
• LogprobsResultCandidate.token / tokenId / logProbability：token、tokenId、对数概率。

​

Candidate.finishReason enum (FinishReason)

• STOP / MAX_TOKENS / SAFETY / RECITATION / BLOCKLIST / PROHIBITED_CONTENT / SPII / MALFORMED_FUNCTION_CALL / OTHER / FINISH_REASON_UNSPECIFIED …

​

Candidate.safetyRatings array<SafetyRating>

• safetyRatings[].category enum (HarmCategory)：如 HATE_SPEECH / SEXUALLY_EXPLICIT / DANGEROUS_CONTENT / HARASSMENT / CIVIC_INTEGRITY …
• safetyRatings[].probability enum (HarmProbability)：NEGLIGIBLE / LOW / MEDIUM / HIGH …
• safetyRatings[].blocked boolean：是否因该 rating 被过滤。

另外一些 API/SDK 还会给出 probabilityScore / severity / severityScore 等更细粒度字段（不一定在所有 Vertex REST 输出中出现）。

​

Candidate.citationMetadata CitationMetadata

• citationMetadata.citations array<Citation>
  • citations[].startIndex integer：引用起始位置
  • citations[].endIndex integer：引用结束位置
  • citations[].uri string：来源 URL/URI
  • citations[].title string：来源标题
  • citations[].license string：许可
  • citations[].publicationDate \{year,month,day\}：发布日期

​

Candidate.groundingMetadata GroundingMetadata

• groundingMetadata.webSearchQueries string[]：用于 Google Search 的 query。
• groundingMetadata.retrievalQueries string[]：检索工具实际执行的 query。
• groundingMetadata.groundingChunks array<GroundingChunk>：证据片段。
  • groundingChunks[].web \{uri,title,domain\}：网页证据。
  • groundingChunks[].retrievedContext / maps：其他来源证据（对象结构依来源而定）。
• groundingMetadata.searchEntryPoint \{renderedContent,sdkBlob\}：搜索入口信息。
• groundingMetadata.retrievalMetadata \{googleSearchDynamicRetrievalScore\}：检索相关元信息。
• 以及 sourceFlaggingUris / googleMapsWidgetContextToken 等（Google Maps grounding 时出现）。

​

Candidate.urlContextMetadata UrlContextMetadata

• urlContextMetadata.urlMetadata array<UrlMetadata>：URL 列表。
  • urlMetadata[].retrievedUrl string：实际被检索的 URL。
  • urlMetadata[].urlRetrievalStatus enum (UrlRetrievalStatus)：SUCCESS / ERROR / PAYWALL / UNSAFE / UNSPECIFIED。

​

Candidate.finishMessage string

​

modelVersion string

​

createTime string

​

responseId string

​

promptFeedback object

• promptFeedback.blockReason enum (BlockedReason)：阻断原因。
• promptFeedback.blockReasonMessage string：可读原因（不一定所有环境支持）。
• promptFeedback.safetyRatings array<SafetyRating>：prompt 维度安全评分。

​

usageMetadata object

• usageMetadata.promptTokenCount integer：prompt token 数。
• usageMetadata.candidatesTokenCount integer：候选输出 token 总数。
• usageMetadata.totalTokenCount integer：总 token 数。
• （可能出现）thoughtsTokenCount / toolUsePromptTokenCount / cachedContentTokenCount 及各模态明细。

import { GoogleGenAI } from "@google/genai";

const client = GoogleGenAI({
  apiKey: "$AGIPower_API_KEY",
  vertexai: true,
  httpOptions: {
    baseUrl: "https://api.agipower.ai",
    apiVersion: "v1",
  },
});

const response = await client.models.generateContent({
  model: "google/gemini-2.5-pro",
  contents: "How does AI work?",
});
console.log(response);

from google import genai
from google.genai import types

client = genai.Client(
    api_key="$AGIPower_API_KEY",
    vertexai=True,
    http_options=types.HttpOptions(
        api_version='v1',
        base_url='https://api.agipower.ai'
    ),
)

response = client.models.generate_content(
    model="google/gemini-2.5-pro",
    contents="How does AI work?"
)
print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Of course. This is a fantastic question. Let's break down how AI works using a simple analogy and then add the technical details.\n\n### The Simple Analogy: Teaching a Child to Recognize a Cat\n\nImagine you're teaching a very young child what a \"cat\" is. You don't write down a long list of rules like \"a cat has pointy ears, four legs, a tail, and whiskers.\" Why? Because some cats have folded ears, some might be missing a leg, and a dog also fits that description.\n\nInstead, you do this:\n\n1.  **Show Examples:** You show the child hundreds of pictures. You point and say, \"That's a cat.\" \"That's also a cat.\" \"This is *not* a cat; it's a dog.\"\n2.  **Let Them Guess:** You show them a new picture and ask, \"Is this a cat?\"\n3.  **Give Feedback:** If they're right, you say \"Yes, good job!\" If they're wrong, you say \"No, that's a fox.\"\n\nOver time, the child's brain, without being told the specific rules, starts to recognize the *patterns* that make a cat a cat. They build an internal, intuitive understanding.\n\n**AI works in almost the exact same way.** It's a system designed to learn patterns from data without being explicitly programmed with rules.\n\n---\n\n### The Core Components of How AI Works\n\nNow, let's replace the child with a computer program. The process has three key ingredients:\n\n#### 1. Data (The Pictures)\n\nThis is the most critical ingredient. AI is fueled by data. For our example, this would be a massive dataset of thousands or millions of images, each one labeled by a human: \"cat,\" \"dog,\" \"hamster,\" etc.\n\n*   **More Data is Better:** The more examples the AI sees, the better it gets at identifying the patterns.\n*   **Good Data is Crucial:** The data must be accurate and diverse. If you only show it pictures of black cats, it will struggle to recognize a white cat.\n\n#### 2. Model / Algorithm (The Child's Brain)\n\nThis is the mathematical framework that learns from the data. Think of it as the \"engine\" that finds the patterns. When you hear terms like **\"Neural Network,\"** this is what they're referring to.\n\nA neural network is inspired by the human brain. It's made of interconnected digital \"neurons\" organized in layers.\n\n*   **Input Layer:** Takes in the raw data (e.g., the pixels of an image).\n*   **Hidden Layers:** This is where the magic happens. Each layer recognizes increasingly complex patterns. The first layer might learn to spot simple edges and colors. The next might combine those to recognize shapes like ears and tails. A deeper layer might combine those shapes to recognize a \"cat face.\"\n*   **Output Layer:** Gives the final answer (e.g., a probability score: \"95% chance this is a cat, 3% dog, 2% fox\").\n\n#### 3. The Training Process (Learning from Feedback)\n\nThis is where the **Model** learns from the **Data**. It's an automated version of showing pictures and giving feedback.\n\n1.  **Prediction (The Guess):** The model is given an input (an image of a cat) and makes a random guess. Early on, its internal settings are all random, so its guess will be wild—it might say \"50% car, 50% dog.\"\n2.  **Compare (Check the Answer):** The program compares its prediction to the correct label (\"cat\"). It then calculates its \"error\" or \"loss\"—a measure of how wrong it was.\n3.  **Adjust (Learn):** This is the key step. The algorithm uses a mathematical process (often called **\"backpropagation\"** and **\"gradient descent\"**) to slightly adjust the millions of internal connections in the neural network. The adjustments are tiny, but they are specifically designed to make the model's guess *less wrong* the next time it sees that same image.\n4.  **Repeat:** This process is repeated **millions or billions of times** with all the data. Each time, the model gets a little less wrong. Over many cycles, these tiny adjustments cause the network to get incredibly accurate at recognizing the patterns it's being shown.\n\nAfter training is complete, you have a **\"trained model.\"** You can now give it brand new data it has never seen before, and it will be able to make accurate predictions.\n\n---\n\n### Major Types of AI Learning\n\nWhile the above is the most common method, there are three main ways AI learns:\n\n**1. Supervised Learning (Learning with an Answer Key)**\nThis is the \"cat\" example we just used. The AI is \"supervised\" because it's trained on data that is already labeled with the correct answers.\n*   **Examples:** Spam filters (emails labeled \"spam\" or \"not spam\"), predicting house prices (houses with known prices), language translation.\n\n**2. Unsupervised Learning (Finding Patterns on its Own)**\nThis is like giving the AI a giant pile of data with *no labels* and asking it to \"find interesting patterns.\" The AI might group the data into clusters based on hidden similarities.\n*   **Examples:** Customer segmentation (finding groups of customers with similar buying habits), identifying anomalies in a computer network.\n\n**3. Reinforcement Learning (Learning through Trial and Error)**\nThis is how you train an AI to play a game or control a robot. The AI takes an action in an environment and receives a reward or a penalty. Its goal is to maximize its total reward over time.\n*   **Examples:** An AI learning to play chess (it gets a reward for winning the game), a robot learning to walk (it gets a reward for moving forward without falling), self-driving car simulations.\n\n### Summary\n\nSo, \"How does AI work?\"\n\n**At its core, modern AI is a system that learns to recognize incredibly complex patterns by processing vast amounts of data, making guesses, and correcting its errors over and over again until it becomes highly accurate.**\n\nIt's less about being \"intelligent\" in a human sense and more about being a phenomenally powerful pattern-matching machine."
          }
        ]
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.4167558059635994
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 1353,
    "totalTokenCount": 2794,
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 5
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 1353
      }
    ],
    "thoughtsTokenCount": 1436
  },
  "modelVersion": "google/gemini-2.5-pro",
  "createTime": "2026-01-29T08:40:38.791866Z",
  "responseId": "Bh17abqqMOSS4_UPqqeqoAc"
}