SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Claude API 파이썬 연동 및 VPS 배포 튜토리얼

Ubuntu 24.04 환경에서 Claude API 키를 안전하게 관리하고 Python으로 로그 분석기를 개발하는 방법을 설명합니다. 스트리밍 응답 처리, 타입 기반 예외 처리, systemd를 이용한 상시 구동 설정 및 API 비용 제어 전략을 포함한 실무 중심의 가이드를 제공합니다.

무엇을 만드는가

Ubuntu 24.04 기반의 신규 VPS에서 에러 메시지나 로그 조각을 파이프로 전달하면 평이한 언어로 진단 결과를 출력하는 명령줄 도구입니다: journalctl -u nginx -n 50 | explain. 이 도구는 약 60줄 정도의 Python 코드로 구성되며, 실제 Claude API 애플리케이션에 필요한 모든 요소를 다룹니다. 여기에는 올바르게 저장된 키, virtualenv, SDK 응답 형태, 스트리밍, 타입이 지정된 예외 체인, 그리고 상시 구동을 위한 systemd 유닛이 포함됩니다.

이 프로젝트를 선택한 데에는 의도가 있습니다. 대부분의 "첫 API 앱" 튜토리얼은 다시는 열어보지 않을 챗봇을 만들게 합니다. 반면 로그 분석기는 서버에서 첫날부터 제 역할을 하며, 초보자가 흔히 실수하는 두 가지, 즉 응답 객체를 올바르게 읽는 법과 비용을 제어하는 법을 익히게 합니다. API는 토큰 단위로 과금되며 사용자가 설정한 한도 외에는 상한선이 없습니다. 따라서 비용 제어는 나중에 고려할 사항이 아니라 설계 단계부터 반영해야 할 핵심 요소입니다. 이는 나중에 동일한 VPS의 tmux 환경에서 Claude Code를 실행하는 단계로 나아갈 때 필요한 규율과 같습니다.

콘솔에서 API 키 발급받기

API 접근 권한은 platform.claude.com의 Anthropic Console에서 관리합니다. 가입 후 Settings → API Keys 메뉴에서 키를 생성하십시오(문서 바로가기: platform.claude.com/settings/keys). 콘솔에서 키 이름 지정, 만료일 설정, 사용자 또는 서비스 계정 연결을 요청합니다. Anthropic은 프로덕션 서비스나 공유되는 모든 항목에 대해 서비스 계정 키 사용을 권장합니다. 키는 생성 시 한 번만 표시되며 sk-ant-로 시작합니다. 다시 확인할 수 없으므로 즉시 복사하거나, 분실 시 삭제 후 재발급받아야 합니다.

비용 관련 안내: 2026년 10월 기준으로 API에 대한 상시 무료 티어는 없습니다. Anthropic의 가격 정책 문서에 따르면 신규 사용자는 테스트를 위한 소액의 무료 크레딧을 받습니다. 정확한 금액은 가입 시 콘솔에 표시되는 금액이며, 소진 후에는 요청이 성공하도록 계정에 자금을 충전해야 합니다. 이는 claude.ai 구독과는 별개이며, API 키로 채팅 앱을 이용할 수는 없습니다. Pro 플랜에는 API 크레딧이 포함되어 있지 않으나, Max 및 Team 플랜에는 포함되어 있습니다. 2026년 10월 기준, Max 5x는 월 100달러, Max 20x는 월 200달러입니다(Team 플랜은 Standard 좌석당 20달러, Premium 좌석당 100달러이며 최대 500달러로 제한됩니다). 이는 claude.ai 결제 설정에서 콘솔 조직을 연결하여 적용받을 수 있습니다. 사용하지 않은 크레딧은 각 결제 주기 종료 시 소멸하며 Claude Code에는 적용되지 않습니다. 자세한 내용은 Max 및 Team 월간 API 크레딧 작동 방식을 참조하십시오. 구독과 API 중 무엇을 선택할지 고민 중이라면 다음 문서를 확인하십시오: 나에게 필요한 Claude 플랜 선택하기.

