Claude Fable 5.2 API 연결부터 응답 검증과 비용 계산까지

Fable 5.2를 처음 연결할 때는 정확한 모델 ID로 작은 요청 하나를 보내고, 응답 텍스트와 종료 사유를 확인하세요. 그다음 도구를 추가하거나 기존 대화를 옮기는 것이 좋습니다. Ofox 카탈로그 ID는 anthropic/claude-fable-5.2, Claude API ID는 claude-fable-5-2입니다. 두 ID는 서로 다른 공급자 설정에 사용됩니다.

이 글은 공개된 모델 규약, 현재 Ofox 카탈로그, 애플리케이션 검증을 구분합니다. 문서와 카탈로그, 소규모 네이티브 프로토콜 API 테스트는 2026년 11월 10일 확인했습니다. 아래 cURL 본문은 실제 테스트에 사용했습니다. SDK 코드는 같은 방식으로 연결하는 예시이며 서비스에서 별도로 실행하지 않았습니다. 이 블로그를 발행하는 Ofox는 여기서 설명하는 게이트웨이를 제공합니다.

엔드포인트와 정확한 ID를 함께 선택하기

공식 개요에는 컨텍스트 100만 토큰, 최대 출력 128K 토큰이 명시되어 있습니다. 이는 상한이지 첫 요청에 적합한 기본 크기가 아닙니다. 민감하지 않은 짧은 입력과 제한된 출력량으로 시작하세요.

Ofox 모델 페이지와 공개 카탈로그에는 Anthropic 및 OpenAI 프로토콜이 표시되어 있으며, 5.2의 현재 공급자 유형은 aws_bedrock입니다. 프로토콜 표기만으로 모든 경로에서 Anthropic 베타 기능을 전부 전달한다고 볼 수는 없습니다. 특정 기능에 의존하기 전에 해당 기능을 직접 검증해야 합니다.

버전 선택에서 놓치기 쉬운 점이 있습니다. 날짜가 기록된 카탈로그 스냅샷에서 claude-fable-latest는 여전히 5.1 항목의 별칭입니다. 배포 테스트에는 정확한 5.2 ID를 사용하고 응답의 모델과 요청 ID를 기록하세요. 새 버전이 나왔다고 별칭도 바뀌었다고 가정하면 안 됩니다.

작은 네이티브 요청 보내기

Ofox 인증 안내에 따라 API Key를 만들고 기존 비밀 관리 도구를 통해 OFOX_API_KEY에 불러오세요. 서버나 로컬 개발 머신에서 실행해야 하며, 배포되는 브라우저 코드에 넣으면 안 됩니다. 아래 본문에서는 샘플링, 도구 강제 선택, 선택적 베타 설정을 의도적으로 제외했습니다.

curl --fail-with-body --max-time 180 \
  https://api.ofox.ai/anthropic/v1/messages \
  -H "x-api-key: $OFOX_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'content-type: application/json' \
  --data '{
    "model": "anthropic/claude-fable-5.2",
    "max_tokens": 4096,
    "output_config": {"effort": "low"},
    "messages": [{
      "role": "user",
      "content": "A synthetic order contains 3 units at USD 12 each. Return the total and one calculation line. Do not use tools."
    }]
  }' > response.json

계산상 정답은 36 USD입니다. 실제 응답에는 이 금액과 계산식이 들어 있었으며 HTTP 200, stop_reason: "end_turn", 입력 46토큰, 출력 32토큰이 기록됐습니다. 단일 합성 요청은 이 좁은 사례를 확인할 뿐, 모든 운영 워크플로를 검증하지는 않습니다. 다음 단계 전에 자신의 response.json을 확인하세요. HTTP 성공만으로 답변 생성, 지시 이행, 출력 한도 내 완료를 확인할 수는 없습니다.

첫 번째 콘텐츠 블록이 텍스트라고 가정하지 않도록 다음 확인 스크립트를 사용할 수 있습니다.

import json
from pathlib import Path

response = json.loads(Path("response.json").read_text())
if "error" in response:
    raise RuntimeError(response["error"])
text = "\n".join(
    block.get("text", "") for block in response.get("content", [])
    if block.get("type") == "text"
)
print("model:", response.get("model"))
print("stop_reason:", response.get("stop_reason"))
print("usage:", response.get("usage"))
print(text)
if response.get("stop_reason") != "end_turn" or not text.strip():
    raise SystemExit("Not a completed text answer; inspect before continuing.")

도구를 쓰지 않는 이 테스트에서는 완료된 텍스트 답변을 요구하고 계산을 수동으로 확인합니다. 운영 작업에서는 결과에 맞는 독립 검증기로 수동 확인을 대체하세요. 36이라는 문자열을 찾는 것만으로는 부족합니다. “합계는 36이 아니다”에도 그 문자열이 들어갑니다.

