편집 워크플로에 맞는 Claude Sonnet API 버전 고르기

편집 연동은 모델 이름만으로 끝나지 않아요. 샘플링 설정, 강제 함수 호출, 응답 파서에 의존할 수 있거든요. 버전을 올리면 편집 품질이 달라지기 전에 이 세 가지가 먼저 바뀔 수 있어요.

새로 만든다면 Sonnet 5를, 64,000 토큰보다 긴 응답이나 무검열 픽션, 가장 넓은 effort 범위가 필요하면 Sonnet 5.5를, temperature, top_p, top_k 제어가 필요하면 Sonnet 4.6을 선택하세요. Sonnet 5는 강제 도구 호출도 지원하지만 5.5는 지원하지 않아요. 모델 ID만 바꾸면 요청이 깨져요. Sonnet 5와 5.5는 샘플링 필드에 400 오류를 반환하고, 5.5는 강제 도구 선택도 거부해요. 응답을 비교하기 전에 버전별로 이 필드들을 제거하세요.

아래 표는 SpicyAPI가 호스팅하는 계약을 설명해요. Anthropic의 Sonnet 5.5 마이그레이션 가이드는 네이티브 버전 변경을 설명하지만, 필드 이름과 기본값은 이 인터페이스와 서로 호환되지 않아요. 아래 가격은 100만 토큰당 USD예요.

버전별로 허용하는 항목

ID는 anthropic/claude-sonnet-4.5/chat, anthropic/claude-sonnet-5/chat, anthropic/claude-sonnet-5.5/chat, anthropic/claude-sonnet-4.6/chat이고, 페이지는 4.5, 5, 5.5, 4.6이에요. 네 모델 모두 같은 /v1/chat/completions 요청 형식을 쓰고, stop, tools, parallel_tool_calls도 받아요.

Sonnet 4.6은 중간 단계의 이전 선택지예요. 이미 1M 윈도우와 reasoning_effort가 있지만 temperature는 계속 받아요. 4.5에서 4.6으로 옮기면 요청 형식은 그대로이고, 입력 요금이 11% 오르며, 등급이 완화됨에서 무검열로 바뀌고, 기본 추론 effort가 medium이 돼요. 샘플링이 사라지는 것은 4.6에서 5로 넘어갈 때예요.

콘텐츠 등급은 픽션과 롤플레이에서 중요해요. Sonnet 5는 필터링됨이고, 우리 테스트에서 Sonnet 4.5와 4.6은 수위가 높은 성인 픽션 요청을 완화하거나 거부하는 경우가 많았어요. Sonnet 5.5는 테스트한 장면을 완화나 거부 없이 내놓았으므로, 성인 픽션 작업에는 이 중 가장 알맞은 선택이에요. 완화된 응답에도 요금이 부과될 수 있어요. SpicyAPI는 플랫폼 차원의 콘텐츠 필터를 추가하지 않아요. 허구의 장면과 편집 제약은 시스템 메시지에 지정하세요.

어떤 버전을 고를까

• 성인 콘텐츠가 없는 새 텍스트 연동: Sonnet 5. 요금이 가장 낮고, 1M 윈도우와 세 가지 effort 단계가 있어요.
• 긴 결과물이나 성인 대상 픽션: Sonnet 5.5. 한 번의 응답으로 64,000 토큰을 넘게 쓸 수 있는 유일한 모델이고, none(사고 없음)이 있는 유일한 모델이며, 무검열이에요.
• 샘플링 제어: 4.5로 고정한 연동을 유지하거나, 1M 윈도우를 위해 4.6으로 옮기세요. 샘플링 없는 강제 함수 호출: Sonnet 5가 더 낮은 요금으로 지원해요. 호출을 강제해야 한다면 5.5 대신 이 모델을 쓰세요.
• 300,000 토큰짜리 원고 전체를 한 번에 처리: 컨텍스트와 비용의 문제이며 Sonnet 4.6 장문 원고 가이드에서 다뤄요.

가격: 토크나이저와 과금되는 출력을 고려하세요