키는 하나의 프로젝트나 서버에만 적용되도록 범위를 제한하여 생성하십시오. 키가 유출되는 상황은 언젠가 발생할 수 있으므로, 다른 모든 서비스에 영향을 주지 않고 해당 키만 즉시 폐기할 수 있도록 관리해야 합니다.

키를 .bashrc에 보관하지 마십시오

반사적으로 export ANTHROPIC_API_KEY=sk-ant-...을 ~/.bashrc에 추가하는 경우가 많습니다. 하지만 그렇게 하지 마십시오. 세 가지 문제가 발생합니다.

  • 모든 프로세스가 이를 상속합니다. 로그인 셸에서 export한 환경 변수는 웹 애플리케이션, 환경 변수를 버그 리포트에 그대로 출력하는 크래시 리포터, 누군가 활성화해 둔 phpinfo() 페이지 등 실행하는 모든 것에 전파됩니다. 키가 노출될 수 있는 범위가 "해당 사용자가 실행하는 모든 것"으로 확대됩니다.
  • 입력 내용이 ~/.bash_history에 남습니다. export 명령을 직접 입력하면 키가 일반 텍스트 파일에 영구적으로 저장되며, 홈 디렉터리의 모든 백업본에 포함됩니다.
  • systemd가 필요할 때 키를 찾을 수 없습니다. 서비스는 사용자의 .bashrc을 읽지 않습니다. 따라서 스크립트를 서비스 유닛으로 승격하는 순간 이 방식은 실패하며, 보통 새벽 6시에 알 수 없는 401 오류로 나타납니다.

서버에서 올바른 방식은 600 권한을 가진 전용 환경 변수 파일을 사용하는 것이며, 해당 키가 필요한 프로세스만 이 파일을 로드하게 하는 것입니다.

sudo mkdir -p /opt/explain
sudo install -m 600 -o root -g root /dev/null /etc/claude-explain.env
printf 'ANTHROPIC_API_KEY=sk-ant-YOUR-KEY-HERE\n' | sudo tee /etc/claude-explain.env >/dev/null

편집기의 스왑 파일에 키가 남는 것을 방지하려면 편집기 대신 printf를 사용하여 tee를 생성하십시오. 어떤 방법을 사용하든 ls -l /etc/claude-explain.env을 통해 파일이 -rw-------로 읽히는지, 그리고 소유자가 root인지 확인하십시오. 대화형 셸은 아래의 래퍼를 통해 호출 시마다 키를 가져오고, systemd는 EnvironmentFile=를 통해 키를 가져옵니다. root가 권한을 낮추기 전에 파일을 읽으므로 서비스 사용자는 파일에 대한 읽기 권한이 필요 없습니다. 키는 코드, git, ps 출력, 셸 기록 어디에도 나타나지 않습니다.

venv에 SDK 설치하기

Ubuntu 24.04는 PEP 668이 적용된 Python 3.12를 제공하므로, 시스템 인터프리터에 직접 pip install anthropic을 실행하면 error: externally-managed-environment 오류가 발생합니다. 이 오류는 운영체제가 의도한 대로 작동하는 것이며, virtualenv를 사용해야 합니다.

sudo apt update && sudo apt install -y python3-venv
sudo python3 -m venv /opt/explain/venv
sudo /opt/explain/venv/bin/pip install anthropic

서버에서는 별도의 활성화 과정이 필요 없습니다. /opt/explain/venv/bin/python를 직접 호출하면 항상 venv의 패키지를 사용합니다.

첫 호출과 응답을 올바르게 읽는 방법

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Explain what a systemd unit file is in three sentences."}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

위 12줄의 코드에는 해당 API의 핵심적인 사고방식이 담겨 있습니다. 첫째, anthropic.Anthropic()를 인자 없이 호출하면 환경 변수에서 키를 읽어옵니다. 문자열 리터럴로 직접 전달하지 마십시오. 둘째, response.content는 문자열이 아니라 콘텐츠 블록의 리스트입니다. 이를 그대로 출력하면 초보자가 흔히 겪는 다음과 같은 결과가 나타납니다.

