# Claude Sonnet 5.5 API (https://wanapi.app/ko/docs/claude-sonnet-5-5)





이 참조 문서는 **Claude Sonnet 5.5**의 Messages 매개변수를 설명합니다. `POST https://api.wanapi.app/v1/messages`에 `claude-sonnet-5-5`를 사용하세요. [Claude 모델 비교](/ko/docs/claude-api).

## 모델 설정 [#모델-설정]

| 설정                       | Claude Sonnet 5.5      |
| ------------------------ | ---------------------- |
| 모델 ID                    | `claude-sonnet-5-5`    |
| 컨텍스트 창                   | 토큰 1M개                 |
| 최대 동기 출력                 | 사고 토큰을 포함하여 128000개    |
| 사고 모드                    | 적응형 또는 `between_tools` |
| 기본 사고 노력                 | `high`                 |
| 강제 도구 호출(`any` / `tool`) | 지원하지 않음                |

## 연결 및 요청 전송 [#연결-및-요청-전송]

[API 키 설정](/ko/settings/apikeys)에서 키를 생성하세요. 하나의 API 키로 모든 모델과 그룹을 이용할 수 있습니다. 서버 환경의 `WAN_API_KEY`에 키를 보관하세요. `anthropic-version: 2023-06-01`을 전송하고, 필요한 기능에만 `anthropic-beta`를 추가하세요.

```bash
curl https://api.wanapi.app/v1/messages \
  -H "x-api-key: $WAN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Explain the purpose of a database index in three sentences."}]
  }'
```

```python
import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["WAN_API_KEY"],
    base_url="https://api.wanapi.app",
)
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain the purpose of a database index in three sentences."}],
)
print("".join(block.text for block in message.content if block.type == "text"))
```

## 현재 API 지원 범위 [#현재-api-지원-범위]

아래 표는 이 모델의 네이티브 API 규격을 설명합니다. Wan API는 현재 호환 계층을 통해 요청을 전달합니다. &#x2A;*`max_tokens`에는 양수를 사용하세요.** 현재 게이트웨이는 `0`을 생성용 토큰 예산으로 바꾸므로, 여기에서는 캐시만 미리 채우는 용도로 사용할 수 없습니다.

현재 게이트웨이는 `diagnostics`, `compaction`, `fallbacks`, `fallback_credit_token`, `thread`를 전달하지 않습니다. 현재 채널 설정에서는 `speed`, `service_tier`, `inference_geo`도 걸러집니다. 아래에 이 필드들을 기재한 것은 모델의 규격을 설명하기 위한 것이며, 현재 연결에서는 아직 사용할 수 없습니다. 응답이 성공했다고 해서 무시된 필드가 적용되었다는 뜻은 아닙니다. 이 필드들이 필요한 베타 기능에도 같은 제한이 적용됩니다.

## 매개변수 [#매개변수]