Sonnet 5와 5.5는 더 새로운 토크나이저를 써요. Anthropic의 마이그레이션 가이드에 따르면 같은 텍스트라도 내용에 따라 4.x보다 약 30% 많은 토큰이 만들어지므로, 토큰당이 아니라 작업당 비용으로 비교하세요. 4.5에서 입력 20,000, 출력 2,000 토큰이 드는 예시 작업에서 5와 5.5는 두 토큰 수가 모두 30% 늘어난다고 가정해 볼게요.

이 시나리오에서 Sonnet 5는 4.5보다 약 9% 낮지만, 이 절감 폭이 모든 문서에 똑같이 적용되는 것은 아니에요. 출력 수에는 과금되는 추론 토큰이 포함되어야 해요. effort를 low로 두면 사고를 줄일 수는 있지만 끌 수는 없어요. 여기서 none을 제공하는 모델은 5.5뿐이에요. 추정치를 예산으로 삼기 전에 실제 작업의 사용량을 확인하세요.

Sonnet 5.5의 요금은 Sonnet 5보다 약 5.3% 높은데, 이는 과금 토큰 수와 캐시 범주가 같을 때의 차이예요. 토크나이저가 바뀌면 긴 프롬프트의 토큰 수를 다시 세어 보세요. 가령 30% 늘어난다면 190,000 토큰 프롬프트는 247,000이 되고, 입력 한도 1M보다는 여전히 낮지만 청구액은 달라져요.

Playground에서 편집 시험하기

더 큰 워크플로를 이전하기 전에 이 간단한 사실 확인 편집으로 먼저 시험해 보세요.

Source A: the gallery reopened to staff in April. Source B: the public launch event was in June. Draft: "The gallery reopened to the public in April." Preserve the distinction between staff access and the public event. Return the corrected sentence and one sentence explaining the change.

1. 위에 링크한 Sonnet 5.5 모델 페이지를 열고 Playground를 선택하세요. 사용자 메시지에 두 출처와 초안을 넣고, 시스템 지침으로 "Edit from the supplied sources only"를 지정하세요.
2. 이 한 줄 수정에는 effort low를 쓰세요. 비용을 확인한 뒤 실행하고, 답변이 직원 입장은 4월, 공개 행사는 6월로 구분을 유지하는지, 정확한 날짜를 지어내지 않았는지 확인하세요.
3. 같은 텍스트를 Sonnet 5로도 시험해 보세요. 성인 콘텐츠가 없는 더 저렴한 편집 워크플로에 맞는지 볼 수 있어요. 편집 자체를 판단할 수 있도록 원문은 바꾸지 마세요.

실제로 납품하는 편집에 맞춰 버전 고르기

출처 묶음이 20,000 토큰인 700단어 분량의 챕터를 다듬는 작업에서는 어느 버전도 최대 컨텍스트나 최대 출력이 필요하지 않아요. 중요한 것은 요청의 제어 항목과 콘텐츠 적합성이 맞는지예요. 일반적인 편집에서는 Sonnet 5가 가격이 낮은 출발점이에요. 성인 픽션 편집자라면 원고 전체의 기본값으로 정하기 전에 필터링됨 등급도 함께 고려해야 해요. 그래서 같은 애플리케이션이라도 수위가 낮은 시놉시스와 성숙한 장면 검토에는 서로 다른 모델이 필요할 수 있어요.

4.5나 4.6에서 표현을 세 가지로 달리 받고 싶다면, 샘플링 제어가 생성을 다양하게 만드는 허용된 방법이에요. 하지만 temperature를 높인다고 어긋난 이야기 논리가 고쳐지는 것은 아니에요. 인물이 아직 알 수 없는 정보를 알고 있는 문단에는 무작위성이 아니라 지식 규칙과 원문 구절이 필요해요. 5나 5.5에서는 동등한 샘플링 필드를 만들어 내지 마세요. 대신 접근 방식을 다르게 명시한 세 가지 대안을 요청하세요. 대사를 더 짧게, 설명을 줄여서, 또는 반전을 더 늦게 같은 식으로요.