네이티브 Messages 문서에는 엔드포인트와 인증 형식이 설명되어 있습니다. 애플리케이션이 Chat Completions를 사용한다면 messages, 응답, 도구 결과 모두 해당 형식을 유지하세요. OpenAI 형식 대화에 네이티브 tool_result 블록을 넣고 어댑터가 원래 상태를 복원할 것이라고 가정하면 안 됩니다.

추론과 답변에 필요한 출력 공간 확보하기

Fable 5.2는 적응형 추론이 항상 활성화되어 있습니다. output_config.effort는 추론 노력 수준을 조절하지만 토큰당 단가를 바꾸지는 않습니다. 작은 테스트에서는 단순 작업을 제한하기 위해 low를 사용했습니다. 복잡한 저장소 수정이나 여러 단계의 분석에도 이 설정을 권장한다는 뜻은 아닙니다.

실질적인 작업은 문서상 기본값인 high에서 시작해 자신의 검수 사례로 낮은 설정과 비교하세요. Anthropic의 effort 안내는 추가 노력이 도움이 되는 작업에 높은 설정을 사용하도록 권합니다. 답변이 얼마나 그럴듯한지뿐 아니라 총 토큰과 완료 여부를 측정해야 합니다.

max_tokens에는 추론과 답변 출력이 함께 포함됩니다. 한도가 작으면 추론 블록 뒤에 stop_reason: "max_tokens"가 나오고 가시적인 답변은 없을 수 있습니다. 이는 400 요청 오류와 다릅니다. 종료 사유를 확인한 뒤 의도적으로 한도를 늘리거나 effort를 낮추세요. 같은 한도로 무작정 반복한 비용을 모델 가격 비교라고 해석하면 안 됩니다.

스트리밍 후 최종 메시지 보존하기

