prompt_cache_options.ttl로 최소 캐시 유지 시간을 30분 또는 12시간으로 선택합니다. 예제는 gpt-6.1-terra를 사용합니다.
12시간 캐시는
/v1/responses에서만 지원되며 /v1/chat/completions에서는 지원되지 않습니다. TTL은 최소 유지 시간이며, 즉시 삭제 시점이나 모든 요청의 캐시 적중을 보장하지 않습니다.API 키 설정
예제의 긴 텍스트는 자리 표시자입니다. 재사용할 실제 내용으로 바꾸세요. 캐시할 접두부는 최소 1,024 토큰이어야 하며, 이 짧은 자리 표시자만으로는 캐시가 기록되지 않습니다.
30분 캐시 사용
prompt_cache_options.ttl을 "30m"으로 설정합니다. ttl을 생략해도 30분이 적용됩니다. mode를 생략하면 업스트림 서비스가 캐시 중단점을 자동 선택하는 암시적 캐시를 사용합니다.
12시간 캐시 사용
같은 필드를"12h"로 바꾸고 나머지 요청 구조는 그대로 유지합니다.
고정 접두부로 서로 다른 질문 처리
같은 긴 문서를 재사용하고 마지막 질문만 바꾸려면mode를 "explicit"으로 설정하고 고정 내용 끝의 input_text 블록에 prompt_cache_breakpoint를 추가합니다. 아래 예제는 12시간을 사용합니다. 30분을 사용하려면 요청의 ttl을 "30m"으로 바꾸세요.
중단점 없이
mode: "explicit"만 설정하면 캐시를 읽거나 쓰지 않습니다. 아래 중단점에는 별도 TTL이 없으므로 요청의 prompt_cache_options.ttl을 상속합니다.캐시 사용량 확인
응답의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만 표시합니다. 실제 수치는 응답에 따라 달라집니다.
input_tokens에 포함됩니다. 두 TTL별 값은 cache_write_tokens의 구성 요소입니다. 총량과 상세 값을 중복해서 더하거나 캐시 읽기와 쓰기를 총 입력량에 다시 더하지 마세요.
이 예제에서 일반 입력은 12000 - 4000 - 7000 = 1000, 쓰기는 5000 + 2000 = 7000, 총 토큰 수는 12000 + 1000 = 13000입니다.
캐시 동작은 OpenAI 공식 캐시 가이드를 참고하세요.