---
title: "Messages 네이티브 대화 인터페이스"
description: "Claude Messages의 요청 헤더, system과 messages의 차이, 콘텐츠 블록 및 종료 원인."
headingIds: {"최소 요청":"section-1","요청 구조":"section-2","콘텐츠 블록 읽기":"section-3","다중 라운드 및 스트리밍":"section-4"}
---

<aside className="docs-publication" data-pagefind-ignore>

[1ZheAI](https://1zheai.com/en/editorial/#publisher)가 관리하는 문서입니다. [출처 및 수정 사항](https://1zheai.com/en/editorial/).

오류를 발견하셨나요? 페이지 주소와 설명을 첨부하여 [고객 지원](mailto:support@1zheai.com)으로 문의해 주세요. API 키나 계정 정보는 보내지 마세요.

</aside>
Claude Code, Anthropic SDK, 그리고 Claude 네이티브 콘텐츠 블록을 유지하려는 애플리케이션은 `POST https://1zheai.com/v1/messages`을 사용합니다. SDK Base URL에는 `https://1zheai.com`을 입력합니다.

## 최소 요청

먼저 사이트 키 환경 변수 `ONEZHE_API_KEY`를 설정한 다음 실행합니다:

```bash
curl --fail-with-body --connect-timeout 10 --max-time 120 \
  https://1zheai.com/v1/messages \
  -H "x-api-key: $ONEZHE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 256,
    "system": "请用简短的中文回答。",
    "messages": [{"role": "user", "content": "什么是域名解析？"}]
  }'
```

## 요청 구조

| 필드 | 타입 | 사용 방식 |
| --- | --- | --- |
| `model` | string | 필수, 키에서 사용 가능한 Claude 모델 선택 |
| `max_tokens` | integer | 필수, 출력 상한; 선택한 모델의 제한 설정과 함께 사용 |
| `messages` | array | 필수, 시간순으로 `user` 및 `assistant` 메시지 전송 |
| `system` | string 또는 콘텐츠 블록 배열 | 선택, 시스템 지시는 최상위에 두고 `role: system` 메시지는 사용하지 않음 |
| `stream` | boolean | 선택, 콘텐츠 블록 증분을 스트리밍으로 읽기 |
| `tools` | array | 선택, 도구 이름, 용도 및 입력 스키마 선언 |

`thinking`, 캐시 제어 및 beta 파라미터는 특정 모델과 업스트림 지원에 따라 다릅니다. 먼저 일반 텍스트를 검증한 다음 필요에 따라 추가하세요. 모든 모델을 동일한 파라미터 세트로 취급하지 마세요.

## 콘텐츠 블록 읽기

반환되는 `content`은 배열이며, 텍스트, 도구 요청 또는 기타 콘텐츠 블록을 동시에 포함할 수 있습니다. 조건 없이 `content[0].text`을 읽지 마세요. 예를 들어 Anthropic Python SDK 사용 시:

```python
for block in message.content:
    if block.type == "text":
        print(block.text)
```

여기서 `message`은 [Anthropic SDK 튜토리얼](/ko/docs/quickstart-anthropic-sdk/)의 `client.messages.create(...)`에서 가져왔습니다.

| `stop_reason` | 애플리케이션 처리 방식 |
| --- | --- |
| `end_turn` | 이번 라운드 답변 종료 |
| `max_tokens` | 출력이 상한으로 잘려 완전한 답변으로 볼 수 없음 |
| `tool_use` | 도구 요청을 확인하고 허용된 도구를 실행한 뒤 결과 반환 |
| 기타 값 | 응답을 보존하고 선택한 모델의 프로토콜에 따라 처리하며 반드시 텍스트 완료라고 가정하지 않음 |

도구 호출 루프에서는 먼저 완전한 assistant 콘텐츠 블록을 히스토리에 추가한 다음 user 콘텐츠의 `tool_result`로 반환하며, `tool_use_id`는 원래 요청에 대응해야 합니다. 도구 요청을 일반 텍스트 한 덩어리로 직접 변환하지 마세요.

## 다중 라운드 및 스트리밍

매번 보존할 히스토리를 함께 전송하세요. 인터페이스 자체는 애플리케이션을 대신해 대화를 저장하지 않습니다. 스트리밍은 `message_stop`으로 메시지 종료를 나타내며, 부분 텍스트를 받았다고 해서 요청이 이미 완료된 것은 아닙니다. 자세한 내용은 [스트리밍 출력](/ko/docs/streaming/)을 참조하세요.

프로토콜 세부 사항은 [Anthropic Messages 사용 안내](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)을 참고하세요. 사이트 확장 파라미터의 사용 가능 여부는 모델 카탈로그와 실제 응답을 따릅니다.