> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude 네이티브 형식

> Claude 네이티브 메시지 API

## 소개

Claude의 네이티브 메시지 API로, Claude Code와 같은 Anthropic 네이티브 클라이언트에 적합합니다. 이 API는 Anthropic 사양을 따르며 Extended Thinking, 도구 호출 등 Claude 모델의 전체 기능을 제공합니다.

<Note>
  OpenAI 호환 클라이언트(예: OpenAI SDK)를 사용하는 경우 [`/v1/chat/completions`](/ko/api-reference/endpoint/chat-openai) 엔드포인트 사용을 권장합니다.
</Note>

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer 토큰, 예: `Bearer sk-xxxxxxxxxx`
</ParamField>

## 요청 매개변수

<ParamField body="model" type="string" required>
  Claude 모델 식별자. 지원 모델:

  * `claude-opus-4-8` - Claude Opus 4.8 (최신, 가장 강력한 추론)
  * `claude-opus-4-7` - Claude Opus 4.7
  * `claude-opus-4-6` - Claude Opus 4.6
  * `claude-sonnet-4-6` - Claude Sonnet 4.6 (최신, 균형 잡힌 성능)
  * `claude-opus-4-5-20251101` - Claude Opus 4.5
  * `claude-haiku-4-5-20251001` - Claude Haiku 4.5 (최신, 가장 빠름)
  * `claude-sonnet-4-5-20250929` - Claude Sonnet 4.5
  * `claude-opus-4-1-20250805` - Claude Opus 4.1
  * `claude-sonnet-4-20250514` - Claude Sonnet 4
  * 기타 Claude 시리즈 모델
</ParamField>

<ParamField body="messages" type="array" required>
  대화 메시지 목록. 각 항목은 `role`(user/assistant)과 `content`를 포함합니다. `content`는 문자열 또는 미디어 콘텐츠 배열일 수 있습니다.
</ParamField>

<ParamField body="max_tokens" type="number" required>
  생성할 최대 토큰 수. 0보다 커야 합니다.
</ParamField>

<ParamField body="system" type="string|array">
  시스템 프롬프트. 문자열 또는 미디어 콘텐츠 배열로 지정할 수 있습니다. 모델의 동작과 역할을 설정하는 데 사용됩니다.
</ParamField>

<ParamField body="temperature" type="number" default="1.0">
  무작위성 제어, 0-1. 값이 높을수록 응답이 더 무작위적입니다. 확장 사고 사용 시 1.0으로 설정하는 것을 권장합니다.
</ParamField>

<ParamField body="top_p" type="number" default="1.0">
  Nucleus 샘플링 매개변수, 0-1. 생성 다양성을 제어합니다. 확장 사고 사용 시 0으로 설정하는 것을 권장합니다.
</ParamField>

<ParamField body="top_k" type="number">
  Top-K 샘플링 매개변수. 일부 모델에서만 지원됩니다.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  스트리밍 출력 활성화 여부. SSE 형식의 데이터 청크를 반환합니다. 확장 사고 사용 시 활성화를 권장합니다.
</ParamField>

<ParamField body="stop_sequences" type="array">
  중지 시퀀스 목록. 모델이 이 시퀀스를 생성하면 생성이 중단됩니다.
</ParamField>

<ParamField body="tools" type="array">
  도구 정의 목록. 함수 도구와 웹 검색 도구를 지원합니다.
</ParamField>

<ParamField body="tool_choice" type="object">
  도구 선택 전략. 모델이 도구를 사용하는 방식을 제어합니다.
</ParamField>

<ParamField body="thinking" type="object">
  확장 사고 설정. Claude의 심층 추론 기능을 활성화합니다.
</ParamField>

<ParamField body="metadata" type="object">
  추적 및 디버깅용 요청 메타데이터.
</ParamField>

<ParamField body="mcp_servers" type="array">
  MCP(Model Context Protocol) 서버 설정.
</ParamField>

<ParamField body="context_management" type="object">
  컨텍스트 관리 설정. 대화 컨텍스트 처리 방식을 제어합니다.
