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

# OpenAI コンテキストキャッシュ利用ガイド

> Responses API で 30 分または 12 時間のキャッシュを使用し、固定のプロンプト、文書、会話のプレフィックスを再利用します。

この機能に対応する GPT-5.6 以降のモデルでは、[Responses API](https://docs.apimart.ai/ja/api-reference/texts/openai/responses.md) のリクエストで `prompt_cache_options.ttl` を設定し、キャッシュの最小保持時間を 30 分または 12 時間から選択できます。例では `gpt-6.1-terra` を使用します。

> [!NOTE]
>
> 12 時間のキャッシュは `/v1/responses` のみ対応し、`/v1/chat/completions` では使用できません。TTL は最小保持時間であり、削除期限や毎回のキャッシュヒットを保証するものではありません。

## API キーを設定する

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

> [!NOTE]
>
> 例の長文はプレースホルダーです。再利用する実際の内容に置き換えてください。キャッシュ対象のプレフィックスには 1,024 トークン以上が必要です。この短いプレースホルダーだけではキャッシュは書き込まれません。

## 30 分のキャッシュを使用する

`prompt_cache_options.ttl` を `"30m"` に設定します。`ttl` を省略しても 30 分になります。`mode` の省略時は暗黙的キャッシュが使用され、上流サービスがキャッシュのブレークポイントを自動で選択します。

```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."
        }
      ]
    }
  ]
}'
```

## 12 時間のキャッシュを使用する

同じフィールドを `"12h"` に変更します。他のリクエスト構造は同じです。

```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."
        }
      ]
    }
  ]
}'
```

## 固定プレフィックスで異なる質問に対応する

同じ長文を再利用して最後の質問だけを変更する場合は、`mode` を `"explicit"` にし、固定内容の末尾の `input_text` ブロックに `prompt_cache_breakpoint` を追加します。この例は 12 時間です。30 分にするにはリクエストの `ttl` を `"30m"` に変更してください。

> [!NOTE]
>
> `mode: "explicit"` のみを設定し、ブレークポイントを追加しない場合、キャッシュの読み書きは行われません。以下のブレークポイントには個別の TTL がないため、リクエストの `prompt_cache_options.ttl` を継承します。

```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."
        }
      ]
    }
  ]
}'
```

次回以降も同じモデル、固定プレフィックス、ブレークポイントを送信し、最後のユーザーメッセージだけを変更します。プレフィックスの内容、順序、コンテキストに影響する設定を揃えてください。キャッシュ ID の作成や指定は不要です。

## キャッシュの利用状況を確認する

レスポンスの `usage.input_tokens_details` を確認します。

* `cached_tokens`: 今回キャッシュから読み取ったトークン数。0 より大きければキャッシュが読み取られています。
* `cache_write_tokens`: 今回キャッシュに書き込んだトークンの合計数。
* `cache_write_tokens_details.ttl_30m_tokens`: 今回 30 分の TTL で書き込んだトークン数。
* `cache_write_tokens_details.ttl_12h_tokens`: 今回 12 時間の TTL で書き込んだトークン数。

初回の書き込み後、同じ固定プレフィックスで再度リクエストし、`cached_tokens` を確認してください。プレフィックスが短すぎる場合、内容が変わった場合、キャッシュにヒットしない場合は 0 になることがあります。

### キャッシュ usage の例と集計方法

以下は、キャッシュに対応する OpenAI モデルで両方の TTL の書き込みがある場合のレスポンス抜粋です。`usage` のみを示しています。値は実際のレスポンスで確認してください。

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

通常の入力トークン数:

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

キャッシュの読み書きは `input_tokens` に含まれています。TTL 別の 2 つの値は `cache_write_tokens` の内訳です。合計と内訳を重複して加算したり、キャッシュの読み書きを入力合計に加算したりしないでください。

この例では、通常の入力は `12000 - 4000 - 7000 = 1000`、書き込みは `5000 + 2000 = 7000`、合計トークン数は `12000 + 1000 = 13000` です。

キャッシュの動作は [OpenAI 公式キャッシュガイド](https://developers.openai.com/api/docs/guides/prompt-caching)を参照してください。


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