> ## 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.

# Hướng dẫn nhanh Gemini API: Sử dụng request native và tương thích OpenAI với CometAPI

> Gọi các model văn bản Gemini thông qua CometAPI bằng request generateContent native hoặc request Chat Completions tương thích OpenAI.

## Những gì bạn sẽ xây dựng

Bạn sẽ gửi một request Gemini native `POST /v1beta/models/\{model\}:generateContent`, sau đó so sánh nó với tùy chọn tương thích OpenAI `POST /v1/chat/completions` cho các ứng dụng đã sử dụng định dạng request Chat Completions.

## Điều kiện tiên quyết

* Một API key CometAPI được lưu trong `COMETAPI_KEY`
* Một model ID văn bản Gemini từ [trang Models](/vi/overview/models)
* `curl`, Python 3.10+, hoặc Node.js 18+

## API key, base URL, xác thực

Sử dụng endpoint Gemini native khi bạn muốn dùng các trường request của Gemini:

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

Sử dụng `x-goog-api-key` cho các request HTTP Gemini native trực tiếp:

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

Chỉ sử dụng base URL tương thích OpenAI khi ứng dụng của bạn đã dùng Chat Completions:

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

## Định dạng Gemini native

Các request Gemini native sử dụng `contents`, `parts`, và `generationConfig`. Hãy dùng đường dẫn này khi bạn cần các trường đặc thù của Gemini như điều khiển thinking, phần media, grounding với Google Search, hoặc toán tử streaming native.

<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>

## Tùy chọn tương thích OpenAI

Sử dụng tuyến tương thích OpenAI khi bạn đang di chuyển một ứng dụng hiện có dùng OpenAI SDK hoặc Chat Completions và không cần các trường request native của Gemini.

<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>

## Giải thích luồng

| Đường dẫn          | Endpoint                                        | Định dạng request                                  | SDK                                  | Dùng khi                                                                                                           |
| ------------------ | ----------------------------------------------- | -------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| Gemini native      | `POST /v1beta/models/\{model\}:generateContent` | `contents`, `parts`, `generationConfig`            | Google GenAI SDK hoặc HTTP trực tiếp | Bạn cần các trường đặc thù của Gemini, các phần multimodal, điều khiển thinking, grounding, hoặc streaming native. |
| Tương thích OpenAI | `POST /v1/chat/completions`                     | `messages`, `temperature`, `max_completion_tokens` | OpenAI SDK hoặc HTTP trực tiếp       | Ứng dụng của bạn đã sử dụng Chat Completions và chỉ cần một model văn bản Gemini phía sau định dạng đó.            |

Không trộn lẫn hai định dạng request này. Các trường Gemini native như `contents` và `generationConfig` thuộc về tuyến `generateContent`. Các trường Chat Completions như `messages` thuộc về tuyến tương thích OpenAI.

## Khắc phục sự cố / FAQ

<AccordionGroup>
  <Accordion title="Tôi nên bắt đầu với đường dẫn nào">
    Hãy bắt đầu với Gemini native `generateContent` khi bạn đang xây dựng một quy trình Gemini mới. Sử dụng tuyến tương thích OpenAI khi một ứng dụng hiện có đã phụ thuộc vào OpenAI SDK hoặc định dạng request Chat Completions.
  </Accordion>

  <Accordion title="Các trường Gemini native bị lỗi trên Chat Completions">
    Gửi các request `contents`, `parts`, `generationConfig`, và `streamGenerateContent` tới endpoint Gemini native. Tuyến tương thích OpenAI mong đợi `messages` và các tham số Chat Completions.
  </Accordion>

  <Accordion title="model ID Gemini bị lỗi">
    Hãy xác nhận rằng model ID có sẵn cho tài khoản của bạn và hỗ trợ tuyến bạn đang gọi. Sử dụng [trang Models](/vi/overview/models) để tìm các model ID hiện có.
  </Accordion>

  <Accordion title="SDK trỏ tới sai dịch vụ">
    Đối với các request Google GenAI SDK, hãy đặt base URL thành `https://api.cometapi.com`. Đối với các request OpenAI SDK, hãy đặt `base_url` trong Python hoặc `baseURL` trong Node.js thành `https://api.cometapi.com/v1`.
  </Accordion>
</AccordionGroup>

## Các bước tiếp theo

* Sử dụng [tài liệu tham chiếu Gemini native API](/api/text/gemini-generating-content) để xem đầy đủ các trường request và response của `generateContent`.
* Đọc [tài liệu tham chiếu Chat Completions API](/api/text/chat) để biết định dạng request tương thích OpenAI.
* Cấu hình client OpenAI SDK trong [Sử dụng CometAPI với OpenAI SDK](/vi/guides/use-cometapi-with-openai-sdk).
* Liệt kê các model khả dụng bằng [Liệt kê các model CometAPI khả dụng](/vi/guides/how-to-list-available-models).
* Thêm xử lý retry và rate-limit bằng [Mã lỗi và chiến lược retry](/vi/guides/error-codes-and-retry-strategy).