| 매개변수                              | 자료형 / 필수 여부            | 공식 제약 및 기본값                                                                                                                                                                         |
| --------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                           | 문자열, 필수                | `claude-sonnet-5-5`.                                                                                                                                                                |
| `max_tokens`                      | 정수, 필수                 | 사고 토큰을 포함하여 0–128000. 공식 API에서 0은 출력 없이 프롬프트 캐시를 채웁니다. 현재 API 지원 범위를 참고하세요.                                                                                                         |
| `messages`                        | 객체 배열, 필수              | 대화 메시지 최소 1개, 최대 100000개. 각 메시지에 `role`과 `content`가 있으며, content는 문자열 또는 콘텐츠 블록 배열입니다. 일반 턴은 `user`/`assistant`를 사용합니다. 대화 중간의 `system` 메시지는 공식 배치 규칙을 따릅니다.                        |
| `system`                          | 문자열 또는 텍스트 블록 배열       | 최상위 지침. 텍스트 블록에 캐시 분기점을 포함할 수 있습니다.                                                                                                                                                 |
| `thinking`                        | 객체                     | 기본값: `{"type":"adaptive"}`. 다른 지원 모드는 `{"type":"between_tools"}`입니다. 수동 예산과 `disabled`는 거부됩니다.                                                                                      |
| `thinking.display`                | 열거형                    | 적응형 모드에서만 사용: `omitted`(기본값) 또는 `summarized`. 요약 생략은 사고 비활성화를 뜻하지 않습니다.                                                                                                             |
| `thinking.block_binding`          | 객체, 베타                 | 적응형 모드에서만 사용. `thinking-binding-controls-2026-08-01`이 필요하며, 공식 사고 보존 규격을 따라야 합니다.                                                                                                   |
| `output_config.effort`            | 열거형 또는 null            | `low`, `medium`, `high`, `xhigh`, `max`. 기본값은 `high`이며 null은 기본값을 유지합니다.                                                                                                            |
| `output_config.format`            | 객체 또는 null             | 구조화된 JSON 출력: `{"type":"json_schema","schema":{...}}`. 지원되는 JSON Schema 하위 집합을 사용하세요.                                                                                               |
| `stream`                          | 불리언                    | 기본값은 `false`. `true`이면 SSE 이벤트를 반환합니다.                                                                                                                                              |
| `stop_sequences`                  | 문자열 배열                 | 공식 API에서는 일치하는 문자열에서 생성을 중단합니다. 업스트림 호환성 점검에서는 이 동작이 적용되지 않았습니다.                                                                                                                    |
| `temperature`                     | 숫자 또는 null             | 호환용으로 1만 허용합니다. 생략하세요. 그 외 null이 아닌 값은 거부됩니다.                                                                                                                                       |
| `top_p`                           | 숫자 또는 null             | 호환용으로 0.99–1만 허용합니다. 생략하세요.                                                                                                                                                         |
| `top_k`                           | null 이외의 값은 허용하지 않음    | 샘플링을 지원하지 않습니다. 이 속성을 생략하세요.                                                                                                                                                        |
| `tools`                           | 객체 배열                  | 클라이언트 도구는 `name`, `input_schema`와 선택적 설명·엄격성 설정을 가집니다. 서버 도구는 버전이 지정된 공식 정의를 사용합니다.                                                                                                 |
| `tool_choice`                     | 객체                     | `auto`(기본값) 또는 `none`. `any`와 이름을 지정한 강제 `tool` 호출은 거부됩니다. `auto`에는 `disable_parallel_tool_use`를 포함할 수 있습니다.                                                                        |
| `metadata.user_id`                | 문자열 또는 null            | 최대 512자. 개인정보를 드러내지 않는 식별자를 사용하세요.                                                                                                                                                  |
| `cache_control`                   | 객체 또는 null             | `type: "ephemeral"`, `ttl: "5m"`(기본값) 또는 `"1h"`. Sonnet 5.5는 캐싱 가능한 토큰이 최소 512개 필요합니다. 공식 API는 블록 수준 캐시 분기점도 지원합니다.                                                                 |
| `diagnostics`                     | 객체 또는 null             | `previous_message_id`: 최대 256자의 문자열 또는 null. 캐시 불일치 진단을 요청합니다.                                                                                                                      |
| `service_tier`                    | 열거형                    | `auto`(기본값) 또는 `standard_only`.                                                                                                                                                     |
| `speed`                           | 열거형 또는 null            | 생략하거나 `standard` / null을 사용하세요. Sonnet 5.5는 `fast`를 지원하지 않습니다.                                                                                                                      |
| `inference_geo`                   | 문자열 또는 null            | 공식 기본값은 계정 설정을 따릅니다. 요청이 수락되었다는 사실만으로 처리 지역을 확인할 수는 없습니다.                                                                                                                           |
| `fallbacks`                       | 문자열, 객체 배열 또는 null, 베타 | `"default"` 또는 최대 3개의 대체 모델 항목. 각 항목에 `model`이 필요하며, 선택적으로 `max_tokens`, `thinking`, `output_config`, `speed`를 재정의할 수 있습니다. 대체 모델 규칙을 참고하세요.                                        |
| `fallback_credit_token`           | 문자열, 객체 또는 null        | 이전 응답 거부에서 받은 토큰 또는 `{"token":"...","mode":"strict"}`. 객체 형식에는 `fallback-credit-2026-07-01`이 필요합니다. mode는 `strict`(기본값) 또는 `best_effort`입니다. null이 아닌 `fallbacks`와 함께 사용할 수 없습니다.   |
| `container`                       | 문자열, 객체 또는 null        | 컨테이너 ID 또는 선택적 `id`와 `skills`(최대 20개)를 가진 컨테이너 설정. 스킬은 공식 유형, 식별자와 버전 필드를 사용합니다.                                                                                                    |
| `context_management`              | 객체 또는 null             | `edits`를 포함한 공식 컨텍스트 편집 설정. null이면 설정을 생략합니다. 모델별 편집 호환성은 그대로 적용됩니다.                                                                                                                |
| `mcp_servers`                     | 객체 배열                  | 공식 MCP 서버 정의. 필요한 베타 버전과 서버 인증 요건을 따라야 합니다. 빈 배열로 요청해 보는 것만으로 원격 MCP 실행을 검증할 수는 없습니다.                                                                                               |
| `compaction`                      | 객체 또는 null, 베타         | `{"type":"summarize"}`와 `compact-2026-09-04`를 사용합니다. null이면 압축을 생략합니다. 압축을 활성화하면 null이 아닌 `context_management`, 중단 문자열 또는 구조화된 출력 형식과 함께 사용할 수 없습니다. 서명된 압축 동작은 현재 테스트를 통과하지 못했습니다. |
| `messages[].output_config.effort` | 열거형, 베타                | 시스템 메시지별 사고 노력. `mid-conversation-output-config-2026-07-01`이 필요합니다. 사고 노력만 있는 시스템 메시지는 어디에나 배치할 수 있으며, 콘텐츠가 있는 시스템 메시지 그룹은 공식 배치 규칙을 따릅니다. `between_tools` 모드에서는 사고 노력을 변경하면 안 됩니다. |

