DEV Community

Cover image for 클로드 페이블 5 API 활용법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

클로드 페이블 5 API 활용법

Anthropic은 2026년 6월 9일 Claude Fable 5를 출시했습니다. Claude Fable 5 API는 기존 Messages API와 같은 방식으로 호출하며, 대부분의 통합에서는 모델 문자열만 claude-fable-5로 바꾸면 됩니다. 이 글에서는 curl 요청, Python/TypeScript SDK, 스트리밍, 도구 사용, 오류 처리, 비용 계산, Apidog를 활용한 테스트 흐름까지 실제 구현에 필요한 단계만 정리합니다. 이전 Claude 모델에서 마이그레이션한다면 Claude Opus 4.8 API와 마찬가지로 요청 구조는 거의 그대로 유지됩니다.

오늘 Apidog를 사용해 보세요

요약

  1. Anthropic 콘솔에서 API 키를 생성합니다.
  2. 키를 ANTHROPIC_API_KEY 환경 변수로 설정합니다.
  3. POST https://api.anthropic.com/v1/messages로 요청을 보냅니다.
  4. 요청 본문에는 최소한 model, max_tokens, messages를 포함합니다.
  5. 모델 값은 "claude-fable-5"를 사용합니다.
  6. 긴 응답은 스트리밍으로 처리합니다.
  7. 비용은 usage.input_tokens, usage.output_tokens로 계산합니다.

가격은 입력 토큰 100만 개당 $10, 출력 토큰 100만 개당 $50입니다.

시작하기 전에 준비할 것

첫 요청을 보내기 전에 다음 항목을 준비하세요.

  1. Anthropic 계정

    console.anthropic.com에서 가입합니다. 콘솔에서 API 키, 사용량, 청구 정보를 관리합니다.

  2. API 키

    콘솔의 API 키 섹션에서 키를 생성합니다. 키는 한 번만 표시되므로 안전하게 보관하세요.

  3. 결제 또는 Enterprise 플랜

    Fable 5는 표준 Claude API 및 사용량 기반 Enterprise 플랜에서 사용할 수 있습니다. 트래픽을 보내기 전에 결제 수단 또는 플랜 포함 여부를 확인하세요. 모델 특성을 먼저 확인하려면 Claude Fable 5란 무엇인가를 참고할 수 있습니다.

  4. SDK 또는 HTTP 클라이언트

    Python/TypeScript 공식 SDK를 사용하거나 curl, Postman, Apidog 같은 HTTP 클라이언트로 직접 호출할 수 있습니다.

API 키는 코드에 직접 넣지 말고 환경 변수로 설정하세요.

export ANTHROPIC_API_KEY="sk-ant-..."
Enter fullscreen mode Exit fullscreen mode

Python 및 TypeScript SDK는 기본적으로 환경 변수 ANTHROPIC_API_KEY를 읽습니다. 키를 Git에 커밋하지 말고, 유출되면 즉시 콘솔에서 폐기 후 재발급하세요.

Fable 5에는 일부 민감한 쿼리, 예를 들어 사이버 보안, 생물학 및 화학, 모델 증류 시도와 관련된 요청을 Claude Opus 4.8로 라우팅하는 안전장치가 포함되어 있습니다. 이는 세션의 5% 미만에서 발생합니다. 별도 설정은 필요 없지만, 응답 객체의 model 값이 요청한 claude-fable-5와 다를 수 있다는 점은 로깅과 테스트에서 고려해야 합니다.

첫 Claude Fable 5 API 호출

가장 먼저 curl로 원시 요청을 보내보면 API 계약을 빠르게 이해할 수 있습니다.

엔드포인트는 Anthropic Messages API 참조에 문서화된 다음 URL입니다.

POST https://api.anthropic.com/v1/messages
Enter fullscreen mode Exit fullscreen mode

최소 요청은 다음과 같습니다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Summarize what makes a good REST API in 3 bullet points."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

필수 헤더는 다음과 같습니다.

헤더 설명
x-api-key Anthropic API 키
anthropic-version API 버전. 예: 2023-06-01
content-type JSON 요청이므로 application/json