</ParamField>

## 프롬프트 캐싱

프롬프트 캐싱을 사용하면 자주 사용하는 컨텍스트 콘텐츠를 캐시하여 비용을 크게 절감하고 응답 속도를 향상시킬 수 있습니다. `system`과 `messages`에서 `cache_control` 매개변수를 사용할 수 있습니다.

### 캐시 제어 매개변수

<ParamField body="cache_control" type="object">
  캐시 제어 설정. `system` 배열 요소와 `messages`의 `content` 배열 요소에서 사용할 수 있습니다.

  * `type`: 캐시 유형
    * `"ephemeral"`: 5분 캐시 (기본값, 가장 비용 효율적)
    * `"persistent"`: 1시간 캐시 (장기적으로 안정적인 컨텍스트에 적합)
</ParamField>

### 캐싱 메커니즘

* **캐시 위치**: `cache_control`이 지정된 마지막 콘텐츠 블록이 캐시됩니다
* **캐시 임계값**: 콘텐츠는 최소 **1024 토큰**(Claude Sonnet 4.5) 또는 **2048 토큰**(Claude 3 Haiku) 이상이어야 합니다
* **캐시 유효 기간**:
  * `ephemeral`: 5분간 유효
  * `persistent`: 1시간 유효
* **비용 절감**: 캐시 읽기는 일반 입력보다 **90% 저렴**합니다

### 사용 사례

1. **긴 문서 분석**: `system`에 대용량 문서를 캐시하고 여러 질문 수행
2. **코드베이스 이해**: 코드 컨텍스트를 캐시하여 다중 턴 코드 분석
3. **지식 베이스 Q\&A**: 지식 베이스 콘텐츠를 캐시하여 빠른 조회
4. **다중 턴 대화**: 대화 기록을 캐시하여 컨텍스트 일관성 유지

## 기본 예제