공식 Python SDK에서는 스트리밍이 끝난 뒤 조립된 메시지를 보관하세요. 다음은 문서에 나온 output_config를 지원하는 최근 SDK용 예시입니다. 애플리케이션에서 검증한 SDK 버전을 기록하고 고정하세요.

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["OFOX_API_KEY"],
    base_url="https://api.ofox.ai/anthropic",
    max_retries=0,
    timeout=180.0,
)
with client.messages.stream(
    model="anthropic/claude-fable-5.2",
    max_tokens=4096,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "Calculate 3 times 12."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print(final_message.stop_reason, final_message.usage)

텍스트 스트림은 화면 표시용입니다. 다음 도구 턴을 위해 저장해야 할 전체 메시지는 아닙니다. 완료 전에 연결이 끊기면 해당 시도를 미완료로 표시하세요. 일부만 표시된 텍스트를 유효한 assistant 응답으로 저장하면 안 됩니다. 텍스트 전용 수집기가 놓칠 수 있는 필드는 thinking 서명 오류 진단에서 확인할 수 있습니다.

외부 동작 전에 읽기 전용 도구 하나 추가하기

첫 도구로는 합성 재고 레코드를 반환하는 함수를 사용할 수 있습니다. 문자열 SKU가 필수인 입력 스키마로 lookup_stock을 정의하고, tool_choice를 auto로 설정한 다음 DEMO-001 조회를 요청하세요. 실행 전에는 생성된 도구 이름과 인수가 허용 목록에 맞는지 검증합니다.

전체 실행 예제가 필요하면 읽기 전용 재고 실행 스크립트와 체크포인트 모듈을 사용하세요. 이 버전은 예제 데이터 세 행을 모두 읽는 read_stock을 정의하며, 최초 요청, 도구 검증, 실제 결과 메시지, 대화 계속하기, 최종 인계 검증을 포함합니다. 단계별 안내는 로컬 확인과 명시적으로 실행하는 유료 호출을 구분합니다.

네이티브 프로토콜에서는 반환된 assistant 콘텐츠 전체를 그대로 추가합니다. 이어서 실제 결과와 일치하는 도구 ID를 담은 user 메시지를 추가하세요.

# response is the completed SDK response; tool is one validated tool_use block.
messages.append({
    "role": "assistant",
    "content": [b.model_dump(exclude_none=True) for b in response.content],
})
messages.append({"role": "user", "content": [{
    "type": "tool_result",
    "tool_use_id": tool.id,
    "content": '{"sku":"DEMO-001","available":7,"source":"synthetic fixture"}'
}]})

이 코드는 대화를 이어가는 형식만 보여주며, 여러 도구를 처리하는 완전한 실행기는 아닙니다. 여러 호출이 반환되면 모든 ID를 처리하고 각각의 실제 결과를 전달해야 합니다. 도구가 실패하면 오류 결과를 보내야 하며 성공 레코드를 지어내면 안 됩니다. tool_result 누락 안내는 연결 오류를, 5.2 업그레이드 안내는 버전별 제약을 설명합니다.

auto는 “도구가 반드시 실행된다”는 뜻이 아닙니다. 조회가 필요한 작업에 텍스트만 반환되면 애플리케이션이 이를 감지하고 완료 처리를 거부해야 합니다. 디버깅 재시도가 주문이나 메시지를 두 번 보내지 않도록 읽기 전용 예제로 시작하세요.

토큰 유형을 구분해 비용 계산하기

11월 10일 확인한 표준 요금이며 단위는 100만 토큰당 USD입니다.

출처는 Anthropic 가격표, Ofox 모델 페이지, 날짜가 기록된 카탈로그 스냅샷입니다. Ofox 저장소는 이 필드를 토큰당 USD로 정의하며, 표에서는 100만을 곱했습니다. 저장소 코드는 동적인 모델 데이터를 읽으므로 Git 소스 자체가 최신 정적 가격표는 아닙니다. 5.2 스냅샷에는 별도 provider_price 객체가 없습니다. 이는 공급자 가격 데이터의 부재이지, 공급자 비용이 0이거나 할인이 검증됐다는 의미가 아닙니다.

캐시되지 않은 입력 20,000토큰과 과금 출력 4,000토큰을 가정하면 다음과 같습니다.

20,000 × $8 / 1,000,000 + 4,000 × $40 / 1,000,000 = $0.32

캐시 읽기 19,000토큰, 캐시되지 않은 입력 1,000토큰, 동일한 출력을 가정하면 다음과 같습니다.

19,000 × $0.20 / 1,000,000 + 1,000 × $8 / 1,000,000
+ 4,000 × $40 / 1,000,000 = $0.1718

두 번째 예제에는 앞선 캐시 쓰기 요청이 포함되지 않습니다. 전체 세션 비용을 계산할 때는 해당 요청을 더해야 합니다. 입력 유형은 서로 겹치지 않게 구분하고, 캐시 쓰기 토큰을 캐시되지 않은 입력에 다시 더하지 마세요. 과금되는 추론 출력, 재시도, 별도 과금 도구도 계산에 포함합니다. 이는 계산 예제이지 관찰된 청구서가 아닙니다. Batch 또는 fast mode 요금은 별도의 적용 조건과 경로 확인이 필요하며 여기서는 적용하지 않았습니다.

실제 API 응답으로 채운 로컬 테스트 기록의 영문 스크린샷입니다. Ofox 제품 인터페이스 스크린샷이 아닙니다.

운영에 옮길 준비가 됐는지 판단하기

추가 네이티브 프로토콜 테스트에서는 스트리밍 텍스트 응답과 읽기 전용 도구 왕복이 완료됐습니다. 의도적으로 호환되지 않는 설정을 넣은 두 요청도 200을 반환했습니다. 하나는 thinking: {"type":"disabled"}를 보냈고, 다른 하나는 도구 없이 계산하라는 프롬프트를 유지한 채 lookup_stock을 강제 선택했습니다. 후자는 도구 호출 없이 텍스트만 반환했습니다. 어느 응답도 해당 제어가 작동했다는 증거는 아닙니다. 400 오류 글의 경로별 결과는 애플리케이션 검수가 필요한 이유를 설명합니다.

트래픽을 옮기기 전에 네 가지를 확인하세요. 완료된 텍스트 요청, 완전한 스트림, ID가 맞는 읽기 전용 도구 왕복, 변경되지 않은 이력으로 복원된 기존 다중 턴 세션입니다. 각 사례의 요청 ID, 정확한 모델, effort, usage, 종료 사유, SDK 버전, 검수 결과를 보관합니다.

400이면 동일 요청을 재시도하기보다 본문을 진단하세요. 과부하에서는 재시도를 제한하고 Claude 529 안내 (영문)를 참고하세요. 모델을 바꿀 때는 체크포인트 튜토리얼처럼 애플리케이션 사실을 불투명한 추론과 별도로 저장합니다. 5.2·5.1·Opus 5.5 비교에서는 비용과 마이그레이션 판단을 다룹니다.

관련 문서: API 인증, 네이티브 Messages, 공급자 라우팅. 데이터 보관 요구사항은 실제 처리 서비스와 확인해야 합니다. Anthropic은 5.2의 모델별 보관 요건을 명시하며, Ofox의 프로토콜 지원 표시는 개인정보 보호 보장이 아닙니다.