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

# Início rápido da API Gemini: use solicitações nativas e compatíveis com OpenAI com a CometAPI

> Chame modelos de texto Gemini pela CometAPI com solicitações nativas generateContent ou solicitações Chat Completions compatíveis com OpenAI.

## O que você vai criar

Você enviará uma solicitação nativa Gemini `POST /v1beta/models/\{model\}:generateContent` e, em seguida, a comparará com a opção compatível com OpenAI `POST /v1/chat/completions` para apps que já usam formatos de solicitação do Chat Completions.

## Pré-requisitos

* Uma chave de API da CometAPI armazenada em `COMETAPI_KEY`
* Um model ID de texto Gemini da [página de modelos](/pt/overview/models)
* `curl`, Python 3.10+ ou Node.js 18+

## Chave de API, URL base, autenticação

Use o endpoint nativo do Gemini quando quiser campos de solicitação do Gemini:

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

Use `x-goog-api-key` para solicitações HTTP nativas diretas do Gemini:

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

Use a URL base compatível com OpenAI apenas quando sua aplicação já usar Chat Completions:

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

## Formato nativo do Gemini

As solicitações nativas do Gemini usam `contents`, `parts` e `generationConfig`. Use este caminho quando precisar de campos específicos do Gemini, como controles de thinking, partes de mídia, grounding com Google Search ou operadores de streaming nativos.

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

## Opção compatível com OpenAI

Use a rota compatível com OpenAI quando estiver migrando um SDK OpenAI existente ou um app Chat Completions e não precisar de campos de solicitação nativos do 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>

## Explicação do fluxo

| Caminho               | Endpoint                                        | Formato da solicitação                             | SDK                             | Use quando                                                                                                              |
| --------------------- | ----------------------------------------------- | -------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Gemini nativo         | `POST /v1beta/models/\{model\}:generateContent` | `contents`, `parts`, `generationConfig`            | Google GenAI SDK ou HTTP direto | Você precisa de campos específicos do Gemini, partes multimodais, controles de thinking, grounding ou streaming nativo. |
| Compatível com OpenAI | `POST /v1/chat/completions`                     | `messages`, `temperature`, `max_completion_tokens` | OpenAI SDK ou HTTP direto       | Seu app já usa Chat Completions e só precisa de um modelo de texto Gemini por trás desse formato.                       |

Não misture os dois formatos de solicitação. Campos nativos do Gemini, como `contents` e `generationConfig`, pertencem à rota `generateContent`. Campos do Chat Completions, como `messages`, pertencem à rota compatível com OpenAI.

## Solução de problemas / FAQ

<AccordionGroup>
  <Accordion title="Com qual caminho devo começar">
    Comece com o Gemini nativo `generateContent` quando estiver criando um novo fluxo de trabalho com Gemini. Use a rota compatível com OpenAI quando um app existente já depender de formatos de solicitação do SDK OpenAI ou do Chat Completions.
  </Accordion>

  <Accordion title="Campos nativos do Gemini falham no Chat Completions">
    Envie solicitações `contents`, `parts`, `generationConfig` e `streamGenerateContent` para o endpoint nativo do Gemini. A rota compatível com OpenAI espera `messages` e parâmetros do Chat Completions.
  </Accordion>

  <Accordion title="O model ID do Gemini falha">
    Confirme que o model ID está disponível para sua conta e oferece suporte à rota que você está chamando. Use a [página de modelos](/pt/overview/models) para encontrar os model IDs atuais.
  </Accordion>

  <Accordion title="O SDK aponta para o serviço errado">
    Para solicitações com o Google GenAI SDK, defina a URL base como `https://api.cometapi.com`. Para solicitações com o OpenAI SDK, defina `base_url` em Python ou `baseURL` em Node.js como `https://api.cometapi.com/v1`.
  </Accordion>
</AccordionGroup>

## Próximos passos

* Use a [referência da API nativa do Gemini](/api/text/gemini-generating-content) para ver todos os campos de solicitação e resposta de `generateContent`.
* Leia a [referência da API Chat Completions](/api/text/chat) para o formato de solicitação compatível com OpenAI.
* Configure clientes do OpenAI SDK em [Use a CometAPI com SDKs OpenAI](/pt/guides/use-cometapi-with-openai-sdk).
* Liste os modelos disponíveis com [Liste os modelos disponíveis da CometAPI](/pt/guides/how-to-list-available-models).
* Adicione tratamento de retry e rate-limit com [Códigos de erro e estratégia de retry](/pt/guides/error-codes-and-retry-strategy).