## 사고 모드와 도구 [#사고-모드와-도구]

`between_tools`는 `type` 속성만 허용하며, 노력 수준은 `low`, `medium`, `high` 중 하나여야 합니다. `display`, `budget_tokens`, `block_binding`을 함께 전송하지 마세요. 예시는 다음과 같습니다.

```json
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "medium"},
  "messages": [{"role": "user", "content": "Explain this concept briefly."}]
}
```

어시스턴트 응답 미리 채우기는 지원하지 않습니다. `pause_turn`을 이어가려면 반환된 서버 도구의 어시스턴트 콘텐츠를 그대로 다시 전송하세요. 압축은 기존 기록을 요약하는 것으로, 어시스턴트 응답 미리 채우기와 다릅니다. 사고 블록과 서명을 정확히 보존하세요. 공식 바인딩 규칙을 따르지 않은 채 다른 모델로 옮기거나 이전 기록을 수정하면 안 됩니다.

네이티브 Claude API의 컴퓨터 사용에는 `computer_toolset_20260801`이 필요하며 `computer_20251124`는 거부됩니다. 이 실행 모델에서는 `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-5`를 사용하는 Advisor 설정도 거부됩니다.

## 미디어 입력 [#미디어-입력]

이미지와 PDF는 사용자 메시지의 `content` 블록에 공개적으로 접근 가능한 HTTP(S) URL로 지정하세요. 파일은 직접 호스팅해야 합니다. 이 연동은 Files API나 업로드 기능을 제공하지 않습니다. 이미지 입력 예시는 다음과 같습니다.

```json
{"role":"user","content":[
  {"type":"image","source":{"type":"url","url":"https://example.com/chart.png"}},
  {"type":"text","text":"What does this chart show?"}
]}
```

PDF에는 `document` 블록을 사용하세요. 대화를 이어갈 때는 도구 사용 ID, 전체 사고 블록과 서명을 그대로 유지하세요. 클라이언트 도구를 실행하고 결과를 반환하는 주체는 사용자 애플리케이션입니다. 도구를 선언하는 것만으로 실행되지는 않습니다.

## 요금 [#요금]

토큰 100만 개당 USD

현재 요금에는 각 그룹의 배율이 반영되어 있습니다. 요금은 최대 2분 동안 캐시됩니다.

하나의 API 키로 모든 모델과 그룹을 이용할 수 있습니다. 기본 표시는 자동 라우팅 순서에서 가장 먼저 이용 가능한 그룹을 뜻하며, 실제로 선택된 그룹의 요금이 적용됩니다.

### Claude Sonnet 5.5

`claude-sonnet-5-5`

