> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 비용 최적화

> BeatAPI 계정에서 실제로 비용이 어디에 쓰이는지, 그리고 효과가 큰 순서대로 어떤 방법으로 줄일 수 있는지 설명합니다.

# 비용 최적화

'더 저렴한 모델을 쓰라'는 조언이 항상 정답은 아닙니다. 이 페이지는 각 방법이 보통 청구 금액을 얼마나 줄이는지를 기준으로 정리했습니다.

## 1. 출력에 상한을 두세요

거의 모든 모델에서 출력 토큰은 입력 토큰보다 몇 배 비싸며, 따로 지정하지 않으면 출력 길이는 모델이 정합니다.

```json
{ "model": "claude-sonnet-5", "max_tokens": 800, "messages": [...] }
```

짧은 답이 핵심인 추출, 분류, 라우팅에서는 출력 상한만 설정해도 거의 공짜로 비용을 아낄 수 있습니다. 문제가 생겨도 조용히 넘어가지 않고 드러난다는 장점도 있습니다. 잘린 응답은 눈에 보이지만, 상한 없는 응답은 그저 비용만 더 듭니다.

## 2. 단계에 맞는 모델을 고르세요

대부분의 파이프라인에는 정말로 가장 강력한 모델이 필요한 단계가 하나 있고, 그렇지 않은 단계가 여럿 있습니다. 라우팅, 의도 파악, 태깅, 형식 변환은 가장 저렴한 모델로도 충분합니다.

```python
def model_for(step):
    if step in ("route", "classify", "extract"):
        return "glm-5.3-flash"
    if step == "draft":
        return "claude-sonnet-5"
    return "claude-fable-5-1"
```

이렇게 파이프라인을 나누면 저렴한 단계가 가장 자주 실행되기 때문에, 보통 모델 하나를 바꾸는 것보다 비용 절감 효과가 큽니다.

## 3. 캐시가 동작하도록 앞부분을 재사용하세요

캐시된 입력은 새 입력보다 훨씬 저렴하게 과금됩니다. 고정된 시스템 프롬프트와 고정된 문서 앞부분을 요청의 *시작*에 두고 호출 간에 바이트 단위까지 똑같이 유지하면 캐시가 적용됩니다.

캐시를 깨뜨리는 요인은 앞부분에 타임스탬프, 요청 ID, 순서가 바뀌는 목록을 넣는 것입니다. 바뀌는 내용은 모두 끝에 두세요.

## 4. 가격이 바뀌는 모델을 파악하세요

두 계열은 놓치기 쉬운 조건에서 더 많이 과금됩니다.

* **피크 시간대.** DeepSeek HC(high-cache) 모델 두 개는 평일 베이징 시간 09:00–12:00와 14:00–18:00에 요금이 두 배가 되며, 일반 유료 DeepSeek 모델은 시간과 관계없이 같은 요금입니다. Hunyuan `hy3`에는 별도의 일일 시간대가 있습니다. 야간 배치는 저렴하지만, 같은 배치를 화요일 10:00에 돌리면 그렇지 않습니다.
* **컨텍스트 구간.** GPT-5.6 계열과 Grok 계열은 컨텍스트가 일정 기준을 넘으면 더 높은 요금이 적용됩니다. 긴 에이전트 세션은 클라이언트에 아무 신호 없이 이 기준을 넘습니다.

정확한 시간과 기준은 [가격 페이지](https://beatapi.io/pricing) 각주에 있으며, 각 응답의 사용량 기록에서 어떤 요금이 적용되었는지 확인할 수 있습니다. 배치를 피크 시간대 밖으로 옮기는 일은 cron 표현식 하나만 바꾸면 됩니다.

## 5. 컨텍스트를 줄이세요

컨텍스트는 한 번이 아니라 대화의 매 턴마다 과금됩니다. 두 가지 습관이 가장 큰 차이를 만듭니다.

* **대화 기록을 줄이세요.** 40번째 턴에서 대화 전체를 보내면 1번째 턴 내용을 마흔 번 결제하는 셈입니다. 요약하거나 최근 구간만 보내세요.
* **파일 전체가 아니라 선택한 부분만 보내세요.** 코딩 도구에서는 이것이 가장 큰 절감 수단입니다. [Cursor](/integrations/cursor)와 [Cline](/integrations/cline)은 허용하면 열려 있는 버퍼 전체를 보냅니다.

## 6. 중간에 멈출 수 있도록 스트리밍하세요

`stream: true`는 완료된 응답의 가격을 바꾸지 않지만, 수백 토큰 만에 잘못된 방향으로 흘러간 응답을 끝까지 결제하지 않고 중단할 수 있게 해 줍니다. 애플리케이션도 더 빠르게 느껴지므로 어느 경우든 적용할 가치가 있습니다.

## 7. 최적화하기 전에 측정하세요

애플리케이션, 도구, 환경마다 별도의 API 키를 발급하세요. 그러면 별도 계측 없이 `GET /v1/usage`의 `by_api_key`에서 지출이 구분되고, `by_model`에서 실제로 어떤 모델이 비용을 쓰는지 알 수 있습니다.

```bash
curl https://api.beatapi.io/v1/usage \
  -H "Authorization: Bearer $BEATAPI_API_KEY"
```

어떤 연동이 비싼지 짐작하면 대개 틀립니다. 아주 작은 호출을 수천 번 하는 브라우저 번역 확장 프로그램과 거대한 호출을 몇 번 하는 에이전트는 청구서에서 전혀 다르게 보입니다.

## 8. 환불 내역을 대조하세요

실패한 작업은 환불됩니다. 장부에 보류 금액만 기록하고 환불을 읽지 않으면 내부 수치가 지출을 실제보다 크게 잡게 되고, 존재하지 않는 숫자를 기준으로 최적화하게 됩니다. 이런 이유로 `GET /v1/usage`는 `credits_settled`와 `credits_refunded`를 따로 보고합니다.

## 도움이 되지 않는 것

* **공격적으로 재시도하기.** `400`을 재시도하면 같은 잘못된 요청을 같은 가격에 보내는 것입니다. `429`와 `5xx`만 재시도하세요. [개발 가이드](/development)를 참고하세요.
* **더 빨리 폴링하기.** 폴링한다고 작업 실행이 빨라지지 않습니다. 같은 상태를 반복해서 요청하지 말고 `poll_after_seconds`를 따르세요.
* **모델을 낮췄다가 두 번 시도하게 되는 경우.** 다시 실행해야 하거나 비싼 모델로 고쳐야 하는 저렴한 모델은 처음부터 제대로 한 번 처리하는 것보다 비쌉니다. 단가가 아니라 파이프라인 전체를 측정하세요.