[TextBlock(citations=None, text='A systemd unit file is...', type='text')]

이는 버그가 아니라 객체의 repr입니다. 응답에는 여러 블록 유형(텍스트, 도구 호출, 사고 과정)이 포함될 수 있으므로, .text에 접근하기 전에 반복문을 통해 block.type == "text"를 확인해야 합니다. Opus 5.5에서는 첫 호출부터 이 점이 중요합니다. 사고 과정(thinking) 기능이 항상 켜져 있기 때문입니다. 모델이 단순한 요청에서 사고 과정을 생략하지 않는 한, 리스트는 기본적으로 텍스트가 비어 있는 thinking 블록으로 시작하며, response.content[0].text은 사용자가 원하는 답변이 아닙니다. 첫날부터 이 반복문을 구현해 두면 "출력값이 이상하다"는 식의 혼란을 원천적으로 방지할 수 있습니다.

모델 ID는 반드시 claude-opus-5-5을 사용하십시오. 4.6 세대부터 모델 ID에는 날짜가 포함되지 않으며, 날짜가 없는 ID가 고정된 스냅샷을 가리킵니다. 현재 모델에 날짜 접미사를 붙여야 한다는 습관(또는 오래된 블로그 게시물)을 따르지 마십시오. 이는 아래에서 다룰 404 오류를 발생시킵니다. 이전 모델들은 반대로 작동합니다. Haiku 4.5의 표준 ID는 날짜가 포함된 claude-haiku-4-5-20251001입니다.

실제 도구: 설명

전체 프로그램은 표준 입력(stdin)을 받아 스트리밍 방식으로 진단 결과를 출력하며, 오류를 처리합니다:

#!/usr/bin/env python3
"""explain: pipe an error or log excerpt in, get a diagnosis out."""
import sys
import anthropic

MODEL = "claude-opus-5-5"

def main() -> int:
    text = sys.stdin.read().strip()
    if not text:
        print("usage: journalctl -u nginx -n 50 | explain", file=sys.stderr)
        return 1

    client = anthropic.Anthropic()
    try:
        with client.messages.stream(
            model=MODEL,
            max_tokens=4096,
            system=(
                "You are a senior Linux sysadmin. The user pipes you server "
                "logs or error output. Name the most likely cause outright, "
                "then give the commands to confirm and fix it. Be terse."
            ),
            messages=[{"role": "user", "content": text}],
        ) as stream:
            for chunk in stream.text_stream:
                print(chunk, end="", flush=True)
        print()
    except anthropic.RateLimitError as e:
        retry_after = e.response.headers.get("retry-after", "60")
        print(f"rate limited; retry in {retry_after}s", file=sys.stderr)
        return 2
    except anthropic.APIStatusError as e:
        print(f"API error {e.status_code}: {e.message}", file=sys.stderr)
        return 2
    except anthropic.APIConnectionError:
        print("network error reaching the API", file=sys.stderr)
        return 2
    return 0

if __name__ == "__main__":
    sys.exit(main())

이 내용을 /opt/explain/explain.py로 저장한 뒤, 대화형 사용을 위해 키를 로드하는 래퍼를 추가하십시오:

sudo tee /usr/local/bin/explain >/dev/null <<'EOF'
#!/bin/sh
set -a; . /etc/claude-explain.env; set +a
exec /opt/explain/venv/bin/python /opt/explain/explain.py "$@"
EOF
sudo chmod 755 /usr/local/bin/explain

(래퍼는 sudo를 통해 실행하거나, 환경 파일에 관리자 계정이 속한 그룹 권한을 부여해야 합니다. 파일 권한을 644로 느슨하게 설정하기보다는 의도적으로 하나를 선택하십시오.)

