> ## 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/ko/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별 값은 `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.