<Tabs>
  <Tab title="비스트리밍 요청">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "messages": [
          {"role": "user", "content": "Please briefly introduce artificial intelligence"}
        ]
      }'
    ```
  </Tab>

  <Tab title="스트리밍 요청 (SSE)">
    ```bash theme={null}
    curl -N -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "stream": true,
        "messages": [
          {"role": "user", "content": "Please briefly introduce artificial intelligence"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Python 예제 (Anthropic SDK)">
    ```python theme={null}
    from anthropic import Anthropic

    client = Anthropic(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai"
    )

    # Non-streaming
    message = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "Please briefly introduce artificial intelligence"}
        ]
    )
    print(message.content[0].text)

    # Streaming
    with client.messages.stream(
        model="claude-sonnet-4-5-20250929",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "Please briefly introduce artificial intelligence"}
        ]
    ) as stream:
        for text_block in stream.text_stream:
            print(text_block, end="")
    ```
  </Tab>
</Tabs>

<ResponseExample>
  ```json theme={null}
  {
    "id": "msg_xxx",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Artificial intelligence is a branch of computer science that focuses on creating intelligent machines capable of performing tasks that typically require human intelligence..."
      }
    ],
    "model": "claude-sonnet-4-5-20250929",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 25,
      "output_tokens": 100
    }
  }
  ```
</ResponseExample>

## 고급 기능

### 시스템 프롬프트

시스템 프롬프트는 문자열 또는 미디어 콘텐츠 배열로 설정할 수 있습니다:

<Tabs>
  <Tab title="문자열 형식">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "system": "You are a helpful assistant that excels at answering questions.",
        "messages": [
          {"role": "user", "content": "What is machine learning?"}
        ]
      }'
    ```
  </Tab>

  <Tab title="배열 형식">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "system": [
          {"type": "text", "text": "You are a helpful assistant that excels at answering questions."}
        ],
        "messages": [
          {"role": "user", "content": "What is machine learning?"}
        ]
      }'
    ```
  </Tab>
</Tabs>

### 확장 사고

Claude는 확장 사고를 지원하여 모델이 심층 추론을 수행할 수 있습니다. 활성화하면 모델이 최종 답변을 생성하기 전에 내부적으로 사고합니다.

<Tabs>
  <Tab title="기본 사용법">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 4096,
        "temperature": 1.0,
        "top_p": 0,
        "stream": true,
        "messages": [
          {"role": "user", "content": "Give a medium difficulty geometry problem and solve it step by step"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Python 예제">
    ```python theme={null}
    from anthropic import Anthropic

    client = Anthropic(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai"
    )

    with client.messages.stream(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4096,
        thinking={
            "type": "enabled",
            "budget_tokens": 4096
        },
        temperature=1.0,
        top_p=0,
        messages=[
            {"role": "user", "content": "Give a medium difficulty geometry problem and solve it step by step"}
        ]
    ) as stream:
        for event in stream:
            if event.type == "content_block_delta":
                if hasattr(event.delta, "thinking"):
                    # Thinking process
                    print(f"[Thinking] {event.delta.thinking}", end="")
                elif hasattr(event.delta, "text"):
                    # Final answer
                    print(event.delta.text, end="")
    ```
  </Tab>
</Tabs>

<Note>
  * `budget_tokens`는 1024보다 커야 합니다
  * 확장 사고 사용 시 `temperature: 1.0`, `top_p: 0` 설정을 권장합니다
  * 사고 과정을 보려면 스트리밍 출력(`stream: true`)을 활성화해야 합니다
</Note>

### 도구 호출

함수 도구와 웹 검색 도구를 지원합니다:

<Tabs>
  <Tab title="함수 도구">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "tools": [
          {
            "name": "get_weather",
            "description": "Get weather information for a city",
            "input_schema": {
              "type": "object",
              "properties": {
                "city": {
                  "type": "string",
                  "description": "City name"
                }
              },
              "required": ["city"]
            }
          }
        ],
        "tool_choice": {
          "type": "auto"
        },
        "messages": [
          {"role": "user", "content": "What is the weather in Shanghai?"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Claude 공식 웹 검색 도구">
    Claude는 공식 웹 검색 도구 `web_search_20250305`를 지원하며, 실시간으로 웹을 검색하고 응답에 인용 출처를 포함할 수 있습니다.

    <Note>참고: AWS Bedrock은 이 검색 도구를 지원하지 않습니다</Note>

    **기본 사용법**:

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "tools": [
          {
            "type": "web_search_20250305",
            "name": "web_search"
          }
        ],
        "messages": [
          {"role": "user", "content": "What are the latest news about artificial intelligence?"}
        ]
      }'
    ```

    **검색 횟수 제한**:

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "tools": [
          {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
          }
        ],
        "messages": [
          {"role": "user", "content": "Search for today'\''s weather in Beijing"}
        ]
      }'
    ```

    **위치 정보 포함 (검색 정확도 향상)**:

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "tools": [
          {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
            "user_location": {
              "type": "approximate",
              "timezone": "Asia/Shanghai",
              "country": "CN",
              "region": "Beijing",
              "city": "Beijing"
            }
          }
        ],
        "messages": [
          {"role": "user", "content": "What'\''s the weather in Shanghai today?"}
        ]
      }'
    ```

    **Python 예제**:

    ```python theme={null}
    from anthropic import Anthropic

    client = Anthropic(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai"
    )

    message = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=1024,
        tools=[
            {
                "type": "web_search_20250305",
                "name": "web_search",
                "max_uses": 5
            }
        ],
        messages=[
            {"role": "user", "content": "What are the latest news about artificial intelligence?"}
        ]
    )
    print(message.content[0].text)
    ```

    <Note>
      * `type`은 `"web_search_20250305"`여야 합니다
      * `name`은 `"web_search"`여야 합니다
      * `max_uses` (선택): 단일 대화에서 최대 검색 횟수, 권장값: 2-10
      * `user_location` (선택): 검색 결과의 지역화 정확도를 높이는 사용자 위치 정보
      * 검색 결과는 응답에 인용 출처가 자동으로 포함됩니다
      * Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 등 지원 모델 포함
    </Note>
  </Tab>

  <Tab title="전체 도구 호출 흐름">
    1단계: 모델이 도구 호출 요청 반환

    ```json theme={null}
    {
      "id": "msg_xxx",
      "content": [
        {
          "type": "tool_use",
          "id": "toolu_xxx",
          "name": "get_weather",
          "input": {"city": "Shanghai"}
        }
      ],
      "stop_reason": "tool_use"
    }
    ```

    2단계: 도구 실행 결과 반환

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "tools": [...],
        "messages": [
          {"role": "user", "content": "What is the weather in Shanghai?"},
          {
            "role": "assistant",
            "content": [
              {
                "type": "tool_use",
                "id": "toolu_xxx",
                "name": "get_weather",
                "input": {"city": "Shanghai"}
              }
            ]
          },
          {
            "role": "user",
            "content": [
              {
                "type": "tool_result",
                "tool_use_id": "toolu_xxx",
                "content": "{\"temp\":\"22°C\",\"condition\":\"Cloudy\",\"aqi\":53}"
              }
            ]
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

### tool\_choice 매개변수 상세

`tool_choice`는 모델이 도구를 사용하는 방식을 제어합니다:

| 값                                       | 설명                    |
| --------------------------------------- | --------------------- |
| `{"type": "auto"}`                      | 도구 사용 여부를 자동 결정 (기본값) |
| `{"type": "any"}`                       | 최소 하나의 도구를 반드시 사용     |
| `{"type": "none"}`                      | 도구를 사용하지 않음           |
| `{"type": "tool", "name": "tool_name"}` | 지정된 도구를 반드시 사용        |

예제:

```json theme={null}
{
  "tool_choice": {
    "type": "auto",
    "disable_parallel_tool_use": false
  }
}
```

### 멀티모달 입력 (이미지)

메시지에 이미지를 포함할 수 있습니다:

```bash theme={null}
curl -X POST "https://api.gravitex.ai/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
            }
          },
          {
            "type": "text",
            "text": "What is in this image?"
          }
        ]
      }
    ]
  }'