스트리밍을 사용하는 이유. client.messages.stream은 전체 생성이 완료될 때까지 기다리지 않고 토큰이 도착하는 즉시 출력하며, 긴 출력물에 대한 HTTP 타임아웃 문제를 방지합니다. 실제로 SDK는 이러한 이유로 비스트리밍 호출 시 매우 큰 max_tokens 값을 거부합니다. text_stream는 답변 텍스트만 반환하며, Opus 5.5의 기본 사고 과정 표시 설정에서는 사고 텍스트가 스트리밍되지 않으므로 출력 결과가 깔끔하게 유지됩니다. 생성된 객체를 나중에 사용해야 한다면 with 블록 내부에서 stream.get_final_message()을 호출하십시오.

예외 처리 순서의 이유. SDK는 유형별 예외를 발생시키며, 가장 구체적인 것부터 처리합니다: RateLimitError는 429 오류이며 대기 시간을 알려주는 retry-after 헤더를 포함합니다. APIStatusError은 그 외의 2xx 이외 응답을 처리하며(서버 측 문제는 e.status_code >= 500을 확인하십시오), APIConnectionError는 요청에 대한 응답을 전혀 받지 못한 경우를 의미합니다. 재시도 루프를 구현하기 전에 알아둘 점은 SDK가 이미 429 및 5xx 오류에 대해 자체적으로 재시도를 수행한다는 것입니다. 기본적으로 지수 백오프(max_retries)를 사용하여 2회 재시도합니다. 따라서 except이 실행될 시점에는 이미 재시도가 소진된 상태이므로, CLI에서는 대기 후 다시 시도하는 대신 오류를 보고하고 종료하는 것이 올바른 대응입니다.

비용 관리

API에는 사용자가 설정하는 것 외에 내장된 월간 한도가 없으며, 여기서 발생하는 모든 실수는 조용히 누적되므로 별도의 섹션으로 다룹니다.

max_tokens는 호출당 지출 상한선입니다. Opus 5.5 모델에서 출력 토큰은 입력 가격의 5배로 비용이 발생하는 비싼 방향이며, max_tokens은 모델이 생성할 수 있는 토큰 수에 대한 엄격한 제한입니다. 제어되지 않는 프롬프트라도 허용된 출력량을 초과하여 비용이 발생하지 않습니다. 5.5 모델에서 이 제한은 사고(thinking) 과정에도 적용됩니다. 사고 토큰은 max_tokens에 포함되어 출력으로 청구되며, 사고 텍스트 자체가 사용자에게 반환되지 않더라도 마찬가지입니다. 작업 규모에 맞게 설정하십시오. 4,096은 간결한 로그 진단과 그 앞의 사고 과정을 위한 공간을 제공하며, 분류 작업에는 훨씬 적은 양이 필요합니다. 응답이 stop_reason: "max_tokens"로 인해 중간에 끊긴다면 너무 작게 설정한 것이므로, 무조건 크게 설정하기보다는 의식적으로 값을 높이거나 모델이 덜 생각하도록 노력(effort) 설정을 낮추십시오.

전송 전에 계산하십시오. 입력도 비용이 발생하며 로그는 부피가 큽니다. API에는 무료로 사용할 수 있는 카운팅 엔드포인트가 있습니다(메시지 생성과는 별도의 자체 속도 제한이 적용됩니다).

count = client.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": big_log_text}],
)
print(count.input_tokens)

이 기능을 사용하여 2 GB 로그를 실수로 도구에 전달하는 것을 방지하고, 실제로 호출할 모델을 전달하십시오. Claude 4.7 및 이후 모델은 이전 Claude 모델보다 동일한 텍스트에 대해 약 30% 더 많은 토큰을 생성하는 최신 토크나이저를 사용합니다. 이를 위해 tiktoken을 사용하지 마십시오. 이는 OpenAI의 토크나이저이며 Claude의 것이 아니므로, 계산 결과가 실제 청구 금액과 일치하지 않습니다.