| 과금 대상 토큰 | claude · 기본 · 모든 입력 길이 |
| --- | ---: |
| 입력(캐시되지 않음) | US$1 |
| 출력 | US$5 |
| 캐시 읽기 | US$0.05 |
| 캐시 쓰기 · 5분 | US$1.25 |
| 캐시 쓰기 · 1시간 | US$2 |

—는 확인된 요금이 없다는 뜻이며, 무료를 의미하지 않습니다.

캐시 요금은 응답에 해당 캐시 사용량이 보고된 경우에만 적용됩니다. 캐시된 토큰을 캐시되지 않은 입력으로 다시 계산하지 마세요.

각 과금 대상 토큰 수에 해당 단가를 곱하고, 합계를 1,000,000으로 나누세요. 사고 토큰은 출력 토큰에 포함되며 별도로 중복 과금되지 않습니다. 캐시 읽기, 5분 쓰기, 1시간 쓰기에는 각각 별도의 단가가 적용됩니다. 길이에 따른 요금은 먼저 해당 구간을 선택한 뒤 요청 비용을 계산하세요.

## 응답과 스트리밍 [#응답과-스트리밍]

완료된 메시지에는 `id`, `type`, `role`, `model`, `content`, `stop_reason`, `usage`가 포함됩니다. `content`에서 텍스트 블록을 읽으세요. 첫 번째 블록은 텍스트가 아닌 사고 또는 도구 호출일 수 있습니다. 아래 응답은 예시입니다.

```json
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [{"type": "text", "text": "A database index helps locate rows without scanning the whole table."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 24, "output_tokens": 18}
}
```

SSE를 받으려면 `stream: true`를 설정하고 `curl -N`을 사용하세요. `message_start`, `content_block_start`, `content_block_delta`, `content_block_stop`, `message_delta`, `message_stop` 외에 `ping`과 스트림 오류도 처리해야 합니다. 각 청크를 완성된 응답으로 취급하지 말고 최종 사용량을 읽으세요.

## OpenAI 호환 형식 [#openai-호환-형식]

동일한 모델 ID를 `POST /v1/chat/completions`와 `POST /v1/responses`에서도 사용할 수 있습니다. `Authorization: Bearer YOUR_API_KEY`와 OpenAI SDK 기본 URL `https://api.wanapi.app/v1`을 사용하세요. Chat Completions는 `messages`를, Responses는 `input`을 사용합니다. 이들 필드는 Messages 형식으로 변환되므로, 위에 설명한 네이티브 매개변수는 `/v1/messages`를 사용하세요.

```bash
curl https://api.wanapi.app/v1/chat/completions \
  -H "Authorization: Bearer $WAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":256,"messages":[{"role":"user","content":"Reply with OK."}]}'
```

## 사용 로그와 오류 [#사용-로그와-오류]

[LLM 로그](/ko/usage)에서 최근 7일 동안 완료된 호출의 모델, 입력 토큰, 출력 토큰과 비용을 확인할 수 있습니다. 호출 후 새로고침하고 `claude-sonnet-5-5`로 필터링하세요. 이미지와 동영상은 [작업 로그](/ko/tasks)에서 확인합니다.

요청이 실패하면 HTTP 상태 코드와 `error` 객체를 확인하세요. 키, [잔액](/ko/docs/balance), 모델 ID와 지원되는 매개변수 조합을 점검하세요. 응답 거부나 출력 한도에 따른 중단은 HTTP 오류와 다릅니다. 요청이나 스트림이 중단되었다면 재시도 전에 로그를 확인하세요. 새 요청에는 추가 비용이 발생할 수 있습니다.

## 모델 참고 문서 [#모델-참고-문서]

* [공식 Sonnet 5.5 개요](https://platform.claude.com/docs/en/models/sonnet-5-5/overview)
* [Sonnet 5.5 변경 사항과 제한](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5)
* [Messages 매개변수 참조 문서](https://platform.claude.com/docs/en/api/messages/create)
* [메시지별 사고 노력](https://platform.claude.com/docs/en/build-with-claude/effort)
* [요청 시 압축](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand)
* [응답 거부와 대체 모델](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback)
* [대체 모델 크레딧](https://platform.claude.com/docs/en/build-with-claude/fallback-credit)