```

### 프롬프트 캐싱

자주 사용하는 컨텍스트 콘텐츠를 캐시하면 비용을 크게 절감하고 응답 속도를 향상시킬 수 있습니다.

<Tabs>
  <Tab title="시스템 캐시 (5분)">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "system": [
          {
            "type": "text",
            "text": "You are a professional technical documentation analyst. Here is the complete AWS Lambda technical documentation:\n\nAWS Lambda is a serverless computing service...[large documentation content, at least 1024 tokens]",
            "cache_control": {"type": "ephemeral"}
          }
        ],
        "messages": [
          {"role": "user", "content": "What is Lambda's pricing model?"}
        ]
      }'
    ```

    **첫 번째 요청 응답**:

    ```json theme={null}
    {
      "usage": {
        "input_tokens": 50,
        "cache_creation_input_tokens": 1200,
        "cache_read_input_tokens": 0,
        "output_tokens": 150
      }
    }
    ```

    **5분 이내 두 번째 요청 (다른 질문, 동일 system)**:

    ```json theme={null}
    {
      "usage": {
        "input_tokens": 45,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 1200,
        "output_tokens": 100
      }
    }
    ```
  </Tab>

  <Tab title="메시지 캐시 (1시간)">
    ````bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 1024,
        "system": "You are a Python programming assistant",
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "Analyze this code:\n```python\n[large code snippet, at least 1024 tokens]\n```",
                "cache_control": {"type": "persistent"}
              }
            ]
          },
          {
            "role": "assistant",
            "content": [
              {
                "type": "text",
                "text": "The main functionality of this code is...[detailed analysis]",
                "cache_control": {"type": "persistent"}
              }
            ]
          },
          {
            "role": "user",
            "content": "How can I optimize the performance of this code?"
          }
        ]
      }'
    ````

    **persistent 캐시의 장점**:

    * 1시간 캐시 유효 기간, 긴 세션에 적합
    * 코드 리뷰, 문서 분석 등에 이상적
    * 캐시 히트 후 후속 요청이 더 빠름
  </Tab>

  <Tab title="Python SDK 예제">
    ```python theme={null}
    from anthropic import Anthropic

    client = Anthropic(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai"
    )

    # First request: Create cache
    message1 = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": "You are a professional document analyst...[long text content]",
                "cache_control": {"type": "ephemeral"}
            }
        ],
        messages=[
            {"role": "user", "content": "First question"}
        ]
    )

    print(f"Cache created: {message1.usage.cache_creation_input_tokens} tokens")
    print(f"Cache read: {message1.usage.cache_read_input_tokens} tokens")

    # Second request within 5 minutes: Use cache
    message2 = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": "You are a professional document analyst...[same long text]",
                "cache_control": {"type": "ephemeral"}
            }
        ],
        messages=[
            {"role": "user", "content": "Second question"}
        ]
    )

    print(f"Cache created: {message2.usage.cache_creation_input_tokens} tokens")
    print(f"Cache read: {message2.usage.cache_read_input_tokens} tokens")
    ```
  </Tab>