도구를 활용하는 편집을 생각해 볼게요. 초안에 인물의 고용주가 적혀 있는데, 현재 기록은 시리즈의 공식 데이터베이스에 있다고 해요. 4.5, 4.6, 5에서는 제공되는 도구 선택으로 조회를 필수로 만들 수 있어요. 5.5에서는 auto이므로 조회 없이 답할 수 있어요. 애플리케이션이 고용주를 반드시 검증해야 한다면, 편집을 요청하기 전에 읽기를 먼저 수행하거나 필요한 조회 결과가 없는 답변은 받아들이지 마세요. 프롬프트의 한 문장으로는 auto가 강제 호출과 같은 보장을 주지 못해요. Anthropic 마이그레이션 가이드의 네이티브 thinking이나 output_config 예시를 이 요청에 그대로 붙여 넣어서는 안 돼요.

이 예시에서 의미 있는 결과는 4월의 직원 입장과 6월의 공개 출시를 모두 보존한 문장이에요. 직원이 4월에 이미 들어갈 수 있었다면 "The gallery reopened in June"은 너무 포괄적이에요. "The gallery held its public launch in June, after reopening to staff in April"는 사람이 쓴 수정으로 받아들일 만해요. 표현이 더 매끄러워졌어도 이 구분을 잃는 새 버전은 편집 작업을 개선한 것이 아니에요.

요청 이전하기

4.5 연동은 temperature: 0.2, top_p: 0.9, 그리고 강제 submit_edit 함수를 쓰고 있을 수 있어요. 5로 옮기면 샘플링 필드가 거부되고, 5.5로 옮기면 샘플링과 강제 도구 선택이 모두 거부돼요.

1. 5와 5.5에서는 샘플링을 제거하세요. 해당 요청에서 temperature, top_p, top_k를 삭제하세요. 지원하지 않는 필드는 작업이 생성되거나 과금되기 전에 400 unsupported_parameter를 반환해요. 공통 파라미터 객체 하나를 보내지 말고 모델별 허용 목록을 관리하세요.
2. 5.5에서는 자동 도구를 사용하세요. submit_edit 함수는 유지하고 시스템 프롬프트에서 호출하도록 요청하되, tool_choice는 auto로 설정하세요. 여기에는 response_format이 없고 5.5가 함수를 건너뛸 수 있으므로, 반환된 인자를 검증하세요. 워크플로에서 강제 호출이 필요하다면 Sonnet 5가 더 낮은 요금으로 지원해요.
3. 답변이 들어갈 여유를 남기세요. 추론은 max_tokens의 일부를 소모해요. 상한이 1,024 토큰이면 보이는 텍스트가 나오기 전에 바닥날 수 있어요. 한 줄 수정에는 low를, 출처가 서로 충돌할 때는 high를 쓰세요. Sonnet 5는 high까지만 지원하며 5.5의 xhigh와 max는 받지 않아요.
4. 긴 편집은 스트리밍하세요. 아래의 짧은 예시는 일반 JSON 응답을 써요. 큰 호출은 네트워크 엣지의 약 100초 제한을 넘길 수 있어요. 그런 경우에는 스트리밍을 쓰고 텍스트와 도구 인자를 따로 조립하세요. 완료 이벤트와 사용량은 텍스트와 스트리밍 가이드에서 다뤄요.
5. 대화는 사용자 메시지로 끝내세요. 4.5에서 옮겨 올 때는 의도한 시작 문구나 형식 힌트를 어시스턴트 프리필로 끝내지 말고 시스템 지침으로 옮기세요.

effort 이름의 의미도 달라져요. Anthropic이 5.5의 단계를 다시 조정했으므로 high는 버전 간에 같지 않아요. SpicyAPI는 5와 5.5 모두 기본값을 medium으로 두지만, Anthropic의 네이티브 5.5 API는 기본값이 high예요. 깔끔한 짧은 답변에는 none보다 low를 권해요. none에서는 5.5가 보이는 텍스트 안에서 질문을 풀어 가기도 해요. none은 캐릭터로서 빠르게 주고받는 턴에는 여전히 유용해요.