본문의 핵심 필드는 다음 세 가지입니다.

{
  "model": "claude-fable-5",
  "max_tokens": 1024,
  "messages": []
}
Enter fullscreen mode Exit fullscreen mode

예상 응답 구조는 다음과 같습니다.

{
  "id": "msg_01ABC...",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [
    {
      "type": "text",
      "text": "- 예측 가능하고 리소스 중심적인 URL..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 96
  }
}
Enter fullscreen mode Exit fullscreen mode

구현 시 주의할 점은 content가 문자열이 아니라 블록 배열이라는 것입니다. 텍스트, 도구 호출, 기타 블록이 섞일 수 있으므로 항상 type을 확인한 뒤 처리하세요.

for block in response.content:
    if block.type == "text":
        print(block.text)
Enter fullscreen mode Exit fullscreen mode

stop_reason은 모델이 응답을 멈춘 이유를 나타냅니다. 일반적으로 end_turn이면 정상 종료입니다. usage는 비용 계산에 사용합니다.

Python에서 Fable 5 호출하기

먼저 공식 SDK를 설치합니다.

pip install anthropic
Enter fullscreen mode Exit fullscreen mode

기본 호출 코드는 다음과 같습니다.

import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY를 환경 변수에서 읽습니다

response = client.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "좋은 REST API를 만드는 요소를 3가지로 요약하세요."
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
Enter fullscreen mode Exit fullscreen mode

이 코드에서 직접 관리해야 하는 값은 대부분 세 가지입니다.

model="claude-fable-5"
max_tokens=1024
messages=[...]
Enter fullscreen mode Exit fullscreen mode

content는 항상 블록 배열로 처리하세요. 단순히 response.content[0].text에 의존하면 도구 호출이나 비텍스트 블록이 포함될 때 깨질 수 있습니다.

시스템 프롬프트 추가하기

시스템 프롬프트는 모델의 역할, 응답 스타일, 출력 형식 규칙을 지정할 때 사용합니다. messages 안에 넣지 않고 system 필드로 전달합니다.

response = client.messages.create(
    model="claude-fable-5",
    max_tokens=2048,
    system="당신은 선임 백엔드 엔지니어입니다. 간결하게 설명하고 코드 예시를 사용하세요.",
    messages=[
        {
            "role": "user",
            "content": "JSON 본문을 검증하는 Flask 라우트를 작성하세요."
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
Enter fullscreen mode Exit fullscreen mode

시스템 프롬프트에는 다음과 같은 규칙을 넣기 좋습니다.

  • 응답 언어
  • 역할 또는 전문성
  • 코드 스타일
  • 출력 형식
  • 금지할 동작
  • 항상 지켜야 하는 제약 조건

프롬프트 캐싱을 사용할 계획이라면 시스템 프롬프트를 자주 변경하지 않는 것이 좋습니다. 매 요청마다 달라지면 캐싱 효과가 줄어듭니다.

긴 출력은 스트리밍으로 처리하기

응답이 길어질 수 있는 요청은 스트리밍을 기본값으로 두는 것이 좋습니다. 스트리밍을 사용하면 토큰이 생성되는 즉시 받을 수 있고, 긴 비스트리밍 응답에서 발생할 수 있는 타임아웃을 줄일 수 있습니다.

with client.messages.stream(
    model="claude-fable-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "결제 API의 멱등성 키에 대해 설명하세요."
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()

print(f"\n\n토큰: {final.usage.output_tokens}")
Enter fullscreen mode Exit fullscreen mode

핵심은 두 가지입니다.

  1. stream.text_stream으로 도착하는 텍스트 청크를 즉시 처리합니다.
  2. 스트림 완료 후 stream.get_final_message()로 최종 메시지와 usage를 가져옵니다.

프런트엔드 채팅 UI를 만든다면 서버에서 Claude 스트림을 받아 브라우저로 다시 스트리밍하는 구조를 사용하면 됩니다.

TypeScript / Node에서 Fable 5 호출하기

Node SDK를 설치합니다.

npm install @anthropic-ai/sdk
Enter fullscreen mode Exit fullscreen mode

기본 호출은 다음과 같습니다.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // ANTHROPIC_API_KEY를 환경 변수에서 읽습니다

const msg = await client.messages.create({
  model: "claude-fable-5",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "일반적인 API 보안 실수 3가지를 나열하세요.",
    },
  ],
});

console.log(msg.content);
Enter fullscreen mode Exit fullscreen mode

msg.content도 Python과 동일하게 블록 배열입니다. 텍스트만 추출하려면 type으로 필터링하세요.

const text = msg.content
  .filter((block) => block.type === "text")
  .map((block) => block.text)
  .join("");

console.log(text);
Enter fullscreen mode Exit fullscreen mode

스트리밍도 같은 패턴입니다. client.messages.stream({...})을 사용하고 이벤트를 순회하거나 최종 메시지를 기다려 조립된 결과를 얻습니다.

API 요청을 앱에 붙이기 전에 요청/응답 계약을 먼저 검증하면 디버깅 시간이 줄어듭니다. Apidog를 사용하면 클라이언트 코드를 작성하기 전에 실제 응답 구조를 확인할 수 있습니다. 이 흐름은 Apidog로 ChatGPT API 테스트하기에서 다룬 방식과 동일합니다.

Fable 5의 도구 사용, 즉 함수 호출 구현하기

도구 사용은 모델이 직접 답을 생성하는 대신, 개발자가 정의한 함수를 호출하도록 만드는 기능입니다. 일반적인 흐름은 다음과 같습니다.

  1. 도구 이름, 설명, 입력 스키마를 정의합니다.
  2. 요청에 tools를 포함합니다.
  3. 모델이 tool_use 블록을 반환하면 실제 함수를 실행합니다.
  4. 결과를 tool_result로 다시 모델에 전달합니다.
  5. 모델이 최종 답변을 생성합니다.

먼저 도구를 정의합니다.

tools = [
    {
        "name": "get_order_status",
        "description": "ID로 고객 주문의 상태를 조회합니다.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string"
                }
            },
            "required": ["order_id"],
        },
    }
]
Enter fullscreen mode Exit fullscreen mode