</Tabs>

<Note>
  **캐시 핵심 사항**:

  * 콘텐츠는 캐싱을 트리거하려면 **≥ 1024 토큰**(Claude Sonnet 4.5) 이상이어야 합니다
  * `ephemeral` 캐시는 **5분**간 유효합니다
  * `persistent` 캐시는 **1시간** 유효합니다
  * 캐시 읽기 비용은 일반 입력보다 **90% 저렴**합니다
  * `cache_control`이 지정된 마지막 블록이 캐시됩니다
  * 캐시는 정확한 콘텐츠 일치를 기반으로 하며, 변경 시 캐시가 무효화됩니다
</Note>

<Tip>
  **모범 사례**:

  * 변경되지 않는 긴 컨텍스트(문서, 코드베이스 등)를 `system`에 캐싱 활성화와 함께 배치
  * 장기적으로 안정적인 콘텐츠에는 `persistent` 캐시(1시간) 사용
  * 자주 변경되는 콘텐츠에는 `ephemeral` 캐시(5분) 사용
  * 다중 턴 대화에서 대화 기록 캐시
  * `cache_creation_input_tokens`와 `cache_read_input_tokens`를 모니터링하여 비용 최적화
</Tip>

## 응답 형식

<Tabs>
  <Tab title="비스트리밍 응답">
    ```json theme={null}
    {
      "id": "msg_xxx",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "Response content..."
        }
      ],
      "model": "claude-sonnet-4-5-20250929",
      "stop_reason": "end_turn",
      "stop_sequence": null,
      "usage": {
        "input_tokens": 25,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "output_tokens": 100
      }
    }
    ```

    **캐시 사용 시 usage 필드**:

    * `input_tokens`: 현재 요청의 비캐시 입력 토큰
    * `cache_creation_input_tokens`: 최초 캐시된 토큰 (첫 요청에만 존재)
    * `cache_read_input_tokens`: 캐시에서 읽은 토큰 (캐시 히트 시 존재)
    * `output_tokens`: 생성된 출력 토큰
  </Tab>

  <Tab title="스트리밍 응답">
    스트리밍 응답은 SSE(Server-Sent Events) 형식으로 반환되며, 다음 이벤트 유형을 포함합니다:

    * `message_start`: 메시지 시작
    * `content_block_start`: 콘텐츠 블록 시작
    * `content_block_delta`: 콘텐츠 델타 (`text` 또는 `thinking` 포함)
    * `content_block_stop`: 콘텐츠 블록 종료
    * `message_delta`: 메시지 델타 (usage 정보 포함)
    * `message_stop`: 메시지 종료

    ```json theme={null}
    event: message_start
    data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-5-20250929","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":25,"output_tokens":0}}}

    event: content_block_start
    data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

    event: content_block_delta
    data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Response"}}

    event: content_block_delta
    data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" content"}}

    event: content_block_stop
    data: {"type":"content_block_stop","index":0}

    event: message_delta
    data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":100}}

    event: message_stop
    data: {"type":"message_stop"}
    ```

    확장 사고 사용 시 `content_block_delta`에 `thinking` 필드가 포함될 수 있습니다:

    ```json theme={null}
    event: content_block_delta
    data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"Let me think about this problem..."}}
    ```
  </Tab>