편집 실행하고 검증하기

이 코드를 sonnet_edit.py로 저장하고 API Keys에서 받은 SPICY_API_KEY를 설정한 뒤 python3 sonnet_edit.py를 실행하세요. 파이썬 표준 라이브러리만 써요. 여기서 Sonnet 5.5를 고른 것은 자동 도구로의 이전을 보여 주기 위해서예요. 모델만 Sonnet 5로 바꿔도 이 필드들은 허용돼요. 이것은 유료 텍스트 호출이며 미디어 생성 작업이 아니에요. 멀티턴과 스트리밍 연동은 채팅 레시피에서 다뤄요.

import json
import os
import sys
import uuid
from urllib.error import HTTPError
from urllib.request import Request, urlopen

def read_reply(resp: dict, *, require_edit_tool: bool = False) -> dict:
    if resp.get("error"):
        raise RuntimeError("API error")
    choices = resp.get("choices") or []
    if not choices:
        raise RuntimeError("no choices in response")
    choice = choices[0]
    finish = choice.get("finish_reason")
    if finish not in {"stop", "tool_calls"}:
        raise RuntimeError(f"incomplete or rejected reply: {finish}")
    msg = choice.get("message") or {}
    calls = msg.get("tool_calls") or []
    if calls:
        if len(calls) != 1:
            raise RuntimeError("expected one submit_edit call")
        call = calls[0]
        if call.get("type") != "function" or not isinstance(call.get("id"), str) or not call["id"]:
            raise RuntimeError("missing function type or call ID")
        fn = call.get("function") or {}
        if fn.get("name") != "submit_edit":
            raise RuntimeError("unexpected function")
        args = json.loads(fn.get("arguments") or "")
        if not isinstance(args, dict) or any(
            not isinstance(args.get(key), str) or not args[key].strip()
            for key in ("sentence", "reason")
        ):
            raise RuntimeError("sentence and reason must be nonempty strings")
        return {"kind": "tool", "call": calls[0], "edit": args}
    if require_edit_tool:
        raise RuntimeError("model skipped submit_edit")
    text = msg.get("content")
    if finish != "stop" or not isinstance(text, str) or not text.strip():
        raise RuntimeError("empty or unfinished text")
    return {"kind": "text", "text": text}


def main() -> None:
    body = {
        "model": "anthropic/claude-sonnet-5.5/chat",
        "reasoning_effort": "low",
        "max_tokens": 8192,
        "messages": [
            {"role": "system", "content": "Edit from the supplied sources only. Reply by calling submit_edit."},
            {"role": "user", "content": 'Source A: the gallery reopened to staff in April. Source B: the public launch event was in June. Draft: "The gallery reopened to the public in April." Keep the staff/public distinction.'},
        ],
        "tools": [{"type": "function", "function": {
            "name": "submit_edit",
            "description": "Return the corrected sentence and the reason.",
            "parameters": {
                "type": "object",
                "properties": {"sentence": {"type": "string"}, "reason": {"type": "string"}},
                "required": ["sentence", "reason"],
            },
        }}],
        "tool_choice": "auto",
    }
    request = Request(
        "https://api.spicyapi.ai/v1/chat/completions",
        data=json.dumps(body).encode(),
        headers={
            "Authorization": f"Bearer {os.environ['SPICY_API_KEY']}",
            "Content-Type": "application/json",
            "Idempotency-Key": str(uuid.uuid4()),
            "User-Agent": "sonnet-edit-example/1.0",
        },
    )
    try:
        with urlopen(request, timeout=80) as response:
            task_id = response.headers.get("X-Spicy-Task-Id")
            if task_id:
                print(f"Task ID: {task_id}", file=sys.stderr)
            result = read_reply(json.load(response), require_edit_tool=True)
    except HTTPError as error:
        task_id = error.headers.get("X-Spicy-Task-Id")
        print(f"HTTP {error.code}; task ID: {task_id or 'not returned'}", file=sys.stderr)
        raise
    print(json.dumps(result["edit"], indent=2))


