> ## 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 키
* [Models page](/ko/overview/models)에서 확인한 Gemini 텍스트 model ID
* `curl`, Python 3.10+ 또는 Node.js 18+

## API 키, 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`를 사용합니다. thinking controls, media parts, Google Search grounding 또는 네이티브 스트리밍(Streaming) 연산자 같은 Gemini 전용 필드가 필요할 때 이 경로를 사용하세요.

<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 전용 필드, 멀티모달(Multimodal) parts, thinking controls, grounding 또는 네이티브 스트리밍(Streaming)이 필요할 때 |
| OpenAI 호환   | `POST /v1/chat/completions`                     | `messages`, `temperature`, `max_completion_tokens` | OpenAI SDK 또는 직접 HTTP       | 앱이 이미 채팅 완성을 사용하고 있고, 그 형식 뒤에서 Gemini 텍스트 model만 필요할 때                                            |

두 요청 형식을 섞어 사용하지 마세요. `contents`, `generationConfig` 같은 네이티브 Gemini 필드는 `generateContent` 경로에 사용해야 합니다. `messages` 같은 채팅 완성 필드는 OpenAI 호환 경로에 사용해야 합니다.

## 문제 해결 / FAQ

<AccordionGroup>
  <Accordion title="어떤 경로로 시작해야 하나요">
    새로운 Gemini 워크플로를 구축하는 경우 네이티브 Gemini `generateContent`로 시작하세요. 기존 앱이 이미 OpenAI SDK 또는 채팅 완성 요청 형식에 의존하고 있다면 OpenAI 호환 경로를 사용하세요.
  </Accordion>

  <Accordion title="채팅 완성에서 네이티브 Gemini 필드가 실패합니다">
    `contents`, `parts`, `generationConfig`, `streamGenerateContent` 요청은 Gemini 네이티브 엔드포인트로 보내세요. OpenAI 호환 경로는 `messages`와 채팅 완성 파라미터를 기대합니다.
  </Accordion>

  <Accordion title="Gemini model ID가 실패합니다">
    해당 model ID를 계정에서 사용할 수 있고 호출하려는 경로를 지원하는지 확인하세요. 현재 model ID는 [Models page](/ko/overview/models)에서 찾을 수 있습니다.
  </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>

## 다음 단계

* 전체 `generateContent` 요청 및 응답 필드는 [Gemini 네이티브 API reference](/api/text/gemini-generating-content)를 사용하세요.
* OpenAI 호환 요청 형식은 [채팅 완성 API reference](/api/text/chat)를 읽어보세요.
* OpenAI SDK 클라이언트는 [Use CometAPI with OpenAI SDKs](/ko/guides/use-cometapi-with-openai-sdk)에서 구성하세요.
* 사용 가능한 모델은 [List available CometAPI models](/ko/guides/how-to-list-available-models)로 확인하세요.
* 재시도 및 rate-limit 처리는 [Error codes and retry strategy](/ko/guides/error-codes-and-retry-strategy)를 추가하세요.