요청에 tools를 포함합니다.

messages = [
    {
        "role": "user",
        "content": "주문 A1855의 상태는 무엇인가요?"
    }
]

response = client.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)
Enter fullscreen mode Exit fullscreen mode

모델이 도구를 호출하려 하면 stop_reason이 tool_use가 되고, content 안에 tool_use 블록이 포함됩니다.

if response.stop_reason == "tool_use":
    tool_use = next(
        block for block in response.content
        if block.type == "tool_use"
    )

    result = lookup_order(tool_use.input["order_id"])  # 사용자 코드

    messages.append({
        "role": "assistant",
        "content": response.content
    })

    messages.append({
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": tool_use.id,
                "content": result,
            }
        ],
    })

    followup = client.messages.create(
        model="claude-fable-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
Enter fullscreen mode Exit fullscreen mode

가장 중요한 값은 tool_use_id입니다. tool_result의 tool_use_id는 이전 tool_use 블록의 id와 정확히 일치해야 합니다.

다단계 에이전트를 만들 때는 이 로직을 루프로 감싸면 됩니다.

while True:
    response = client.messages.create(
        model="claude-fable-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )

    if response.stop_reason != "tool_use":
        break

    tool_use = next(
        block for block in response.content
        if block.type == "tool_use"
    )

    result = lookup_order(tool_use.input["order_id"])

    messages.append({
        "role": "assistant",
        "content": response.content
    })

    messages.append({
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": tool_use.id,
                "content": result,
            }
        ],
    })
Enter fullscreen mode Exit fullscreen mode

운영 환경에서는 도구 실행 전후에 다음을 추가하는 것이 좋습니다.

  • 입력 검증
  • 허용된 도구 목록 확인
  • 승인 게이트
  • 실행 로그
  • 타임아웃
  • 재시도 정책

적응적 사고 및 노력 설정