충성도가 아닌 작업별로 모델을 선택하십시오. 2026년 10월 기준으로 Opus 5.5(claude-opus-5-5)는 입력 토큰 100만 개당 4달러, 출력 100만 개당 20달러입니다. Haiku 5.5(claude-haiku-5-5)는 10만 토큰 이하 프롬프트에 대해 100만 개당 0.10달러/0.50달러(그 이상은 0.50달러/2.50달러)이며 1M 컨텍스트를 지원합니다. Sonnet 5.5(claude-sonnet-5-5)는 그 사이인 2달러/10달러입니다. 구체적으로 2,000토큰의 로그 발췌문과 500토큰의 답변은 Opus에서 약 0.018달러, Haiku에서 약 0.00045달러의 비용이 발생하며, 여기에 모델이 수행하는 사고 비용(출력으로 청구됨)이 추가됩니다. 출력 품질을 판단하는 동안에는 Opus에서 시작한 다음, 동일한 프롬프트를 Haiku에서 시도해 보십시오. 대량의 단순 변환 작업의 경우 토큰당 가격이 40분의 1 수준임에도 결과물은 구분하기 어려운 경우가 많습니다. 예산에 고정하기 전에 가격 페이지에서 현재 수치를 확인하십시오.

대기 가능한 작업은 배치를 사용하십시오. Batches API는 표준 가격의 50%로 요청을 비동기 처리하며, 대부분의 배치는 1시간 이내에 완료됩니다. 야간 요약, 백필, 대량 분류 등 사람이 기다리지 않아도 되는 모든 작업은 여기에 해당합니다.

반복되는 컨텍스트에는 프롬프트 캐싱을 사용하십시오. 모든 호출에서 동일한 대형 시스템 프롬프트나 런북을 다시 보낸다면 캐시 가능으로 표시하십시오.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    system=[{
        "type": "text",
        "text": RUNBOOK_TEXT,  # the same 30K tokens on every call
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": question}],
)
print(response.usage.cache_read_input_tokens)  # non-zero from the second call on

캐시 쓰기는 5분 TTL 기준 입력 가격의 1.25배이며, 캐시 읽기는 Opus 5.5 및 Sonnet 5.5에서 0.05배(대부분의 다른 모델에서는 0.1배)이므로 해당 시간 내의 두 번째 호출부터는 첫 번째 호출 비용을 상쇄합니다. 두 가지 주의사항이 있습니다. 캐시된 접두사는 모델별 최소 단위(Opus 5.5 기준 512토큰)를 넘어야 하므로, 매우 짧은 시스템 프롬프트는 캐시되지 않습니다. 또한 동일한 호출을 반복해도 cache_read_input_tokens이 0으로 유지된다면, 요청마다 접두사 내의 무언가가 변경되고 있는 것입니다(보통 타임스탬프가 원인입니다).

입력으로 간주되는 항목을 기억하십시오. 시스템 프롬프트, 도구 정의, 그리고 다중 턴 대화에서 매 턴마다 다시 보내는 전체 기록은 모두 입력 토큰으로 청구됩니다. 기록을 정리하지 않는 대화 루프는 비용이 이차 함수적으로 증가합니다. 대화형 서비스를 구축하기 전에 전체 계산 방식을 이해하는 것이 좋습니다: Claude 토큰 사용량과 청구 금액이 실제로 합산되는 방식.

systemd에서 실행하기

환경 변수 파일 관리 원칙을 지키면 얻는 이점은 분명합니다. 매일 아침 어제의 오류를 요약해서 알려주는 타이머를 설정할 수 있습니다.

# /etc/systemd/system/log-digest.service
[Unit]
Description=Daily error-log digest via the Claude API

[Service]
Type=oneshot
User=explain
Group=systemd-journal
EnvironmentFile=/etc/claude-explain.env
ExecStart=/bin/sh -c 'journalctl -p err --since yesterday | /opt/explain/venv/bin/python /opt/explain/explain.py >> /var/log/log-digest.txt'
# /etc/systemd/system/log-digest.timer
[Unit]
Description=Run the log digest every morning

[Timer]
OnCalendar=06:15
Persistent=true

[Install]
WantedBy=timers.target
sudo useradd -r -s /usr/sbin/nologin explain
sudo touch /var/log/log-digest.txt && sudo chown explain /var/log/log-digest.txt
sudo systemctl daemon-reload
sudo systemctl enable --now log-digest.timer
sudo systemctl start log-digest.service   # test it once, right now

EnvironmentFile= 설정이 주는 이점을 확인하십시오. systemd는 권한이 없는 explain 사용자로 전환하기 전에 root 소유의 600 모드 파일을 읽습니다. 따라서 프로세스는 변수를 전달받지만, 사용자는 키 파일을 직접 읽을 수 없습니다. systemd-journal 그룹은 로그 접근 권한을 부여합니다. systemctl start 명령을 수동으로 실행하여 journalctl -u log-digest.service 내용을 확인하십시오. 오타를 찾기 위해 06:15까지 기다릴 필요는 없습니다. 이 패턴이 셸 파이프라인으로 감당하기 어려울 정도로 커지면, 동일한 환경 변수 파일 기반의 키 관리 방식을 같은 서버의 Claude 기반 n8n 워크플로에 그대로 적용할 수 있습니다.

실패 유형 및 확인 가능한 메시지

정상적인 키를 사용해도 발생하는 401 오류. 예외 메시지는 다음과 같습니다.

anthropic.AuthenticationError: Error code: 401 - {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}, 'request_id': 'req_011CSHoEeqs5C35K2UUqR7Fy'}

