> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alterhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Serviço de Gateway & Router API

> Use Alter como um endpoint compatível com OpenAI API para acessar modelos de IA 92+

O Alter fornece um endpoint compatível com APIs OpenAI que permite usar o Alter como roteador unificado para acessar modelos de IA 92+ de provedores 10+. Use a API Alter como backend para aplicativos de terceiros ou como um serviço de API direto para seus projetos personalizados.

<Warning>
  **Uso pretendido:** o API Router foi projetado para uso pessoal, utilitarios leves e projetos de baixo volume. Ele **nao** foi projetado para sistemas agentic de alto throughput nem para servicos multiusuario.
</Warning>

## Visão geral

O gateway de API Alter é um roteador centralizado que elimina a necessidade de gerenciar várias chaves de API e contas de faturamento em diferentes provedores de IA. Em vez de ter seus detalhes de faturamento espalhados por muitos provedores, você pode usar Alter como seu único ponto de entrada para acesso ao modelo de IA.

### O que é o Alter Router?

Alter em si é um serviço **router**—um gateway de API unificado que fornece acesso a:

* 10+ fornecedores de modelos de IA (OpenAI, Gemini, Claude, Mistral, etc.)
* 92+ modelos individuais de IA
* Autenticação e faturamento simplificados
* Fácil mudança de modelo sem alterações de código

## Características chave

* \*\* Endpoint compatível com o OpenAI\*\* que suporta completações de chat e listagem de modelos
* \*\* Cobrança centralizada\*\* através da sua conta Alter
* **Acesso a todos os modelos** de aplicações externas ou código personalizado
* \*\* Integração sem costura\*\* com Tools compatíveis com OpenAI existentes e SDKs
* \*\* Seleção de modelo flexível\*\* em todos os fornecedores

## Começar

### 1. Gerar a chave da API

1. Abra as configurações do Alter (\*\* ,\*\* ou menu Configurações)
2. Ir para **Router** tab
3. Na seção "Alter API Keys", clique em "Adicionar Nova Chave" para gerar uma nova chave API
4. Copie sua chave (começa com `sk-`)

**Importante:** Nunca compartilhe sua chave API. Trata-a como uma senha.

### 2. Obtenha o ponto final

O ponto final do roteador Alter é:

```
https://alterhq.com/api
```

Para algumas Tools, pode precisar de adicionar `/v1`:

```
https://alterhq.com/api/v1
```

### 3. Lista modelos disponíveis

Verifique quais modelos estão disponíveis:

```bash theme={null}
curl https://alterhq.com/api/models \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Isso retorna todos os modelos 92+ em 10 provedores com suas capacidades.

## Convenção de nomeação de modelos

Ao usar a API Alter, os nomes dos modelos seguem este formato:

```
<Provider>#<Model-name>
```

### Exemplos:

* `OpenAI#gpt-5` - Último GPT-5
* `OpenAI#gpt-5-nano` - GPT Leve
* `Claude#claude-sonnet-4-6` - Último Claude
* `Gemini#gemini-2.5-pro` - Último Gemini
* `Mistral#mistral-small-latest` - Modelo Mistral
* `Alter#best` - Melhor modelo de Alter

## Métodos de Uso

### Para aplicações de terceiros

Usar o Alter como infra- estrutura para Tools como SillyTavern, NovelCrafter, etc.:

1. Definir URL base: `https://alterhq.com/api` (ou `/v1`)
2. Digite sua chave de API
3. Usar o formato `Provider#Model-name` ao selecionar modelos

### Para Desenvolvimento Personalizado

#### Python (com OpenAI SDK)

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://alterhq.com/api/v1"
)

response = client.chat.completions.create(
    model="OpenAI#gpt-5",
    messages=[
        {"role": "user", "content": "What is machine learning?"}
    ]
)

print(response.choices[0].message.content)
```

#### JavaScript (com OpenAI SDK)

```javascript theme={null}
import OpenAI from 'openai';

const openai = new OpenAI({
    apiKey: "YOUR_API_KEY",
    baseURL: "https://alterhq.com/api/v1",
    dangerouslyAllowBrowser: true
});

const completion = await openai.chat.completions.create({
    model: "OpenAI#gpt-5",
    messages: [
        {"role": "user", "content": "Hello!"}
    ]
});

console.log(completion.choices[0].message.content);
```

#### LangChain (Píton)

```python theme={null}
from langchain_openai import ChatOpenAI

chat = ChatOpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://alterhq.com/api/v1",
    model="OpenAI#gpt-5"
)

response = chat.invoke("What is AI?")
print(response.content)
```

#### CURL direto

```bash theme={null}
curl https://alterhq.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "OpenAI#gpt-5",
    "messages": [
      {"role": "user", "content": "What is machine learning?"}
    ]
  }'
