프롬프트 캐싱

프롬프트 캐싱은 시스템 프롬프트, 문서, 도구 정의처럼 긴 프롬프트에서 이미 처리된 앞부분(prefix)을 여러 요청에 걸쳐 재사용합니다. 캐시 읽기는 일반 입력 토큰보다 훨씬 저렴합니다. api14는 제공자의 캐시 가격을 그대로 전달하며, input_cache_read와 input_cache_write는 모델의 각 모델에 표시됩니다.

자동 캐싱

아래 제공자는 스스로 캐시합니다. 따로 바꿀 것은 없습니다.

요청 간에 앞부분(prefix)이 일치하도록, 변하지 않는 부분은 프롬프트의 처음에, 변하는 부분은 끝에 두세요.

cache_control을 사용한 명시적 캐싱

Anthropic Claude(그리고 Gemini 명시적 캐싱)는 중단점(breakpoint)이 필요합니다. 텍스트 콘텐츠 파트에 cache_control을 추가하세요.

{
  "model": "anthropic/claude-sonnet-4.5",
  "messages": [
    {
      "role": "system",
      "content": [
        { "type": "text", "text": "You are a contracts assistant." },
        {
          "type": "text",
          "text": "<the full 40-page agreement text>",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    { "role": "user", "content": "Which clause covers termination?" }
  ]
}

• Anthropic은 중단점을 최대 4개까지 허용합니다. 캐시는 약 5분간 유지되며 적중할 때마다 갱신됩니다. 더 오래 유지하려면 "ttl": "1h"를 사용하세요. 쓰기 비용이 더 많이 듭니다.
• Anthropic의 캐시 쓰기는 입력의 약 1.25배, 읽기는 약 0.1배입니다.
• 같은 제공자의 캐시를 계속 적중시키려면 필요에 따라 provider: { "order": ["Anthropic"], "allow_fallbacks": false }를 추가하세요.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api14.com/api/v1",
  apiKey: process.env.API14_API_KEY,
});

const result = await client.chat.completions.create({
  "model": "anthropic/claude-sonnet-4.5",
  "messages": [
    {
      "role": "user",
      "content": "Explain vector databases in two sentences."
    }
  ]
});
console.log(result.choices[0].message.content);

캐시 사용량 확인

usage 객체에 캐시된 토큰이 표시되며, cost에는 이미 할인이 반영되어 있습니다.

{
  "usage": {
    "prompt_tokens": 10450,
    "completion_tokens": 120,
    "total_tokens": 10570,
    "prompt_tokens_details": { "cached_tokens": 10200 },
    "cost": 0.004863
  }
}

cached_tokens는 대시보드의 사용량 로그에도 표시됩니다. 생성 조회에서는 cache_discount를 포함한 전체 내역을 볼 수 있습니다.

오류

캐싱 자체가 오류를 일으키지는 않습니다. 잘못된 형식의 cache_control은 제공자가 무시하거나 400으로 거부합니다. 오류를 참고하세요.