키가 셸에서는 정상 작동하지만 서비스에서 401 오류가 발생한다면, 서비스가 키를 전달받지 못한 것입니다. systemd는 .bashrc을 읽지 않는다는 점을 기억하십시오. EnvironmentFile=가 올바른 경로를 가리키고 있는지 확인하십시오. 그 외 원인으로는 환경 변수 파일에 포함된 따옴표(ANTHROPIC_API_KEY="sk-ant-...", systemd는 따옴표를 제거하지만 셸 래퍼의 . file는 따옴표를 값에 포함할 수 있음), 공백 문자, 지난주 콘솔에서 취소한 키, 또는 생성 시 설정한 만료 기한이 지난 키 등이 있습니다.

모델 오타로 인한 404 오류. 가장 흔한 사례는 날짜가 포함되지 않은 모델 ID에 날짜 접미사를 붙이는 경우입니다.

anthropic.NotFoundError: Error code: 404 - {'type': 'error', 'error': {'type': 'not_found_error', 'message': 'model: claude-opus-5-5-20260922'}, 'request_id': 'req_011CSJqymAvNw4bT3qmDdMbA'}

현재 세대 모델 ID는 claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, claude-fable-5-1와 같이 표기된 그대로 사용해야 합니다. 4.6 세대 이전 모델은 예외입니다. claude-haiku-4-5는 날짜가 포함된 ID인 claude-haiku-4-5-20251001의 편의 별칭이며, 두 형식 모두 작동합니다. 모델 ID는 기억에 의존하거나 오래된 튜토리얼을 참고하지 말고, 반드시 모델 문서에서 복사하십시오.

429 rate_limit_error. 오류 유형 문자열은 rate_limit_error이며, 응답 헤더의 retry-after에 대기해야 할 초 단위 시간이 포함됩니다. SDK는 예외가 발생하기 전에 이미 두 번의 재시도와 백오프를 수행했습니다. 따라서 429 오류가 지속된다면 현재 사용 중인 티어의 처리량을 초과한 것이므로, 재시도 루프를 강화하지 말고 작업을 배치(batch) 처리하거나 분산하십시오.

텍스트가 아닌 객체가 출력됨. 출력 결과가 [TextBlock(citations=None, text='...', type='text')]과 같이 나타납니다. 이는 블록을 순회하며 block.type == "text"인 블록에서 .text를 읽어오는 대신 response.content를 출력했기 때문입니다. 위의 모든 SDK 예제는 올바르게 작성되어 있으므로 해당 루프를 복사하십시오.

