Messages 네이티브 대화 인터페이스

1ZheAI가 관리하는 문서입니다. 출처 및 수정 사항.

오류를 발견하셨나요? 페이지 주소와 설명을 첨부하여 고객 지원으로 문의해 주세요. API 키나 계정 정보는 보내지 마세요.

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 튜토리얼의 client.messages.create(...)에서 가져왔습니다.

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

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

다중 라운드 및 스트리밍

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

프로토콜 세부 사항은 Anthropic Messages 사용 안내을 참고하세요. 사이트 확장 파라미터의 사용 가능 여부는 모델 카탈로그와 실제 응답을 따릅니다.