Fable 5는 적응적 사고를 지원합니다. 이는 모델이 답변 전 얼마나 깊게 추론할지 결정하도록 하는 기능입니다. 필요한 경우 thinking과 output_config를 전달합니다.

response = client.messages.create(
    model="claude-fable-5",
    max_tokens=4096,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # low | medium | high
    messages=[
        {
            "role": "user",
            "content": "불안정한 웹훅 수신기에 대한 재시도 전략을 설계하세요."
        }
    ],
)
Enter fullscreen mode Exit fullscreen mode

effort는 모델이 얼마나 많은 작업을 수행할지 조정합니다.

값 사용 시점
low 짧은 답변, 단순 요약, 빠른 응답
medium 일반적인 설계 및 구현 설명
high 복잡한 계획, 다단계 추론, 아키텍처 검토

단순 조회나 짧은 답변에는 굳이 켜지 않는 것이 좋습니다. 추가 추론은 더 많은 토큰을 사용할 수 있으므로, 실제로 필요한 경로에만 적용하세요.

오류 처리 구현하기

실제 애플리케이션에서는 API 실패를 명확하게 처리해야 합니다. Python SDK는 유형화된 예외를 제공하므로 문자열 매칭 대신 예외 클래스를 catch하세요.

import anthropic

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-fable-5",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "CORS 프리플라이트 요청에 대해 설명하세요."
            }
        ],
    )

except anthropic.AuthenticationError:
    # 401: API 키 누락, 잘못된 키, 취소된 키
    print("잘못된 API 키입니다. 콘솔에서 키를 확인하고 다시 설정하세요.")

except anthropic.RateLimitError as e:
    # 429: 요청 수 또는 토큰 제한 초과
    retry_after = e.response.headers.get("retry-after", "60")
    print(f"속도 제한에 걸렸습니다. {retry_after}초 후 다시 시도하세요.")

except anthropic.BadRequestError as e:
    # 400: 요청 형식 오류
    print(f"잘못된 요청: {e.message}")
Enter fullscreen mode Exit fullscreen mode

자주 발생하는 오류는 다음과 같습니다.

상태 코드 SDK 예외 원인 처리
401 AuthenticationError 키 누락, 잘못된 키, 취소된 키 환경 변수와 콘솔 상태 확인
429 RateLimitError 요청 수 또는 토큰 제한 초과 retry-after 확인 후 백오프
400 BadRequestError 잘못된 요청 형식 messages, max_tokens, 역할 순서 확인

SDK는 기본적으로 429 및 5xx 오류에 대해 지수 백오프를 적용해 재시도합니다. 별도 재시도 로직을 구현한다면 retry-after 헤더를 우선적으로 확인하세요.

안전장치 대체 응답 처리하기

Fable 5는 민감한 쿼리의 작은 부분을 Claude Opus 4.8로 라우팅할 수 있습니다. 이는 오류가 아닙니다. 요청은 성공하지만 응답 객체의 model 값이 다를 수 있습니다.

따라서 다음처럼 요청한 모델명을 기준으로만 검증하지 마세요.

# 권장하지 않음
assert response.model == "claude-fable-5"
Enter fullscreen mode Exit fullscreen mode

대신 응답 객체에서 실제 처리 모델을 읽어 로깅하세요.

print(f"requested_model=claude-fable-5 actual_model={response.model}")
Enter fullscreen mode Exit fullscreen mode

모니터링이나 분석에서 어떤 모델이 응답했는지 중요하다면, 요청 시 사용한 모델명과 응답의 response.model을 둘 다 저장하세요.

요청당 비용 계산하기

Fable 5 가격은 다음과 같습니다.

항목 가격
입력 토큰 100만 개당 $10
출력 토큰 100만 개당 $50

모든 응답에는 usage가 포함되므로 요청별 비용을 계산할 수 있습니다.

response = client.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "중복 이메일을 찾는 SQL 쿼리를 작성하세요."
        }
    ],
)

input_tokens = response.usage.input_tokens
output_tokens = response.usage.output_tokens