error: externally-managed-environment. Ubuntu 24.04의 시스템 Python에 대해 pip install을 실행한 경우입니다. 반드시 venv를 사용하십시오. 운영 중인 서버에서 --break-system-packages를 사용하는 것은 절대 금물입니다.

답변이 잘림. response.stop_reason == "max_tokens"은 모델이 답변 도중 출력 제한에 도달했음을 의미합니다. 이는 설계된 대로 작동하는 것이며, 제한을 의도적으로 높이십시오. 5.5 모델의 경우 '생각(thinking)' 과정도 동일한 제한을 소모한다는 점을 유의하십시오.

첫 번째 애플리케이션이 정상 작동하면, Claude를 활용한 AI 에이전트 구축을 통해 동일한 API 호출을 도구를 사용하는 에이전트로 확장할 수 있습니다.

FAQ

Claude API를 테스트하는 데 비용이 얼마나 드나요?

이 정도 도구라면 비용은 매우 적습니다. 2026년 10월 기준으로 Opus 5.5는 입력 토큰 100만 개당 4달러, 출력 토큰 100만 개당 20달러입니다. 따라서 일반적인 로그 진단(입력 수천 토큰, 출력 수백 토큰)은 사고 토큰(출력으로 과금됨)을 제외하면 2센트 정도이며, Haiku 5.5($0.10/$0.50)를 사용하면 0.1센트 미만입니다. 매일 요약을 받아보더라도 한 달 커피 한 잔 값보다 저렴합니다. 위험 요소는 호출당 가격이 아니라 무한 루프와 무제한 max_tokens이므로, 이 가이드에서는 두 가지 모두 명시적으로 설정합니다.

Claude API에 무료 티어가 있나요?

2026년 10월 기준으로 상시 무료 티어는 없습니다. Anthropic의 가격 정책 문서에 따르면 신규 사용자는 API 테스트를 위한 소액의 무료 크레딧을 1회 제공받습니다. 정확한 금액은 가입 시 콘솔에서 확인할 수 있으며, 이후에는 계정을 충전해야 합니다. Max 및 Team 구독자는 예외이며, 해당 플랜에는 위에서 언급한 월간 API 크레딧이 포함되어 있습니다. 요청당 한계 비용이 0인 것을 목표로 한다면, 최상위 성능 대신 Ollama를 사용하여 오픈 웨이트 모델을 직접 호스팅하고 토큰 대신 RAM 비용을 지불하는 대안이 있습니다.

서버에서 API 키를 안전하게 유지하려면 어떻게 해야 하나요?

코드에 포함하거나, git에 올리거나, .bashrc에서 export하거나, 기록이 남는 셸에 직접 입력해서는 안 됩니다. root 소유의 파일에 600 권한으로 저장하고, 프로세스별로 로드하십시오. 대화형 사용 시에는 래퍼 스크립트를 사용하고, systemd에는 EnvironmentFile=를 사용하십시오. 서버나 프로젝트당 하나의 키를 할당하여 키가 유출되었을 때 전체가 아닌 해당 부분만 폐기할 수 있도록 관리하십시오. 키가 페이스트 사이트나 git 커밋에 노출되었다면 즉시 콘솔에서 폐기하십시오. 커밋을 삭제하는 것만으로는 유출을 막을 수 없습니다.

어떤 Claude 모델로 시작해야 하나요?

출력 결과가 개발하기에 충분한지 평가하고, 아이디어를 최고 품질로 검증하고 싶다면 claude-opus-5-5로 시작하십시오. 취미 수준의 사용량이라면 비용 차이는 몇 센트에 불과합니다. 프롬프트가 확정되면 실제 입력값으로 claude-haiku-5-5에서 다시 실행해 보십시오. 요약, 분류, 로그 분류 작업의 경우 토큰당 가격이 40분의 1 수준인 이 모델로도 충분한 경우가 많습니다. Haiku나 Sonnet으로의 전환은 기본값이 아니라 측정 결과에 따라 결정하십시오.

#claude-api#python#ai#vps#anthropic