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

# Usare AI SDK con CometAPI

> Usa questa guida per configurare AI SDK con CometAPI impostando l'URL di base, la chiave API e le opzioni del model o del provider.

Il [provider CometAPI per l'AI SDK](https://github.com/cometapi-dev/ai-sdk-provider) ti offre accesso a oltre 500 modelli AI tramite un'interfaccia TypeScript unificata. Usalo per aggiungere generazione di testo, Streaming, Embeddings e generazione di immagini a qualsiasi applicazione Node.js o Edge runtime.

## Funzionalità supportate

| Funzionalità            | Metodo                 | Stato      |
| ----------------------- | ---------------------- | ---------- |
| Generazione di testo    | `generateText()`       | Supportato |
| Streaming di testo      | `streamText()`         | Supportato |
| Embeddings di testo     | `textEmbeddingModel()` | Supportato |
| Generazione di immagini | `imageModel()`         | Supportato |

## Prerequisiti

* Node.js 18+
* Un account CometAPI con una chiave API attiva — [ottienila qui](https://www.cometapi.com/console/token)

<Steps>
  <Step title="Installa il provider">
    Installa `@cometapi/ai-sdk-provider` insieme al pacchetto core di AI SDK:

    <CodeGroup>
      ```bash npm theme={null}
      npm install @cometapi/ai-sdk-provider ai
      ```

      ```bash pnpm theme={null}
      pnpm add @cometapi/ai-sdk-provider ai
      ```

      ```bash yarn theme={null}
      yarn add @cometapi/ai-sdk-provider ai
      ```
    </CodeGroup>
  </Step>

  <Step title="Imposta la tua chiave API">
    Il provider legge la variabile d'ambiente `COMETAPI_KEY` per impostazione predefinita:

    ```bash theme={null}
    read -rsp "CometAPI API key: " COMETAPI_KEY
    printf '\n'
    export COMETAPI_KEY
    ```

    <Note>
      Usa le variabili d'ambiente per evitare di inserire credenziali hardcoded nel codice sorgente.
    </Note>
  </Step>

  <Step title="Importa il provider">
    Importa l'istanza predefinita del provider:

    ```typescript theme={null}
    import { cometapi } from '@cometapi/ai-sdk-provider';
    ```

    Per sovrascrivere la chiave API, l'URL di base o altre impostazioni, usa `createCometAPI`:

    ```typescript theme={null}
    import { createCometAPI } from '@cometapi/ai-sdk-provider';

    const cometapi = createCometAPI({
      apiKey: process.env.COMETAPI_KEY,       // override env variable
      baseURL: 'https://api.cometapi.com/v1',  // default
    });
    ```
  </Step>
</Steps>

## Utilizzo

### Genera testo

Usa `generateText()` per una risposta singola:

```typescript theme={null}
import { cometapi } from '@cometapi/ai-sdk-provider';
import { generateText } from 'ai';

const { text } = await generateText({
  model: cometapi('your-model-id'),
  prompt: 'What is CometAPI?',
});

console.log(text);
```

### Esegui lo streaming del testo

Usa `streamText()` per output in tempo reale suddiviso in chunk:

```typescript theme={null}
import { cometapi } from '@cometapi/ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: cometapi('your-model-id'),
  prompt: 'Write a short story about AI.',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}
```

### Genera embeddings

Usa `textEmbeddingModel()` per creare embeddings vettoriali:

```typescript theme={null}
import { cometapi } from '@cometapi/ai-sdk-provider';

const model = cometapi.textEmbeddingModel('text-embedding-3-small');

// Single embedding
const single = await model.doEmbed({ values: ['Hello, world!'] });
console.log('Dimensions:', single.embeddings[0].length);

// Batch embeddings
const batch = await model.doEmbed({
  values: ['sunny day', 'rainy afternoon', 'cold winter night'],
});
console.log('Count:', batch.embeddings.length);
```

### Genera immagini

Usa `imageModel()` per generare immagini da prompt testuali:

```typescript theme={null}
import { cometapi } from '@cometapi/ai-sdk-provider';
import { experimental_generateImage as generateImage } from 'ai';

const { image } = await generateImage({
  model: cometapi.imageModel('your-model-id'),
  prompt: 'A beautiful sunset over mountains',
});
```

## Configurazione del provider

`createCometAPI` accetta le seguenti opzioni:

| Opzione   | Tipo                     | Predefinito                   | Descrizione                             |
| --------- | ------------------------ | ----------------------------- | --------------------------------------- |
| `apiKey`  | `string`                 | `process.env.COMETAPI_KEY`    | Chiave API di CometAPI                  |
| `baseURL` | `string`                 | `https://api.cometapi.com/v1` | URL di base dell'API                    |
| `headers` | `Record<string, string>` | —                             | Header di richiesta personalizzati      |
| `fetch`   | `FetchFunction`          | —                             | Implementazione personalizzata di fetch |

## Metodi del modello

Il provider espone diversi costruttori di modello:

| Metodo                                 | Restituisce        | Caso d'uso                                          |
| -------------------------------------- | ------------------ | --------------------------------------------------- |
| `cometapi(modelId)`                    | `LanguageModelV2`  | Generazione di testo e Streaming (forma abbreviata) |
| `cometapi.chatModel(modelId)`          | `LanguageModelV2`  | Chat completions                                    |
| `cometapi.completionModel(modelId)`    | `LanguageModelV2`  | Completamenti di testo                              |
| `cometapi.languageModel(modelId)`      | `LanguageModelV2`  | Alias di `chatModel`                                |
| `cometapi.textEmbeddingModel(modelId)` | `EmbeddingModelV2` | Embeddings di testo                                 |
| `cometapi.imageModel(modelId)`         | `ImageModelV2`     | Generazione di immagini                             |

Consulta l'elenco completo dei model ID disponibili nella [pagina Models](/it/overview/models).

<AccordionGroup>
  <Accordion title="Suggerimenti e risoluzione dei problemi">
    * **Selezione del modello**: Qualsiasi modello del [catalogo modelli CometAPI](/it/overview/models) funziona con il metodo di modello corrispondente — i modelli chat tramite `cometapi()`, i modelli embedding tramite `textEmbeddingModel()`, i modelli immagine tramite `imageModel()`.
    * **Ottimizzazione delle risposte**: Passa `temperature`, `maxTokens` e `topP` direttamente a `generateText()` o `streamText()`, ad esempio `generateText(\{..., temperature: 0.7\})`.
    * **Gestione degli errori**: Racchiudi le chiamate in `try/catch` per gestire errori di autenticazione, limiti di frequenza o problemi di rete.
    * **Sicurezza**: Non salvare mai le chiavi API nel controllo versione. Usa variabili d'ambiente o un gestore di segreti.
    * **Limiti di frequenza**: Monitora l'utilizzo nella [console CometAPI](https://www.cometapi.com/console).
  </Accordion>
</AccordionGroup>

## Risorse correlate

* [Provider AI SDK di CometAPI su GitHub](https://github.com/cometapi-dev/ai-sdk-provider)
* [@cometapi/ai-sdk-provider su npm](https://www.npmjs.com/package/@cometapi/ai-sdk-provider)
* [Documentazione di AI SDK](https://ai-sdk.dev/docs)
* [Guida rapida di CometAPI](/it/overview/quick-start)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#howto",
        "name": "Usare AI SDK con CometAPI",
        "description": "Usa questa guida per configurare AI SDK con CometAPI impostando l'URL di base, la chiave API e il model o le opzioni del provider.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#step-1",
            "position": 1,
            "name": "Installare il provider",
            "text": "Completa il passaggio Installare il provider nella guida Usare AI SDK con CometAPI."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#step-2",
            "position": 2,
            "name": "Impostare la chiave API",
            "text": "Memorizza la chiave API di CometAPI nella variabile di ambiente o nel campo delle impostazioni usato dall'integrazione."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#step-3",
            "position": 3,
            "name": "Importare il provider",
            "text": "Completa il passaggio Importare il provider nella guida Usare AI SDK con CometAPI."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "Documentazione CometAPI",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Integrazioni",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "Usare AI SDK con CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/ai-sdk"
          }
        ]
      }
    ]
    }
    `}
</script>