input_cost = input_tokens / 1_000_000 * 10
output_cost = output_tokens / 1_000_000 * 50
total = input_cost + output_cost

print(f"입력:  {input_tokens} 토큰 = ${input_cost:.6f}")
print(f"출력: {output_tokens} 토큰 = ${output_cost:.6f}")
print(f"총계: ${total:.6f}")
Enter fullscreen mode Exit fullscreen mode

예를 들어 입력 2,000 토큰, 출력 500 토큰이면 다음과 같습니다.

입력 비용 = 2000 / 1,000,000 * $10 = $0.020
출력 비용 = 500 / 1,000,000 * $50 = $0.025
총 비용 = $0.045
Enter fullscreen mode Exit fullscreen mode

출력 토큰은 입력 토큰보다 5배 비싸므로 비용을 줄이려면 다음을 우선 적용하세요.

  • max_tokens 제한
  • 시스템 프롬프트에서 간결한 답변 요구
  • 불필요한 장문 출력 방지
  • 스트리밍으로 UX 개선
  • 긴 컨텍스트 재사용 시 캐싱 고려

출력 중심 비용 계산 방식은 Claude Opus 4.8 가격에 적용하는 계산과 동일하며, Fable 5의 단가만 다릅니다.

Apidog로 Claude Fable 5 API 테스트 및 디버그하기

클라이언트 코드를 작성하기 전에 실제 요청을 직접 보내보면 구현 오류를 빠르게 줄일 수 있습니다. Apidog는 HTTP 요청을 만들고, 응답을 검사하고, 팀과 API 요청 정의를 공유할 수 있는 API 클라이언트입니다.

Claude Fable 5 요청을 Apidog에서 테스트하는 흐름은 다음과 같습니다.

1. 새 HTTP 요청 만들기

Apidog에서 새 HTTP 요청을 만들고 메서드를 POST로 설정합니다.

https://api.anthropic.com/v1/messages
Enter fullscreen mode Exit fullscreen mode

2. API 키를 환경 변수로 저장하기

환경 변수에 다음과 같은 이름으로 키를 저장합니다.

anthropic_api_key
Enter fullscreen mode Exit fullscreen mode

키를 비밀 값으로 저장하면 요청 공유나 내보내기 과정에서 원본 키가 노출되는 것을 줄일 수 있습니다.

3. 헤더 설정하기

다음 헤더를 추가합니다.

x-api-key: {{anthropic_api_key}}
anthropic-version: 2023-06-01
content-type: application/json
Enter fullscreen mode Exit fullscreen mode

4. JSON 본문 추가하기

최소 본문은 다음과 같습니다.

{
  "model": "claude-fable-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "결제 API의 멱등성 키에 대해 설명하세요."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

요청을 보내면 응답 패널에서 다음 값을 바로 확인할 수 있습니다.

  • content
  • stop_reason
  • usage.input_tokens
  • usage.output_tokens
  • model

5. 스트리밍 응답 확인하기

스트리밍을 테스트하려면 본문에 다음 필드를 추가합니다.

{
  "stream": true
}
Enter fullscreen mode Exit fullscreen mode

Apidog에서 서버 전송 이벤트가 도착하는 과정을 확인하면, 앱에서 스트리밍 UI를 구현하기 전에 실제 이벤트 흐름을 검증할 수 있습니다.

6. 요청 저장 및 코드 생성하기

작동하는 요청을 컬렉션에 저장하면 팀원이 같은 정의를 재사용할 수 있습니다. 또한 Apidog의 코드 생성 기능으로 Python, JavaScript, curl 등 여러 언어의 스니펫을 만들 수 있습니다.

이 방식의 장점은 앱 코드의 요청과 Apidog에서 검증한 정상 요청을 나란히 비교할 수 있다는 점입니다. 헤더 누락, JSON 구조 오류, 모델명 오타, 스트리밍 설정 문제를 빠르게 찾을 수 있습니다.

설정할 준비가 되었다면 Apidog를 다운로드하고 위의 최소 요청부터 저장해 보세요.

Top comments (0)