生成内容 - CometAPI Documentation

POST

v1beta

models

{model}

{operator}

import os
from google import genai

client = genai.Client(
    api_key=os.environ["COMETAPI_KEY"],
    http_options={
        "api_version": "v1beta",
        "base_url": "https://api.cometapi.com",
    },
)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents='Explain how AI works in a few words',
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "AI learns patterns from massive amounts of data to make predictions, solve problems, and generate new content. \n\nIn short: **Data in → Patterns found → Smart predictions out.**"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 36,
    "thoughtsTokenCount": 388,
    "totalTokenCount": 433
  },
  "modelVersion": "gemini-3.8-flash"
}

通过 CometAPI 使用 Gemini 原生请求格式来生成文本、发送视频输入以及配置思考或工具。示例使用 gemini-3.8-flash。

使用 Google 的 GenerateContent API 参考了解字段定义和特定模型选项。本页展示 CometAPI 基础 URL、身份验证和请求示例。

支持使用 x-goog-api-key 和 Authorization: Bearer 请求头进行身份验证。

快速入门

要将 Google Gen AI SDK 或 HTTP 客户端与 CometAPI 配合使用，请配置基础 URL 和 API 密钥：

设置	Google 默认值	CometAPI
基础 URL	`generativelanguage.googleapis.com`	`api.cometapi.com`
API 密钥	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

使用 GenerateContent 文本生成指南获取原生 API 示例。更改基础 URL 时，请保持 generateContent 请求结构不变。

发送视频输入

将视频作为内容部分发送。根据视频的存储位置选择输入形式：

视频来源	请求部分	适用场景
本地视频文件	`inlineData`	视频足够小，可在 JSON 请求中以 base64 形式发送。
公开视频 URL	`fileData.fileUri`	视频可通过无需身份验证的公开 HTTPS URL 访问。

对于 REST 和 curl 请求，请使用 camelCase 字段名称，例如 inlineData.mimeType 和 fileData.fileUri。

此示例发送内联 MP4 数据。请将 <base64-encoded-mp4> 替换为视频的 base64 内容：

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "video/mp4",
            "data": "<base64-encoded-mp4>"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 2048,
    "thinkingConfig": {
      "thinkingLevel": "LOW"
    }
  }
}
EOF

此示例分析一段花朵绽放的公开 MP4 视频：

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 2048,
    "thinkingConfig": {
      "thinkingLevel": "LOW"
    }
  }
}
EOF

配置思考 (推理)

使用 thinkingConfig.thinkingLevel 指定推理深度。以下示例使用 LOW 和 MEDIUM。

思考级别
思考摘要

此示例将思考级别设为 LOW：

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "How does quantum computing work?"
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "LOW"
    }
  }
}
EOF

设置 includeThoughts 以请求思考摘要。当响应包含摘要时，其文本部分具有 thought: true：

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "What is the 10th Fibonacci number when F(0)=0 and F(1)=1? Briefly verify the result."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 4096,
    "thinkingConfig": {
      "thinkingLevel": "MEDIUM",
      "includeThoughts": true
    }
  }
}
EOF

thinkingBudget 是适用于兼容模型（包括 Gemini 2.5）的数值控制参数。请在 Gemini 3 示例中使用 thinkingLevel，且不要同时发送这两个控制参数。请参阅 Google 的思考指南了解特定模型的取值。

流式传输响应

使用 streamGenerateContent?alt=sse 接收 Server-Sent Events。每个 data: 行都包含一个 JSON GenerateContentResponse 对象：

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --no-buffer \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "Write a short poem about the stars"
        }
      ]
    }
  ]
}
EOF

设置系统指令

使用 systemInstruction 指导响应。此示例请求一个不含额外文本的方程式：

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "What is 2+2?"
        }
      ]
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are a math tutor. Answer with exactly one equation and no other text."
      }
    ]
  }
}
EOF

请求 JSON 输出

将 responseMimeType 设为 application/json，并提供 responseSchema。此示例请求一个包含名称和数值距离的行星数组：

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "Return a JSON array of 3 planets with name and average_distance_from_sun_au."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "ARRAY",
      "items": {
        "type": "OBJECT",
        "properties": {
          "name": {
            "type": "STRING",
            "description": "Name of the planet."
          },
          "average_distance_from_sun_au": {
            "type": "NUMBER",
            "description": "Average distance from the Sun, in astronomical units."
          }
        },
        "required": [
          "name",
          "average_distance_from_sun_au"
        ]
      }
    }
  }
}
EOF

使用 Google 搜索进行事实依据验证

添加一个 googleSearch 工具以请求搜索事实依据验证。此示例询问 UEFA EURO 2024 决赛的结果：

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "Use Google Search to find the winner and final score of the UEFA EURO 2024 final. Cite your sources."
        }
      ]
    }
  ],
  "tools": [
    {
      "googleSearch": {}
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 2048
  }
}
EOF