</Tabs>

## 오류 처리

시스템은 업스트림 Claude API 오류를 처리하고 표준화된 오류 응답 형식을 반환합니다.

| 오류 유형                  | HTTP 상태 코드 | 설명                       |
| ---------------------- | ---------- | ------------------------ |
| `invalid_request`      | 400        | 요청 매개변수 오류 (예: 필수 필드 누락) |
| `authentication_error` | 401        | 유효하지 않거나 권한 없는 API 키     |
| `rate_limit_error`     | 429        | 요청 속도 제한 초과              |
| `upstream_error`       | 500        | 업스트림 서비스 오류              |
| `gravitex_api_error`   | 500        | 시스템 내부 오류                |

오류 응답 예제:

```json theme={null}
{
  "error": {
    "type": "invalid_request",
    "message": "field messages is required"
  }
}
```

## /v1/chat/completions와 비교

| 기능        | /v1/messages                 | /v1/chat/completions                   |
| --------- | ---------------------------- | -------------------------------------- |
| 인증        | `Authorization: Bearer`      | `Authorization: Bearer`                |
| 응답 형식     | Anthropic 네이티브 형식            | OpenAI 호환 형식                           |
| 확장 사고     | 네이티브 `thinking` 매개변수         | `reasoning_effort` 또는 `reasoning` 매개변수 |
| 도구 호출     | 네이티브 `tools` 및 `tool_choice` | OpenAI 호환 형식                           |
| 적합한 클라이언트 | Anthropic SDK, Claude Code   | OpenAI SDK, 호환 클라이언트                   |

<Tip>
  * Claude Code 또는 기타 Anthropic 네이티브 클라이언트를 사용하는 경우 `/v1/messages` 엔드포인트 사용을 권장합니다
  * OpenAI SDK를 사용하거나 OpenAI 형식 호환이 필요한 경우 `/v1/chat/completions` 엔드포인트 사용을 권장합니다
  * 두 엔드포인트의 기능은 본질적으로 동일하며, 주요 차이는 요청/응답 형식에 있습니다
</Tip>

## 참고 사항

<Note>
  * `max_tokens`는 필수 매개변수이며 0보다 커야 합니다
  * `messages` 배열은 비어 있을 수 없습니다
  * 확장 사고 사용 시 `budget_tokens`는 1024보다 커야 합니다
  * 확장 사고는 사고 과정을 보려면 스트리밍 출력이 필요합니다
  * 도구 호출은 여러 라운드의 상호작용이 필요합니다: 1라운드에서 도구 호출 요청 반환, 2라운드에서 도구 실행 결과 반환
  * 이미지 입력은 base64 인코딩이 필요합니다
</Note>

<Tip>
  * 스트리밍 출력을 사용하면 첫 토큰 응답 시간과 상호작용 경험을 개선할 수 있습니다
  * 도구 호출에는 모델 응답 차단을 방지하기 위한 적절한 타임아웃 및 재시도 메커니즘이 있어야 합니다
  * 확장 사고는 복잡한 문제에 대한 추론 품질을 크게 향상시킬 수 있습니다
</Tip>

## 관련 리소스

<Columns cols={2}>
  <Card title="Chat Completions (OpenAI 호환)" icon="message" href="/ko/api-reference/endpoint/chat-openai">
    OpenAI 호환 채팅 엔드포인트 문서 보기
  </Card>

  <Card title="모델 목록" icon="list" href="/ko/api-reference/models">
    지원되는 모든 모델 정보 보기
  </Card>
</Columns>