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

# Guida rapida all'API Gemini: usa richieste native e compatibili con OpenAI con CometAPI

> Chiama i modelli di testo Gemini tramite CometAPI con richieste native generateContent o richieste Chat Completions compatibili con OpenAI.

## Cosa creerai

Invierai una richiesta nativa Gemini `POST /v1beta/models/\{model\}:generateContent`, quindi la confronterai con l'opzione compatibile con OpenAI `POST /v1/chat/completions` per le app che usano già i formati di richiesta Chat Completions.

## Prerequisiti

* Una chiave API CometAPI archiviata in `COMETAPI_KEY`
* Un model ID di un modello di testo Gemini dalla [pagina Models](/it/overview/models)
* `curl`, Python 3.10+ o Node.js 18+

## Chiave API, URL di base, autenticazione

Usa l'endpoint nativo Gemini quando vuoi usare i campi di richiesta Gemini:

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

Usa `x-goog-api-key` per richieste HTTP Gemini native dirette:

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

Usa l'URL di base compatibile con OpenAI solo quando la tua applicazione usa già Chat Completions:

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

## Formato Gemini nativo

Le richieste Gemini native usano `contents`, `parts` e `generationConfig`. Usa questo percorso quando ti servono campi specifici di Gemini come controlli di thinking, parti multimediali, grounding con Google Search o operatori di streaming nativi.

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

## Opzione compatibile con OpenAI

Usa il percorso compatibile con OpenAI quando stai migrando un'app esistente basata su OpenAI SDK o Chat Completions e non ti servono i campi di richiesta nativi di 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>

## Spiegazione del flusso

| Path                   | Endpoint                                        | Formato della richiesta                            | SDK                             | Usa quando                                                                                                    |
| ---------------------- | ----------------------------------------------- | -------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Gemini nativo          | `POST /v1beta/models/\{model\}:generateContent` | `contents`, `parts`, `generationConfig`            | Google GenAI SDK o HTTP diretto | Ti servono campi specifici di Gemini, parti multimodali, controlli di thinking, grounding o streaming nativo. |
| Compatibile con OpenAI | `POST /v1/chat/completions`                     | `messages`, `temperature`, `max_completion_tokens` | OpenAI SDK o HTTP diretto       | La tua app usa già Chat Completions e ha bisogno solo di un modello di testo Gemini dietro quel formato.      |

Non mischiare i due formati di richiesta. I campi nativi di Gemini come `contents` e `generationConfig` appartengono al percorso `generateContent`. I campi Chat Completions come `messages` appartengono al percorso compatibile con OpenAI.

## Risoluzione dei problemi / FAQ

<AccordionGroup>
  <Accordion title="Con quale percorso dovrei iniziare">
    Inizia con `generateContent` nativo di Gemini quando stai creando un nuovo flusso di lavoro Gemini. Usa il percorso compatibile con OpenAI quando un'app esistente dipende già da OpenAI SDK o dai formati di richiesta Chat Completions.
  </Accordion>

  <Accordion title="I campi nativi Gemini falliscono su Chat Completions">
    Invia richieste `contents`, `parts`, `generationConfig` e `streamGenerateContent` all'endpoint nativo Gemini. Il percorso compatibile con OpenAI si aspetta `messages` e parametri Chat Completions.
  </Accordion>

  <Accordion title="Il model ID Gemini non funziona">
    Conferma che il model ID sia disponibile per il tuo account e supporti il percorso che stai chiamando. Usa la [pagina Models](/it/overview/models) per trovare i model ID correnti.
  </Accordion>

  <Accordion title="L'SDK punta al servizio sbagliato">
    Per le richieste Google GenAI SDK, imposta l'URL di base su `https://api.cometapi.com`. Per le richieste OpenAI SDK, imposta `base_url` in Python o `baseURL` in Node.js su `https://api.cometapi.com/v1`.
  </Accordion>
</AccordionGroup>

## Passaggi successivi

* Usa il [riferimento API nativo Gemini](/api/text/gemini-generating-content) per tutti i campi di richiesta e risposta di `generateContent`.
* Leggi il [riferimento API Chat Completions](/api/text/chat) per il formato di richiesta compatibile con OpenAI.
* Configura i client OpenAI SDK in [Usare CometAPI con OpenAI SDK](/it/guides/use-cometapi-with-openai-sdk).
* Elenca i modelli disponibili con [Elencare i modelli CometAPI disponibili](/it/guides/how-to-list-available-models).
* Aggiungi la gestione dei retry e dei rate limit con [Codici di errore e strategia di retry](/it/guides/error-codes-and-retry-strategy).