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

# Usar o AI SDK com CometAPI

> Use este guia para configurar o AI SDK com CometAPI definindo a URL base, a chave de API e as opções de model ou provider.

O [provider da CometAPI para o AI SDK](https://github.com/cometapi-dev/ai-sdk-provider) dá a você acesso a mais de 500 modelos de IA por meio de uma interface unificada em TypeScript. Use-o para adicionar geração de texto, Streaming, Embeddings e geração de imagens a qualquer aplicação em Node.js ou runtime Edge.

## Recursos compatíveis

| Recurso             | Método                 | Status     |
| ------------------- | ---------------------- | ---------- |
| Geração de texto    | `generateText()`       | Compatível |
| Streaming de texto  | `streamText()`         | Compatível |
| Embeddings de texto | `textEmbeddingModel()` | Compatível |
| Geração de imagens  | `imageModel()`         | Compatível |

## Pré-requisitos

* Node.js 18+
* Uma conta CometAPI com uma chave de API ativa — [obtenha a sua aqui](https://www.cometapi.com/console/token)

<Steps>
  <Step title="Instale o provider">
    Instale `@cometapi/ai-sdk-provider` junto com o pacote principal do 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="Defina sua chave de API">
    O provider lê a variável de ambiente `COMETAPI_KEY` por padrão:

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

    <Note>
      Use variáveis de ambiente para evitar codificar credenciais diretamente no seu código-fonte.
    </Note>
  </Step>

  <Step title="Importe o provider">
    Importe a instância padrão do provider:

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

    Para substituir a chave de API, a URL base ou outras configurações, use `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>

## Uso

### Gerar texto

Use `generateText()` para uma resposta única:

```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);
```

### Transmitir texto em streaming

Use `streamText()` para saída em blocos em tempo real:

```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);
}
```

### Gerar embeddings

Use `textEmbeddingModel()` para criar Embeddings vetoriais:

```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);
```

### Gerar imagens

Use `imageModel()` para gerar imagens a partir de prompts de texto:

```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',
});
```

## Configuração do provedor

`createCometAPI` aceita as seguintes opções:

| Option    | Type                     | Default                       | Description                              |
| --------- | ------------------------ | ----------------------------- | ---------------------------------------- |
| `apiKey`  | `string`                 | `process.env.COMETAPI_KEY`    | Chave de API da CometAPI                 |
| `baseURL` | `string`                 | `https://api.cometapi.com/v1` | URL base da API                          |
| `headers` | `Record<string, string>` | —                             | Cabeçalhos de solicitação personalizados |
| `fetch`   | `FetchFunction`          | —                             | Implementação personalizada de fetch     |

## Métodos de modelo

O provedor expõe vários construtores de modelo:

| Method                                 | Returns            | Use case                                       |
| -------------------------------------- | ------------------ | ---------------------------------------------- |
| `cometapi(modelId)`                    | `LanguageModelV2`  | Geração de texto e streaming (forma abreviada) |
| `cometapi.chatModel(modelId)`          | `LanguageModelV2`  | Chat completions                               |
| `cometapi.completionModel(modelId)`    | `LanguageModelV2`  | Completações de texto                          |
| `cometapi.languageModel(modelId)`      | `LanguageModelV2`  | Alias para `chatModel`                         |
| `cometapi.textEmbeddingModel(modelId)` | `EmbeddingModelV2` | Embeddings de texto                            |
| `cometapi.imageModel(modelId)`         | `ImageModelV2`     | Geração de imagens                             |

Consulte a lista completa de model IDs disponíveis na [página de modelos](/pt/overview/models).

<AccordionGroup>
  <Accordion title="Dicas e solução de problemas">
    * **Seleção de modelo**: Qualquer modelo do [catálogo de modelos da CometAPI](/pt/overview/models) funciona com o método de modelo correspondente — modelos de chat via `cometapi()`, modelos de embedding via `textEmbeddingModel()`, modelos de imagem via `imageModel()`.
    * **Ajuste fino das respostas**: Passe `temperature`, `maxTokens` e `topP` diretamente para `generateText()` ou `streamText()`, por exemplo, `generateText(\{..., temperature: 0.7\})`.
    * **Tratamento de erros**: Envolva as chamadas em `try/catch` para lidar com erros de autenticação, limites de taxa ou problemas de rede.
    * **Segurança**: Nunca faça commit de chaves de API no controle de versão. Use variáveis de ambiente ou um gerenciador de segredos.
    * **Limites de taxa**: Monitore o uso no [console da CometAPI](https://www.cometapi.com/console).
  </Accordion>
</AccordionGroup>

## Recursos relacionados

* [Provedor CometAPI AI SDK no GitHub](https://github.com/cometapi-dev/ai-sdk-provider)
* [@cometapi/ai-sdk-provider no npm](https://www.npmjs.com/package/@cometapi/ai-sdk-provider)
* [Documentação do AI SDK](https://ai-sdk.dev/docs)
* [Início rápido do CometAPI](/pt/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": "Usar AI SDK com CometAPI",
        "description": "Use este guia para configurar o AI SDK com CometAPI definindo a URL base, a chave de API e as opções de model ou provider.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#step-1",
            "position": 1,
            "name": "Instalar o provedor",
            "text": "Conclua a etapa Instalar o provedor no guia Usar AI SDK com CometAPI."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#step-2",
            "position": 2,
            "name": "Defina sua chave de API",
            "text": "Armazene sua chave de API da CometAPI na variável de ambiente ou no campo de configurações usado pela integração."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/ai-sdk#step-3",
            "position": 3,
            "name": "Importar o provedor",
            "text": "Conclua a etapa Importar o provedor no guia Usar AI SDK com CometAPI."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "Documentação da CometAPI",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Integrações",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "Usar AI SDK com CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/ai-sdk"
          }
        ]
      }
    ]
    }
    `}
</script>