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

# Cache de respostas de LLM

> Armazene em cache solicitações idênticas a LLMs para reduzir a latência e os custos de API. Configure o cache de respostas por correspondência exata com TTL para consultas repetidas e buscas em FAQs.

**Casos de uso**

* Eliminar custos redundantes em consultas idênticas repetidas (FAQs, buscas de produtos).
* Acelerar os ciclos de desenvolvimento e testes armazenando em cache solicitações de fixtures.
* Servir o mesmo prompt a muitos usuários simultâneos sem pagar por chamada.
* Reduzir a latência de cauda em endpoints chamados com frequência.

***

## Início rápido

Armazene em cache solicitações idênticas para reduzir a latência em cerca de 95% e economizar custos.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [{ "role": "user", "content": "Explain renewable energy" }],
    "cache": { "type": "exact_match", "ttl": 3600 }
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "Explain renewable energy",
  cache: {
    type: "exact_match",
    ttl: 3600,
  },
});

console.log(response.output_text);
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [{ role: "user", content: "Explain renewable energy" }],
  cache: {
    type: "exact_match",
    ttl: 3600,
  },
});

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

## Configuração

| Parâmetro | Tipo | Obrigatório | Descrição | Exemplo |
| - | - | - | - | - |
| `type` | `"exact_match"` | Sim | Único tipo de cache compatível | `"exact_match"` |
| `ttl` | number | Não | Expiração do cache em segundos (padrão: 3600, máximo: 259200) | `3600` |

**Chave de cache**: gerada a partir de modelo + entrada + todos os parâmetros. Solicitações idênticas compartilham a mesma chave.

## Recomendações de TTL

| Caso de uso | TTL (segundos) | Motivo |
| - | - | - |
| Respostas de FAQ | `86400` (24h) | Conteúdo estático |
| Geração de conteúdo | `3600` (1h) | Atualidade moderada |
| Desenvolvimento/testes | `300` (5min) | Iteração rápida |
| Análise de dados | `1800` (30min) | Equilíbrio entre velocidade e atualidade |

## Exemplos de código

> [!NOTE]
>
> Os exemplos abaixo usam o endpoint Chat Completions. O mesmo parâmetro `cache` se aplica à Responses API: substitua `chat.completions.create(...)` por `responses.create(...)`.

```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [
      {
        "role": "user",
        "content": "Explain the benefits of renewable energy for businesses"
      }
    ],
    "cache": {
      "type": "exact_match",
      "ttl": 3600
    }
  }'
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [
    {
      role: "user",
      content: "Explain the benefits of renewable energy for businesses",
    },
  ],
  cache: {
    type: "exact_match",
    ttl: 3600,
  },
});
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
  api_key=os.environ.get("TOQAN_API_KEY"),
  base_url="https://router.toqan.ai/eu/v3/router"
)

response = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    messages=[
        {
            "role": "user",
            "content": "Explain the benefits of renewable energy for businesses"
        }
    ],
    extra_body={
        "cache": {
            "type": "exact_match",
            "ttl": 3600
        }
    }
)
```

## Solução de problemas

**Baixa taxa de acertos no cache**

* Garanta parâmetros idênticos (temperature, max\_tokens etc.).
* Verifique se o TTL não é curto demais para o seu caso de uso.
* Confirme se as solicitações são de fato idênticas (diferencia maiúsculas de minúsculas).

**O cache não está funcionando**

* Confirme se `type: "exact_match"` está especificado.
* Verifique o status do cache nos cabeçalhos da resposta.

**Problemas de desempenho**

* Use um TTL mais curto para conteúdo dinâmico.
* Considere pré-aquecer o cache para solicitações previsíveis.
* Monitore as taxas de acerto/erro do cache.

## Limitações

* **Apenas correspondência exata**: qualquer alteração de parâmetro cria uma nova chave de cache.
* **Diferencia maiúsculas de minúsculas**: "Hello" e "hello" são chaves de cache diferentes.
* **Sem correspondência semântica**: solicitações semelhantes, mas não idênticas, não correspondem.
* **Limites de armazenamento**: respostas muito grandes consomem mais espaço de cache.
* **Restrições de TTL**: mínimo de 1 segundo e máximo de 259200 segundos (3 dias).

## Boas práticas

* Defina o TTL com base nos requisitos de atualidade do conteúdo.
* Use o cache para solicitações repetidas e determinísticas.
* Monitore as taxas de acerto do cache para otimizar os valores de TTL.
* Evite armazenar em cache conteúdo personalizado ou sensível ao tempo.
* Teste o comportamento do cache em desenvolvimento antes de levar para produção.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.