> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini API 快速入門：透過 CometAPI 使用原生與 OpenAI 相容請求

> 透過 CometAPI 呼叫 Gemini 文字模型，可使用原生 generateContent 請求，或使用與 OpenAI 相容的聊天補全請求。

## 你將建立的內容

你將傳送一個原生 Gemini `POST /v1beta/models/\{model\}:generateContent` 請求，接著將它與 OpenAI 相容的 `POST /v1/chat/completions` 選項進行比較，適用於已經使用聊天補全請求格式的應用程式。

## 先決條件

* 儲存在 `COMETAPI_KEY` 中的 CometAPI API key
* 來自[模型頁面](/zh-Hant/overview/models)的 Gemini 文字模型 model ID
* `curl`、Python 3.10+ 或 Node.js 18+

## API key、base URL、驗證

當你想使用 Gemini 請求欄位時，請使用 Gemini 原生端點：

```text theme={null}
https://api.cometapi.com/v1beta/models/{model}:generateContent
```

直接使用原生 Gemini HTTP 請求時，請使用 `x-goog-api-key`：

```text theme={null}
x-goog-api-key: $COMETAPI_KEY
```

只有在你的應用程式已經使用聊天補全時，才使用 OpenAI 相容 base URL：

```text theme={null}
https://api.cometapi.com/v1
```

## 原生 Gemini 格式

原生 Gemini 請求使用 `contents`、`parts` 和 `generationConfig`。當你需要 Gemini 專屬欄位時，請使用此路徑，例如 thinking 控制、媒體部分、Google Search grounding，或原生串流運算子。

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.cometapi.com/v1beta/models/your-gemini-model-id:generateContent" \
    -H "x-goog-api-key: $COMETAPI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [
        {
          "parts": [
            {
              "text": "Explain why base URL configuration matters."
            }
          ]
        }
      ],
      "generationConfig": {
        "temperature": 0.3
      }
    }'
  ```

  ```python Python theme={null}
  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="your-gemini-model-id",
      contents="Explain why base URL configuration matters.",
      config={
          "temperature": 0.3,
      },
  )

  print(response.text)
  ```

  ```javascript Node.js theme={null}
  import { GoogleGenAI } from "@google/genai";

  const ai = new GoogleGenAI({
    apiKey: process.env.COMETAPI_KEY,
    httpOptions: {
      baseUrl: "https://api.cometapi.com",
      apiVersion: "v1beta",
    },
  });

  const response = await ai.models.generateContent({
    model: "your-gemini-model-id",
    contents: "Explain why base URL configuration matters.",
    config: {
      temperature: 0.3,
    },
  });

  console.log(response.text);
  ```
</CodeGroup>

## OpenAI 相容選項

當你正在遷移既有的 OpenAI SDK 或聊天補全應用程式，且不需要 Gemini 原生請求欄位時，請使用 OpenAI 相容路由。

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.cometapi.com/v1/chat/completions \
    -H "Authorization: Bearer $COMETAPI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "your-gemini-model-id",
      "messages": [
        {
          "role": "user",
          "content": "Explain why base URL configuration matters."
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["COMETAPI_KEY"],
      base_url="https://api.cometapi.com/v1",
  )

  completion = client.chat.completions.create(
      model="your-gemini-model-id",
      messages=[
          {
              "role": "user",
              "content": "Explain why base URL configuration matters.",
          }
      ],
  )

  print(completion.choices[0].message.content)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.COMETAPI_KEY,
    baseURL: "https://api.cometapi.com/v1",
  });

  const completion = await client.chat.completions.create({
    model: "your-gemini-model-id",
    messages: [
      {
        role: "user",
        content: "Explain why base URL configuration matters.",
      },
    ],
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

## 流程說明

| 路徑        | 端點                                              | 請求格式                                             | SDK                       | 使用時機                                               |
| --------- | ----------------------------------------------- | ------------------------------------------------ | ------------------------- | -------------------------------------------------- |
| Gemini 原生 | `POST /v1beta/models/\{model\}:generateContent` | `contents`、`parts`、`generationConfig`            | Google GenAI SDK 或直接 HTTP | 你需要 Gemini 專屬欄位、多模態部分、thinking 控制、grounding 或原生串流。 |
| OpenAI 相容 | `POST /v1/chat/completions`                     | `messages`、`temperature`、`max_completion_tokens` | OpenAI SDK 或直接 HTTP       | 你的應用程式已經使用聊天補全，而且只需要在該格式後方接入 Gemini 文字模型。          |

不要混用這兩種請求格式。像是 `contents` 和 `generationConfig` 這類原生 Gemini 欄位屬於 `generateContent` 路由。像是 `messages` 這類聊天補全欄位則屬於 OpenAI 相容路由。

## 疑難排解 / FAQ

<AccordionGroup>
  <Accordion title="我應該從哪一種路徑開始">
    如果你正在建立新的 Gemini 工作流程，請從原生 Gemini `generateContent` 開始。若既有應用程式已經依賴 OpenAI SDK 或聊天補全請求格式，請使用 OpenAI 相容路由。
  </Accordion>

  <Accordion title="原生 Gemini 欄位在 Chat Completions 上失敗">
    請將 `contents`、`parts`、`generationConfig` 和 `streamGenerateContent` 請求傳送到 Gemini 原生端點。OpenAI 相容路由預期的是 `messages` 與聊天補全參數。
  </Accordion>

  <Accordion title="Gemini model ID 失敗">
    請確認該 model ID 可供你的帳戶使用，且支援你正在呼叫的路由。請使用[模型頁面](/zh-Hant/overview/models)查找目前可用的 model ID。
  </Accordion>

  <Accordion title="SDK 指向錯誤的服務">
    對於 Google GenAI SDK 請求，請將 base URL 設為 `https://api.cometapi.com`。對於 OpenAI SDK 請求，請在 Python 中將 `base_url` 或在 Node.js 中將 `baseURL` 設為 `https://api.cometapi.com/v1`。
  </Accordion>
</AccordionGroup>

## 後續步驟

* 使用 [Gemini 原生 API 參考](/api/text/gemini-generating-content) 查看完整的 `generateContent` 請求與回應欄位。
* 閱讀[聊天補全 API 參考](/api/text/chat)以了解 OpenAI 相容的請求格式。
* 在 [搭配 OpenAI SDK 使用 CometAPI](/zh-Hant/guides/use-cometapi-with-openai-sdk) 中設定 OpenAI SDK 用戶端。
* 使用 [列出可用的 CometAPI 模型](/zh-Hant/guides/how-to-list-available-models) 列出可用模型。
* 使用 [錯誤代碼與重試策略](/zh-Hant/guides/error-codes-and-retry-strategy) 加入重試與速率限制處理。