使用搜索时，检查候选项的 groundingMetadata，获取搜索查询、来源 URL，以及来源与响应文本之间的链接。

保留对话内容

对于多轮对话，请在 user 中发送此前的 model 内容。SDK 聊天示例会为你维护此历史记录。请在 contents 中包含这些内容。对于函数调用（Function Calling），请为每个 functionResponse 返回一个 functionCall，并包含匹配的 name 以及所有返回的 id。将此前的模型内容原样传回，包括 thoughtSignature 字段。该签名是不透明的；请勿根据显示的文本重建它。

响应示例

文本响应包含生成的内容和 Token 使用情况。此简化示例省略了可选字段：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "AI learns patterns from massive amounts of data to make predictions, solve problems, and generate new content. \n\nIn short: **Data in → Patterns found → Smart predictions out.**"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 36,
    "thoughtsTokenCount": 388,
    "totalTokenCount": 433
  },
  "modelVersion": "gemini-3.8-flash"
}

thoughtsTokenCount 会报告内部思考 Token，即使响应不包含思考摘要也是如此。请检查每个内容部分；响应可以包含文本、摘要或函数调用（Function Calling）。

比较请求格式

对于 Gemini 请求和响应字段，请选择原生端点。请参阅聊天补全了解与 OpenAI 兼容的格式。

字段	Gemini 原生	与 OpenAI 兼容的聊天
对话输入	`contents` ，包含 `parts`	`messages`
模型 ID	在请求路径中	`model` 在请求正文中
生成的内容	`candidates` ，包含 `content.parts`	`choices` ，包含 `message`

授权

x-goog-api-key

string

header

必填

Your CometAPI key passed via the x-goog-api-key header. Bearer token authentication (Authorization: Bearer $COMETAPI_KEY) is also supported.

路径参数

model

string

默认值:gemini-3.8-flash

必填

Gemini model ID. These examples use gemini-3.8-flash. See the Models page for available model IDs.

operator

enum<string>

默认值:generateContent

必填

Operation to perform. Use generateContent for a JSON response. For Server-Sent Events, select streamGenerateContent and set the separate alt query parameter to sse.

可用选项:

generateContent,

streamGenerateContent

查询参数

alt

enum<string>

Set to sse when the operator is streamGenerateContent. Omit this parameter for generateContent.

可用选项:

sse

请求体

application/json

contents

object[]

Conversation content. Each entry has an optional role (user or model) and a parts array. For tool results, preserve the complete preceding model content, including any thoughtSignature fields.

Show child attributes

systemInstruction

object

System instructions that guide the model's behavior across the entire conversation. Text only.

Show child attributes

tools

object[]

Tools available to the model during generation. Use googleSearch for search grounding.

Show child attributes

toolConfig

object

Configuration for tool usage, such as function calling mode.

Show child attributes

safetySettings

object[]

Safety filter settings. Override default thresholds for specific harm categories.

Show child attributes

generationConfig

object

Configuration for model generation behavior including temperature, output length, and response format.

Show child attributes

cachedContent

string

The name of cached content to use as context. Format: cachedContents/{id}. See the Gemini context caching documentation for details.

响应

200 - application/json

Successful response. For streaming requests, the response is a stream of SSE events, each containing a GenerateContentResponse JSON object prefixed with data:.

candidates

object[]

The generated response candidates.

Show child attributes

promptFeedback

object

Feedback on the prompt, including safety blocking information.

Show child attributes

usageMetadata

object

Token usage statistics for the request.

Show child attributes

modelVersion

string

The model version that generated this response.

createTime

string

The timestamp when this response was created (ISO 8601 format).

responseId

string

Unique identifier for this response.

最后修改于 2026年9月8日

import os
from google import genai

client = genai.Client(
    api_key=os.environ["COMETAPI_KEY"],
    http_options={
        "api_version": "v1beta",
        "base_url": "https://api.cometapi.com",
    },
)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents='Explain how AI works in a few words',
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "AI learns patterns from massive amounts of data to make predictions, solve problems, and generate new content. \n\nIn short: **Data in → Patterns found → Smart predictions out.**"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 36,
    "thoughtsTokenCount": 388,
    "totalTokenCount": 433
  },
  "modelVersion": "gemini-3.8-flash"
}

​快速入门

​发送视频输入

​配置思考 (推理)

​流式传输响应

​设置系统指令

​请求 JSON 输出

​使用 Google 搜索进行事实依据验证

​保留对话内容

​响应示例

​比较请求格式

授权

路径参数

查询参数

请求体

响应

快速入门

发送视频输入

配置思考 (推理)

流式传输响应

设置系统指令

请求 JSON 输出

使用 Google 搜索进行事实依据验证

保留对话内容

响应示例

比较请求格式