產生內容

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-flash-preview",
    contents="Explain how AI works in a few words",
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "<string>",
        "parts": [
          {
            "text": "<string>",
            "functionCall": {
              "name": "<string>",
              "args": {}
            },
            "inlineData": {
              "mimeType": "<string>",
              "data": "<string>"
            },
            "thought": true
          }
        ]
      },
      "safetyRatings": [
        {
          "category": "<string>",
          "probability": "<string>",
          "blocked": true
        }
      ],
      "citationMetadata": {
        "citationSources": [
          {
            "startIndex": 123,
            "endIndex": 123,
            "uri": "<string>",
            "license": "<string>"
          }
        ]
      },
      "tokenCount": 123,
      "avgLogprobs": 123,
      "groundingMetadata": {
        "groundingChunks": [
          {
            "web": {
              "uri": "<string>",
              "title": "<string>"
            }
          }
        ],
        "groundingSupports": [
          {
            "groundingChunkIndices": [
              123
            ],
            "confidenceScores": [
              123
            ],
            "segment": {
              "startIndex": 123,
              "endIndex": 123,
              "text": "<string>"
            }
          }
        ],
        "webSearchQueries": [
          "<string>"
        ]
      },
      "index": 123
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "<string>",
        "probability": "<string>",
        "blocked": true
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 123,
    "candidatesTokenCount": 123,
    "totalTokenCount": 123,
    "trafficType": "<string>",
    "thoughtsTokenCount": 123,
    "promptTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ]
  },
  "modelVersion": "<string>",
  "createTime": "<string>",
  "responseId": "<string>"
}

CometAPI 支援 Gemini 原生 API 格式，讓你能完整使用 Gemini 專屬功能，例如思考控制、Google Search grounding、原生圖片生成模態等。當你需要 OpenAI 相容聊天端點無法提供的能力時，請使用此端點。

請使用 Google 官方的 GenerateContent API reference 作為完整請求欄位、回應結構描述與 Gemini 模型特定行為的權威來源。此 CometAPI 頁面說明如何透過 CometAPI 傳送該原生請求格式。

隨著 Google 更新原生 API，Gemini 的請求參數與回應欄位可能會變更。請查閱 Gemini 文字生成文件以取得最新且完整的參數清單與供應商特定行為。

驗證同時支援 x-goog-api-key 與 Authorization: Bearer 標頭。

快速開始

若要搭配 CometAPI 使用任何 Gemini SDK 或 HTTP 用戶端，請替換 base URL 與 API key：

設定	Google 預設值	CometAPI
Base URL	`generativelanguage.googleapis.com`	`api.cometapi.com`
API key	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

傳送影片輸入

Gemini generateContent 可接受影片作為內容部分。請根據影片的儲存位置選擇輸入形式：

影片來源	請求部分	使用時機
本機影片檔案	`inlineData`	影片夠小，可作為 base64 置於 JSON 請求中傳送。
公開影片 URL	`fileData.fileUri`	影片可透過不需要驗證的公開 HTTPS URL 取得。

對於 REST 與 curl 請求，請使用 Gemini 的 camelCase 欄位名稱，例如 inlineData.mimeType 與 fileData.fileUri。不要將 URL 媒體以 file_data.file_uri 傳送。

此範例會讀取本機 MP4 檔案，將其編碼為 base64，並在請求主體中傳送：

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_PATH="./your_video.mp4"
VIDEO_B64=$(base64 < "$VIDEO_PATH" | tr -d '\n')

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-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": "${VIDEO_B64}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF

此範例會使用 fileData.fileUri 傳送公開的 MP4 URL：

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_URL="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-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": "${VIDEO_URL}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF

CometAPI 不建議為此端點使用獨立的 Gemini Files API 上傳流程。請直接在 generateContent 請求中使用 inlineData 或 fileData.fileUri 傳送媒體。

設定 thinking（推理）

Gemini 模型可以在產生回應之前先進行內部推理。控制方式取決於模型世代。

Gemini 3 (thinkingLevel)
Gemini 2.5 (thinkingBudget)

Gemini 3 模型使用 thinkingLevel 來控制推理深度。可用層級：MINIMAL、LOW、MEDIUM、HIGH。除非你明確需要不同的 Gemini 3 變體，否則請使用 gemini-3-flash-preview 作為預設範例模型。

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Explain quantum physics simply."}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingLevel": "LOW"}
    }
  }'

Gemini 2.5 模型使用 thinkingBudget 進行更細緻的 Token 層級控制：

0 — 停用 thinking
-1 — 動態（由模型決定，預設值）
> 0 — 指定的 Token 預算（例如：1024、2048）

curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Solve this logic puzzle step by step."}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingBudget": 2048}
    }
  }'

在 Gemini 2.5 模型中使用 thinkingLevel（或在 Gemini 3 模型中使用 thinkingBudget）可能會導致錯誤。請針對你的模型版本使用正確的參數。

串流回應

若要在模型產生內容時接收 Server-Sent Events，請使用 streamGenerateContent?alt=sse 作為運算子。每個 SSE 事件都包含一行 data:，其中帶有一個 JSON GenerateContentResponse 物件。

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

設定 system instructions

