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

# Guia de cache de contexto da OpenAI

> Use o cache de 30 minutos ou 12 horas pela Responses API para reutilizar prompts, documentos e prefixos de conversa estáveis.

Nos modelos GPT-5.6 e posteriores compatíveis, defina `prompt_cache_options.ttl` em uma solicitação à [Responses API](https://docs.apimart.ai/pt/api-reference/texts/openai/responses.md) para escolher uma duração mínima de cache de 30 minutos ou 12 horas. Os exemplos usam `gpt-6.1-terra`.

> [!NOTE]
>
> O cache de 12 horas está disponível apenas em `/v1/responses`, não em `/v1/chat/completions`. O TTL indica uma duração mínima, não um prazo de exclusão nem uma garantia de acerto de cache em todas as solicitações.

## Definir a chave de API

```bash theme={null}
export API_KEY="YOUR_API_KEY"
```

> [!NOTE]
>
> O texto longo nos exemplos é ilustrativo. Substitua-o pelo conteúdo que deseja reutilizar. O prefixo precisa ter pelo menos 1.024 tokens; esse texto curto sozinho não gera uma gravação no cache.

## Usar o cache de 30 minutos

Defina `prompt_cache_options.ttl` como `"30m"`. Omitir `ttl` também seleciona 30 minutos. Sem `mode`, o cache é implícito: o serviço de origem escolhe o ponto de cache automaticamente.

```bash theme={null}
curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "30m"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'
```

## Usar o cache de 12 horas

Altere o mesmo campo para `"12h"` e mantenha o restante da estrutura:

```bash theme={null}
curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'
```

## Reutilizar um prefixo fixo com perguntas diferentes

Para reutilizar um documento longo mudando apenas a última pergunta, defina `mode` como `"explicit"` e adicione `prompt_cache_breakpoint` ao bloco `input_text` no final do conteúdo fixo. Este exemplo usa 12 horas; para 30 minutos, altere o TTL da solicitação para `"30m"`.

> [!NOTE]
>
> Definir `mode: "explicit"` sem adicionar um ponto de cache impede leituras e gravações no cache. O ponto abaixo não tem um TTL próprio e herda `prompt_cache_options.ttl` da solicitação.

```bash theme={null}
curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h",
    "mode": "explicit"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the three main points in the reference material."
        }
      ]
    }
  ]
}'
```

Envie o mesmo modelo, prefixo fixo e ponto de cache nas solicitações seguintes, alterando apenas a última mensagem do usuário. Mantenha o conteúdo, a ordem e as configurações que afetam o contexto. Não é necessário criar ou enviar um ID de cache.

## Verificar o uso do cache

Confira `usage.input_tokens_details` na resposta:

* `cached_tokens`: Tokens lidos do cache nesta solicitação. Um valor maior que 0 indica uma leitura do cache.
* `cache_write_tokens`: Total de tokens gravados no cache nesta solicitação.
* `cache_write_tokens_details.ttl_30m_tokens`: Tokens gravados com TTL de 30 minutos nesta solicitação.
* `cache_write_tokens_details.ttl_12h_tokens`: Tokens gravados com TTL de 12 horas nesta solicitação.

Após a primeira gravação, envie outra solicitação com o mesmo prefixo estável e verifique `cached_tokens`. O valor pode ser 0 se o prefixo for curto demais, o conteúdo mudar ou não houver acerto de cache.

### Exemplo de cache usage e contagem de tokens

Este trecho de resposta mostra apenas `usage` de um modelo OpenAI compatível com cache, com gravações para ambos os TTLs. Os valores reais dependem da resposta.

```json theme={null}
{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 5000,
        "ttl_12h_tokens": 2000
      }
    },
    "output_tokens": 1000,
    "total_tokens": 13000
  }
}
```

Tokens de entrada comuns:

```text theme={null}
input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens
```

```text theme={null}
cache_write_tokens = ttl_30m_tokens + ttl_12h_tokens
total_tokens = input_tokens + output_tokens
```

Leituras e gravações no cache já estão incluídas em `input_tokens`. As duas quantidades por TTL são componentes de `cache_write_tokens`: não some novamente o total e seus componentes, nem acrescente leituras e gravações à entrada total.

Aqui, a entrada comum é `12000 - 4000 - 7000 = 1000`, as gravações são `5000 + 2000 = 7000` e o total de tokens é `12000 + 1000 = 13000`.

Consulte o [guia oficial de cache de prompts da OpenAI](https://developers.openai.com/api/docs/guides/prompt-caching) para entender o funcionamento.


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