Anthropic은 2026년 6월 9일 Claude Fable 5를 출시했으며, 코드를 작성하며 생계를 꾸려가는 개발자라면 Claude Fable 5 API에 관심을 가질 것입니다. 이 API는 이미 익숙한 Messages API와 동일하게 작동하므로, 실제로 변경되는 유일한 부분은 모델 문자열인 claude-fable-5입니다. 이 가이드에서는 한 줄짜리 curl 요청부터 스트리밍, 도구 사용, 오류 처리 및 비용 계산에 이르기까지, 실제 응답을 받아 작동하는 코드를 얻는 데 필요한 모든 호출을 안내합니다. 이전에 Claude를 사용하여 배포한 경험이 있다면 친숙하게 느껴질 것입니다. 이전 모델에서 마이그레이션하는 경우, Claude Opus 4.8 API의 경우와 마찬가지로 대부분 문자열만 변경하면 됩니다.
요약
Anthropic 콘솔에서 API 키를 발급받아 ANTHROPIC_API_KEY로 설정한 다음, model: "claude-fable-5", max_tokens 값, messages 배열을 포함하여 Messages API로 POST 요청을 보내세요. 공식 Anthropic SDK(Python 또는 TypeScript)를 사용하거나 원시 HTTP 요청을 사용할 수 있습니다. 요청 시간 초과를 피하려면 긴 출력은 스트리밍하세요. 가격은 입력 토큰 100만 개당 $10, 출력 토큰 100만 개당 $50입니다.
시작하기 전에
첫 요청을 보내기 전에 네 가지가 준비되어 있어야 합니다.
- Anthropic 계정. console.anthropic.com에서 가입하세요. 콘솔은 키, 사용량, 청구를 관리하는 곳입니다.
- API 키. 콘솔의 API 키 섹션에서 생성하세요. 한 번 복사하면 다시 볼 수 없으니 비밀번호처럼 다루세요.
- 결제 또는 Enterprise 플랜. Fable 5는 표준 Claude API에서 사용할 수 있으며, 사용량 기반 Enterprise 플랜에서도 완벽하게 이용 가능합니다. 트래픽을 보내기 전에 결제 수단을 추가하거나 플랜에 포함되어 있는지 확인하세요. Fable 5가 귀하의 사용 사례에 적합한지 아직 결정 중이라면, Claude Fable 5란 무엇인가 개요에서 모델의 강점을 명확하게 설명합니다.
- SDK (선택 사항이지만 권장). 사용하는 언어에 맞는 공식 Anthropic SDK를 설치하세요. 원한다면 curl 또는 다른 HTTP 클라이언트를 사용하여 원시 HTTP 엔드포인트를 호출할 수도 있습니다.
키가 소스 코드에 절대 포함되지 않도록 환경 변수로 설정하세요.
export ANTHROPIC_API_KEY="sk-ant-..."
두 SDK 모두 환경에서 ANTHROPIC_API_KEY를 자동으로 읽으므로 코드에 직접 전달할 필요는 거의 없습니다. 키를 Git에 올리지 마세요. 키가 유출되면 즉시 콘솔에서 교체하세요.
미리 알아야 할 한 가지 동작이 있습니다. Fable 5는 민감한 쿼리(사이버 보안, 생물학 및 화학, 모델 증류 시도)의 작은 부분을 직접 답변하는 대신 Claude Opus 4.8로 라우팅하는 안전장치를 포함하고 있습니다. 이는 세션의 5% 미만에서 발생합니다. 별도로 구성할 필요는 없지만, 때때로 다른 모델로 레이블이 지정된 응답이 돌아오는 이유를 설명합니다. 이에 대한 자세한 내용은 오류 처리 섹션에서 다룹니다.
첫 Claude Fable 5 API 호출
방해 없이 원시 요청과 응답을 볼 수 있도록 curl로 시작하세요. 엔드포인트는 Anthropic Messages API 참조에 문서화된 POST https://api.anthropic.com/v1/messages이며, 세 개의 헤더와 JSON 본문이 필요합니다.
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."}]}'
여기서 세 가지 헤더가 중요합니다. x-api-key는 귀하의 키를 전달합니다. anthropic-version은 API 버전을 고정합니다(2023-06-01은 현재 안정적인 값입니다). content-type은 서버에 JSON을 보내고 있음을 알립니다. 본문에는 model, max_tokens, messages의 세 가지 필수 필드가 있습니다. 이것이 전체 계약입니다.
응답은 JSON 객체로 돌아옵니다. 여기서 중요한 부분은 블록 목록인 content입니다.
{
"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 }
}
content는 문자열이 아니라 목록입니다. 단일 응답에 텍스트, 도구 사용 블록, 사고 블록이 혼합될 수 있기 때문입니다. text를 읽기 전에 항상 목록을 반복하고 각 블록의 type을 확인하세요. stop_reason은 모델이 멈춘 이유를 알려주며(end_turn은 깔끔한 종료를 의미), usage는 나중에 비용 계산에 사용할 토큰 수를 제공합니다.
Python에서 Fable 5 호출하기
공식 Anthropic Python SDK는 헤더 및 JSON 상용구 코드를 제거합니다. 먼저 설치하세요.
pip install anthropic
다음은 기본적인 호출입니다. 클라이언트는 환경에서 키를 읽으므로 직접 전달할 필요가 없습니다.
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를 만드는 요약을 하세요."}],
)
for block in response.content:
if block.type == "text":
print(block.text)
이 패턴은 curl 호출과 유사합니다. model, max_tokens, messages를 전달하면 content가 블록 목록인 응답을 받습니다. 루프는 block.type == "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)
시스템 프롬프트는 페르소나, 출력 형식 규칙, 모든 턴에 걸쳐 유지하고자 하는 제약 조건을 설정하기에 적절한 곳입니다. 나중에 프롬프트 캐싱을 추가할 경우 매 요청마다 변경하면 캐싱이 무효화되므로 안정적으로 유지하세요.
긴 출력 스트리밍
긴 답변을 생성하는 모든 것에 대해 스트리밍하세요. 스트리밍은 토큰이 생성되는 즉시 전송하므로 진행 상황을 즉시 표시하고, 대규모 비스트리밍 응답에서 발생하는 요청 시간 초과를 방지할 수 있습니다. Fable 5의 장기적인 작업 능력은 실제 워크로드에서 스트리밍을 기본 선택으로 만듭니다.
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}")
stream.text_stream은 도착하는 대로 텍스트 청크를 생성합니다. flush=True는 각 청크가 버퍼링되지 않고 즉시 출력되도록 하는 데 중요합니다. 스트림이 완료되면 stream.get_final_message()는 최종 usage 숫자를 포함하여 완전히 조립된 메시지를 제공하므로, 스트리밍된 사용자 경험과 완전한 객체를 두 번째 요청 없이 얻을 수 있습니다.
TypeScript / Node에서 Fable 5 호출하기
Node SDK도 동일한 형태를 따릅니다. 설치하세요.
npm install @anthropic-ai/sdk
그런 다음 호출하세요. 클라이언트는 Python과 마찬가지로 환경에서 ANTHROPIC_API_KEY를 읽습니다.
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);
msg.content는 Python 및 curl에서 본 것과 동일한 블록 목록입니다. 텍스트만 추출하려면 블록 유형으로 필터링하세요.
const text = msg.content
.filter((block) => block.type === "text")
.map((block) => block.text)
.join("");
console.log(text);
스트리밍은 Python과 동일하게 작동합니다. client.messages.stream({...})을 사용하고 이벤트를 반복하거나, finalMessage()를 기다려 조합된 결과를 얻으세요. 이를 프런트엔드 채팅에 연결하는 경우, 서버 경로에서 스트리밍하고 청크를 브라우저로 전달하세요. Node 또는 Python으로 구축하든 동일한 테스트 습관이 적용되며, Apidog와 같은 도구를 사용하면 클라이언트 코드를 작성하기 전에 계약을 쉽게 확인할 수 있습니다. 이는 Apidog로 ChatGPT API 테스트하기에서 다룬 워크플로와 동일합니다.
Fable 5의 도구 사용 (함수 호출)
도구 사용을 통해 Fable 5는 사용자가 정의한 함수를 호출할 수 있습니다. JSON 스키마로 도구를 설명하면 모델이 언제 호출할지 결정하고, 실제 함수를 실행하여 결과를 다시 피드백합니다. Fable 5는 도구 사용에 강력하며, 이 때문에 에이전트 루프에 잘 맞습니다.
이름, 설명, input_schema를 사용하여 도구를 정의합니다.
tools = [
{
"name": "get_order_status",
"description": "ID로 고객 주문의 상태를 조회합니다.",
"input_schema": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
}
]
messages를 전달하는 것과 동일한 방식으로 tools를 요청에 전달합니다.
messages = [{"role": "user", "content": "주문 A1855의 상태는 무엇인가요?"}]
response = client.messages.create(
model="claude-fable-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
모델이 도구를 사용하려 할 때, 응답은 stop_reason == "tool_use"와 함께 도구 이름과 선택된 입력을 포함하는 tool_use 블록을 반환합니다. 루프는 간단합니다. 어시스턴트의 응답을 추가하고, 도구를 실행한 다음, 새로운 사용자 턴에서 tool_result 블록으로 결과를 다시 보냅니다.
if response.stop_reason == "tool_use":
tool_use = next(b for b in response.content if b.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,
)
핵심적인 세부 사항은 tool_use_id입니다. tool_result 블록은 tool_use 블록의 정확한 id를 참조해야 모델이 어떤 호출에 대한 결과인지 알 수 있습니다. 다단계 에이전트의 경우, `stop_reason`이 `end_turn`이 될 때까지 계속되는 루프 안에 이 로직을 감싸게 됩니다. Python SDK는 또한 루프를 처리하는 도구 실행기를 제공하지만, 위의 수동 버전은 내부에서 어떤 일이 일어나는지 보여주고 승인 게이트 또는 로깅을 추가할 수 있는 지점을 제공합니다.
적응적 사고 및 노력
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": "불안정한 웹훅 수신기에 대한 재시도 전략을 설계하세요."}],
)
effort는 모델이 얼마나 많이 생각하고 작동하는지를 제어합니다. 낮은 노력은 더 간결하고 빠른 응답을 의미하며, 높은 노력은 더 많은 토큰 비용으로 더 철저한 추론을 의미합니다. 추가적인 추론이 토큰 가치만큼 중요하지 않은 간단한 조회 및 짧은 답변에는 둘 다 끄세요. Fable 5가 설계된 장기적인 계획과 같은 어려운 다단계 문제에 이 기능을 사용하세요. 처음에는 간단하게 유지하고, 나중에 경로에 필요하다는 것을 알게 되면 thinking을 추가할 수 있습니다.
오류 처리 및 안전장치 대체
실제 통합에서는 실패를 깔끔하게 처리해야 합니다. SDK는 유형화된 예외를 발생시키므로, 오류 문자열을 일치시키기보다는 특정 클래스를 catch하세요. 가장 자주 보게 될 세 가지는 HTTP 401, 429, 400에 해당합니다.
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 키. ANTHROPIC_API_KEY를 확인하세요.
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}")
각 오류가 의미하는 바와 해결 방법은 다음과 같습니다.
- 401 (
AuthenticationError): 키가 없거나, 형식이 잘못되었거나, 취소되었습니다. 코드가 실제로 실행되는 환경에ANTHROPIC_API_KEY가 설정되어 있는지, 그리고 콘솔에서 키가 여전히 활성 상태인지 확인하세요. - 429 (
RateLimitError): 분당 요청 또는 분당 토큰 제한을 초과했습니다. SDK는 이미 지수 백오프(기본적으로 두 번 재시도)를 사용하여 429 및 5xx 오류를 재시도합니다. 사용자 지정 백오프를 추가하는 경우retry-after헤더를 읽으세요. - 400 (
BadRequestError): 요청 형식이 잘못되었습니다. 일반적인 원인으로는 비어 있는messages배열, 누락된max_tokens, 또는 역할이 올바르게 교체되지 않은 메시지 등이 있습니다. 오류 메시지는 일반적으로 필드 이름을 지정합니다.
이제 안전장치 대체(safeguard fallback)에 대해 설명합니다. Fable 5는 민감한 쿼리(사이버 보안, 생물학 및 화학, 증류 시도)의 작은 부분을 직접 답변하는 대신 Claude Opus 4.8로 라우팅합니다. 이는 세션의 5% 미만에서 발생합니다. 오류는 아니며 요청은 여전히 성공하지만, 응답은 다른 모델로 태그되어 돌아올 수 있습니다. response.model을 로깅하거나 단언할 때, claude-fable-5가 아니라고 해서 무조건 실패 처리하지 마세요. 요청은 내부적으로 다른 모델에 의해 처리된 것입니다. 애플리케이션이 어떤 모델이 답변했는지 엄격하게 알아야 하는 경우, 보낸 내용과 일치한다고 가정하기보다는 반환된 객체에서 response.model을 읽으세요.
요청당 비용 추정
가격은 입력 토큰 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}")
출력 토큰은 입력 토큰 비용의 5배이므로, 가장 저렴하게 비용을 절감하는 방법은 응답을 간결하게 유지하는 것입니다. 2,000개의 입력 토큰과 500개의 출력 토큰을 사용하는 요청은 2000 / 1M * $10 + 500 / 1M * $50이며, 이는 $0.02 + $0.025 = $0.045입니다. 요청 볼륨을 곱하여 예산을 책정하세요. 출력 비용이 청구서의 대부분을 차지한다면, max_tokens를 제한하고 시스템 프롬프트에서 간결한 답변을 요청하세요. 출력 가격 책정은 Claude Opus 4.8 가격 모델에 적용하는 것과 동일한 계산 방식이며, 단지 Fable 5의 숫자를 사용합니다.
Apidog로 Claude Fable 5 API 테스트 및 디버그하기
클라이언트 코드를 작성하기 전에, 몇 번의 요청을 직접 보내보고 정확히 어떤 응답이 돌아오는지 확인하는 것이 좋습니다. Apidog는 이를 위해 만들어진 API 클라이언트입니다. https://api.anthropic.com/v1/messages로 실제 요청을 보내고, 스트리밍 응답을 검사하며, 요청을 저장하여 팀 전체가 동일한 정의를 기반으로 작업할 수 있습니다. 다음은 아무것도 없는 상태에서 작동하는 저장된 요청까지의 깔끔한 경로입니다.
- 요청 생성. Apidog에서 새 HTTP 요청을 만들고, 메서드를
POST로 설정한 다음, URLhttps://api.anthropic.com/v1/messages를 붙여넣으세요. 이 엔드포인트는 이 가이드의 모든 예시에서 사용됩니다. - 키를 환경 변수로 저장. Apidog 환경 변수를 생성하고,
anthropic_api_key와 같은 이름으로 지정한 후, 키를 비밀 값으로 붙여넣으세요. 환경에 키를 유지하면 저장된 요청과 공유하는 모든 내보내기에서 키가 노출되지 않습니다. - 헤더 설정.
x-api-key에{{anthropic_api_key}}값을 추가한 다음,anthropic-version: 2023-06-01및content-type: application/json을 추가하세요. Bearer 스타일의 비밀 변수를 선호하는 경우, 동일한 방식으로 토큰을 저장하고{{...}}구문을 사용하여 참조하면 원시 값이 요청에 나타나지 않습니다. - JSON 본문 추가. 최소 페이로드인
{"model": "claude-fable-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "결제 API의 멱등성 키에 대해 설명하세요."}]}를 입력하세요. 이를 보내고 응답을 읽으세요. 응답 패널에서content블록,stop_reason,usage를 바로 볼 수 있을 것입니다. - 스트리밍 응답 보기. 본문에서
"stream": true를 설정하고 다시 보내세요. Apidog는 서버 전송 이벤트를 도착하는 대로 렌더링하므로, 토큰이 스트리밍되는 것을 확인하고 앱에 빌드하기 전에 스트리밍 로직이 API가 실제로 보내는 것과 일치하는지 확인할 수 있습니다. - 코드 저장 및 생성. 요청을 컬렉션에 저장하여 팀원들이 재사용할 수 있도록 하고, Apidog의 코드 생성 기능을 사용하여 Python, JavaScript, curl 또는 다른 언어로 작동하는 스니펫을 내보내세요. 이는 빈 파일 대신 테스트된 시작점을 제공합니다.
이 워크플로는 API의 정확한 응답 형태를 파악하고 앱에서 오작동하는 요청을 디버그하는 가장 빠른 방법입니다. 이는 코드의 요청을 잘 알려진 올바른 요청과 나란히 비교할 수 있기 때문입니다. 설정할 준비가 되면, Apidog를 다운로드하고 위에서 설명한 최소한의 본문으로 시작하세요.