```

## Guia de Seleção do Modelo

### Velocidade

* `Alter#light` - Modelo leve
* `OpenAI#gpt-5-nano` - GPT Leve
* `Gemini#gemini-2.5-flash-lite` - Rápido Gemini

### Para a qualidade

* `Alter#best` - Melhor disponível
* `OpenAI#gpt-5` - GPT mais capaz
* `Gemini#gemini-2.5-pro` - Poderoso Gemini
* `Claude#claude-sonnet-4-6` - Último Claude

### Para visão/imagens

* `OpenAI#gpt-5` - Multimodal Avançado
* `Gemini#gemini-2.5-pro` - Visão forte
* `Mistral#pixtral-large-latest` - Capaz de visão

### Para codificação

* `OpenAI#gpt-5` - Código excelente
* `Mistral#codestral-2501` - Especialista em códigos
* `Claude#claude-sonnet-4-6` - Código forte

### Por Custo

* `Alter#fair` - Custo-efetivo
* `Alter#light` - O mais barato
* `OpenAI#gpt-5-nano` - Orçamento GPT

### Para pesquisa na Web

* `Perplexity#sonar` - Informação Web
* `Perplexity#sonar-pro` - Pesquisa avançada

## Parâmetros Suportados

Parâmetros padrão da API OpenAI funcionam com Alter:

* `model` - ID do modelo (obrigatório)
* `messages` - Mensagens de chat (obrigatórias)
* `temperature` - 0.0-2. 0 (por omissão: 1. 0)
* `max_tokens` - Comprimento máximo de resposta
* `top_p` - Amostragem de núcleos
* `frequency_penalty` - Penalizar a repetição
* `presence_penalty` - Incentivar novos tópicos

## Casos de Uso Popular

### Integração de aplicativos de terceiros

* \*\* [SillyTavern](https://sillytavern.app/)\*\* - Conversa de representação
* **[NovelCrafter](https://www.novelcrafter.com/)** - Escrita criativa
* Outras Tools compatíveis com o OpenAI

### Infra- Estrutura de Aplicação Personalizada

* Tools internas que necessitam de IA
* Automação de suporte ao cliente
* Sistemas de geração de conteúdo
* Fluxos de trabalho de análise de dados

### Modelo Comparação e Teste A/B

```python theme={null}
for model_id in ["OpenAI#gpt-5", "Claude#claude-sonnet-4-6", "Gemini#gemini-2.5-pro"]:
    # Run same prompt on different models
    # Compare outputs
```

### Otimização de custos

Use modelos mais baratos para tarefas de alto volume, modelos poderosos para consultas complexas.

## Configuração

### Gerenciamento de Chaves de API

* Gerar e gerenciar chaves de API através de **Settings > Router**
* Mantenha as chaves API seguras – nunca as compartilhe publicamente
* Rodar as teclas regularmente para segurança
* Usar chaves diferentes para ambientes diferentes (dev/prod)

### Limites de Utilização

O gateway API tem limitações de uso justo:

* **Diário Limite**: 200 pedidos por dia em uso justo
* \*\* Throttling\*\*: Após exceder o limite diário, os pedidos de aceleração para 1 por 10 minutos
* **Orçamento Top-up**: "Top up" seu orçamento para acesso consistente além dos limites de uso justo

## Solução de problemas

### Modelos não listados

Se o seu aplicativo não lista modelos disponíveis:

* Especificar manualmente o modelo usando o formato `Provider#Model-name`
* Verificar se sua chave API está correta
* Verifique se o aplicativo suporta o ponto final da listagem de modelos

### Erros de autenticação

* Verificar se sua chave API está corretamente inserida
* Certifique-se de que está a utilizar o endpoint correcto: `https://alterhq.com/api` ou `https://alterhq.com/api/v1`
* Verifique se sua conta Alter está ativa e em boa posição

### Problemas de Ligação

* Verifique se a aplicação suporta parâmetros compatíveis com OpenAI
* Certifique-se de que está a utilizar a versão mais recente do Alter
* Verifique a conectividade de rede com `alterhq.com`

### Alta Latência

* Tente um modelo mais rápido (por exemplo, `OpenAI#gpt-5-nano`)
* Verifique sua conexão de rede
* Usar streaming para respostas longas

## Melhores Práticas

1. **Secure sua chave de API** - Usar variáveis de ambiente, nunca código rígido
2. \*\* Uso do monitor\*\* - Acompanhe chamadas de API e ajuste alertas
3. \*\* Escolha modelos apropriados\*\* - Match model capacidade para complexidade de tarefas
4. \*\* Erros de mão graciosamente\*\* - Implementar lógica de repetição com backoff
5. **Otimizar custos** - Usar modelos mais rápidos/mais baratos para tarefas de rotina

## Documentos Relacionados

* [Ligando seu modelo](/how-to/choose-generative-model)
* [Configurações - Configuração do Roteador](/how-to/settings-guide#router-settings)
* [Configurações - Teclas API](/how-to/settings-guide#api-keys-settings)