if __name__ == "__main__":
    main()

유효한 편집은 직원 입장은 4월, 공개 행사는 6월로 유지해요. 파서는 빈 답변, 잘린 응답, 건너뛰었거나 형식이 잘못된 함수 호출을 거부해요. 다만 유효한 인자라도 이 사실 확인은 별도로 필요해요. Sonnet 마이그레이션 보고서에는 빈 폴백이 성공한 결과로 사용자에게 전달된 사례가 소개되어 있어요.

finish_reason이 length라면 새 호출에서 출력 여유를 늘리거나 더 작은 작업으로 나누세요. 다시 비용을 쓰기 전에 부분 결과와 작업 ID를 보존하세요. 멀티턴 도구 워크플로에서는 다음 턴 전에 해당 tool_call_id와 함께 도구 결과를 돌려주세요. 이전 점검에는 모순 하나, 바뀌지 않은 사실 하나, "unknown" 답변 하나, "no match" 도구 결과 하나를 포함하세요. 더 긴 추출에서는 JSON이 유효한지뿐 아니라 필수 섹션이 있는지도 확인하세요.

Agent에게 연동 준비 맡기기

요청을 직접 붙여 넣는 대신 기존 편집기를 Agent가 맞춰 주길 원한다면 Agent를 쓰세요. 작업 지시에는 같은 갤러리 출처와 초안을 그대로 넣으세요.

• CLI: SPICY_API_KEY를 설정한 뒤 npx @spicyapi/cli models get anthropic/claude-sonnet-5.5/chat --json으로 선택한 계약을 확인하게 하세요. 이 읽기 전용 명령은 CLI 가이드에 나와 있어요.
• MCP: SpicyAPI MCP 서버를 연결한 뒤 이렇게 요청하세요. "Use spicyapi_model_get for anthropic/claude-sonnet-5.5/chat, then adapt my gallery edit to its accepted effort and tool-choice settings. Prepare the request without running it."
• Skill: npx skills add spicyapi-ai/spicy-skill로 공식 SpicyAPI Skill을 설치하고 새 Agent 세션을 시작한 뒤 이렇게 요청하세요. "Use the SpicyAPI Skill to migrate my gallery editor from Sonnet 4.5 to 5.5. Keep the source facts and validate submit_edit; show me the request before calling it."

CLI와 MCP는 이 텍스트 워크플로를 위한 모델 탐색을 제공해요. 편집 자체는 위의 프로그램이나 Agent의 HTTP 클라이언트를 통해 /v1/chat/completions를 써요. 반복 편집을 맡기기 전에 API 키에 지출 한도를 설정하세요.

FAQ

Sonnet 5.5가 Sonnet 5보다 저렴한가요?

아니요. 토큰당 약 5.3% 더 비싸요($1.90과 $9.50 대비 $2와 $10). 과금 토큰 수와 캐시 범주가 같을 때만 작업 비용이 그만큼 더 들어요. 그 추가 비용으로 128,000 토큰의 응답 상한, none과 xhigh effort, 무검열 등급을 얻어요.

Sonnet 5.5가 Opus 5.5보다 나은가요?

일반적으로는 그렇지 않아요. SpicyAPI에서 Opus 5.5는 입력 $3.60, 출력 $18로 Sonnet 5.5의 약 1.8배이고, 1M 윈도우와 128,000 출력 상한은 같아요. Sonnet 5.5로 시작해서, 가장 어려운 구절이 틀리게 돌아올 때만 올라가세요. 그 경로는 「Claude Opus 5.5 NSFW 롤플레이」 가이드에서 다뤄요.

Sonnet 5.5에서 temperature를 계속 쓸 수 있나요?

아니요. 깊이는 추론 effort로 조절하고, 톤에 관한 규칙은 시스템 프롬프트에 넣으세요. 샘플링 제어가 필요하다면 4.5와 4.6이 선택지예요.