若要在整段對話中引導模型的行為，請使用 systemInstruction：

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "What is 2+2?"}]}],
    "systemInstruction": {
      "parts": [{"text": "You are a math tutor. Always show your work."}]
    }
  }'

請求 JSON 輸出

若要強制輸出結構化 JSON，請設定 responseMimeType。你也可以選擇提供 responseSchema，以進行嚴格的結構描述驗證：

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "List 3 planets with their distances from the sun"}]}],
    "generationConfig": {
      "responseMimeType": "application/json"
    }
  }'

使用 Google Search 進行 grounding

若要啟用即時網頁搜尋，請加入 googleSearch 工具：

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Who won the euro 2024?"}]}],
    "tools": [{"google_search": {}}]
  }'

回應會包含 groundingMetadata，其中包含來源 URL 和信心分數。

回應範例

來自 CometAPI 的 Gemini 端點的典型回應：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Hello"}]
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.0023
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 1,
    "totalTokenCount": 30,
    "trafficType": "ON_DEMAND",
    "thoughtsTokenCount": 24,
    "promptTokensDetails": [{"modality": "TEXT", "tokenCount": 5}],
    "candidatesTokensDetails": [{"modality": "TEXT", "tokenCount": 1}]
  },
  "modelVersion": "gemini-3-flash-preview",
  "createTime": "2026-03-25T04:21:43.756483Z",
  "responseId": "CeynaY3LDtvG4_UP0qaCuQY"
}

usageMetadata 中的 thoughtsTokenCount 欄位會顯示模型在內部推理上花費了多少 Token，即使回應中未包含 thinking 輸出也是如此。

與 OpenAI 相容端點比較

功能	Gemini 原生 (`/v1beta/models/...`)	OpenAI 相容 (`/v1/chat/completions`)
Thinking 控制	`thinkingConfig` 搭配 `thinkingLevel` / `thinkingBudget`	不可用
Google Search grounding	`tools: [\{"google_search": \{\}\}]`	不可用
Google Maps grounding	`tools: [\{"googleMaps": \{\}\}]`	不可用
圖像生成 modality	`responseModalities: ["IMAGE"]`	不可用
驗證標頭	`x-goog-api-key` 或 `Bearer`	僅 `Bearer`
回應格式	Gemini 原生（`candidates`、`parts`）	OpenAI 格式（`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 model ID. Example: gemini-3-flash-preview, gemini-2.5-pro. See the Models page for current options.

operator

enum<string>

必填

The operation to perform. Use generateContent for synchronous responses, or streamGenerateContent?alt=sse for Server-Sent Events streaming.

可用選項:

generateContent,

streamGenerateContent?alt=sse

主體

application/json

contents

object[]

Conversation content. Each entry has an optional role (user or model) and a parts array.

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 the model may use to generate responses. Supports function declarations, Google Search, Google Maps, and code execution.

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.

建立訊息

影像生成與編輯 API

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-flash-preview",
    contents="Explain how AI works in a few words",
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "<string>",
        "parts": [
          {
            "text": "<string>",
            "functionCall": {
              "name": "<string>",
              "args": {}
            },
            "inlineData": {
              "mimeType": "<string>",
              "data": "<string>"
            },
            "thought": true
          }
        ]
      },
      "safetyRatings": [
        {
          "category": "<string>",
          "probability": "<string>",
          "blocked": true
        }
      ],
      "citationMetadata": {
        "citationSources": [
          {
            "startIndex": 123,
            "endIndex": 123,
            "uri": "<string>",
            "license": "<string>"
          }
        ]
      },
      "tokenCount": 123,
      "avgLogprobs": 123,
      "groundingMetadata": {
        "groundingChunks": [
          {
            "web": {
              "uri": "<string>",
              "title": "<string>"
            }
          }
        ],
        "groundingSupports": [
          {
            "groundingChunkIndices": [
              123
            ],
            "confidenceScores": [
              123
            ],
            "segment": {
              "startIndex": 123,
              "endIndex": 123,
              "text": "<string>"
            }
          }
        ],
        "webSearchQueries": [
          "<string>"
        ]
      },
      "index": 123
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "<string>",
        "probability": "<string>",
        "blocked": true
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 123,
    "candidatesTokenCount": 123,
    "totalTokenCount": 123,
    "trafficType": "<string>",
    "thoughtsTokenCount": 123,
    "promptTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ]
  },
  "modelVersion": "<string>",
  "createTime": "<string>",
  "responseId": "<string>"
}

內容審核

API 金鑰

快速開始

傳送影片輸入

設定 thinking（推理）

串流回應

設定 system instructions

請求 JSON 輸出

使用 Google Search 進行 grounding

回應範例

與 OpenAI 相容端點比較

授權

路徑參數

主體

回應

​快速開始

​傳送影片輸入

​設定 thinking（推理）

​串流回應

​設定 system instructions

​請求 JSON 輸出

​使用 Google Search 進行 grounding

​回應範例

​與 OpenAI 相容端點比較

授權

路徑參數

主體

回應

快速開始

傳送影片輸入

設定 thinking（推理）

串流回應

設定 system instructions

請求 JSON 輸出

使用 Google Search 進行 grounding

回應範例

與 OpenAI 相容端點比較