Claude Messages API 신청 및 사용

Anthropic Claude는 매우 강력한 AI 대화 시스템으로, 프롬프트를 입력하기만 하면 단 몇 초 만에 유창하고 자연스러운 응답을 생성할 수 있습니다. Claude Messages API는 Anthropic의 공식 네이티브 API 형식으로, OpenAI 호환 형식(Chat Completion)과 달리 Anthropic 고유의 요청 및 응답 구조를 사용하며, 멀티모달 콘텐츠 입력, 도구 호출, 심층 사고(Extended Thinking) 등의 고급 기능과 같은 Claude의 고유한 능력을 더 잘 활용할 수 있습니다. 이 문서는 주로 Claude Messages API 작업의 사용 절차를 소개하며, 이를 통해 Anthropic 공식과 일치하는 네이티브 인터페이스를 사용하여 Claude의 대화 기능을 호출할 수 있습니다.

신청 절차

Claude Messages API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 예비용으로 보관하세요.

아직 로그인하거나 가입하지 않았다면 로그인 페이지로 자동 이동하여 가입 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 반환됩니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스별로 별도 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 콘솔에서 공용 잔액을 충전할 수 있습니다.

📘 전체 문서: Claude Messages API →

기본 사용

Claude Messages API의 요청 경로는 /v1/messages이며, Anthropic 공식 API와 일치합니다. 최소한 다음 세 가지 필수 파라미터를 제공해야 합니다.

model: 사용할 Claude 모델을 선택합니다. claude-opus-5-5는 Messages API를 통해서만 제공되며, 100만 Token 컨텍스트, 최대 출력 128K Token을 지원하고 항상 적응형 사고를 활성화합니다. 최신 플래그십은 claude-fable-5-1(100만 Token 컨텍스트, 최대 출력 128K Token)이며, 기존 claude-fable-5도 계속 호환 유지됩니다. claude-sonnet-5-5는 네이티브 Messages 시리즈 인터페이스에 추가되었으며, 이미지 입력과 적응형 사고를 지원합니다. 입력, 출력 및 캐시 읽기의 공식 기준 가격은 각각 100만 Token당 2, 10 및 0.20달러입니다.
messages: 입력 메시지 배열로, 각 메시지는 role(역할)과 content(내용)를 포함하며, role은 user와 assistant를 지원합니다.
max_tokens: 최대 출력 token 수로, 단일 응답의 길이를 제한하는 데 사용됩니다.

자주 사용하는 선택적 파라미터:

system: 모델의 동작과 역할을 설정하는 시스템 프롬프트입니다.
temperature: 생성 무작위성으로, 0-1 사이이며 값이 클수록 응답이 더 분산됩니다.
stream: 스트리밍 응답 사용 여부로, true로 설정하면 글자 단위 반환 효과를 구현할 수 있습니다.
stop_sequences: 사용자 정의 중지 시퀀스로, 모델은 이러한 텍스트를 만나면 생성을 중지합니다.
top_p: 핵 샘플링 파라미터로, temperature와 함께 생성의 무작위성을 제어합니다.
top_k: 확률이 가장 높은 K개 선택지에서만 샘플링합니다.
tools: 모델이 외부 함수를 호출하도록 하는 도구 정의입니다.
tool_choice: 모델이 제공된 도구를 사용하는 방식을 제어합니다.
cache_control: 요청의 마지막 캐시 가능한 콘텐츠 블록에서 자동으로 캐시 중단점을 생성하며, 구체적인 콘텐츠 블록에 작성할 수도 있습니다.

cURL 예시

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

Python 예시

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

호출 후 반환 결과는 다음과 같습니다:

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

반환 결과 필드 설명:

id: 이번 메시지의 고유 식별자입니다.
type: 항상 message입니다.
role: 항상 assistant입니다.
content: 응답 내용 배열이며, 각 요소는 type(예: text) 및 해당 내용을 포함합니다.
model: 요청을 처리한 모델 이름입니다.
stop_reason: 중지 사유입니다. 안정적인 값에는 end_turn, max_tokens, stop_sequence, tool_use, pause_turn(계속하려면 현재 assistant 내용을 원본 그대로 다시 전달 가능), refusal 및 model_context_window_exceeded가 포함됩니다.
stop_sequence: 사용자 정의 중지 시퀀스로 인해 중지된 경우, 일치하는 중지 시퀀스 텍스트를 표시합니다.
stop_details: stop_reason이 refusal인 경우, 거부 카테고리와 설명을 포함할 수 있습니다.
usage: token 사용 통계입니다. input_tokens는 캐시되지 않은 입력이며, cache_creation_input_tokens와 cache_read_input_tokens는 각각 캐시 쓰기 및 읽기입니다. output_tokens는 전체 출력 token 수입니다. output_tokens_details.thinking_tokens가 반환되는 경우 이 값은 output_tokens의 부분집합이므로, 총량 또는 비용을 계산할 때 다시 더하지 마세요. 이 세부 정보는 권위 있는 집계가 없을 경우 null이거나 생략될 수 있습니다.
usage.cache_creation: 선택적인 캐시 쓰기 TTL 세부 정보로, ephemeral_5m_input_tokens 및 ephemeral_1h_input_tokens를 포함합니다. 객체가 존재할 경우 두 항목의 합은 cache_creation_input_tokens와 같으며, 필드가 null이거나 생략된 경우 현재 응답에 사용 가능한 TTL 분할이 없음을 의미하므로 0으로 해석할 수 없습니다.
usage.cost: 비스트리밍 응답에는 Ace Data Cloud가 기록한 크레딧 소모 객체가 포함될 수 있으며, amount는 이번 실제 소모량, currency는 계량 단위, list_amount는 할인 전 금액(있는 경우)입니다. Fable 5.1의 공식 캐시 읽기 기준 가격은 100만 Token당 $0.25이며, 5분 및 1시간 캐시 쓰기 기준 가격은 각각 $12.50 및 $20/100만 Token입니다. 플랫폼 실제 가격은 요금제 할인에 따라 환산됩니다.

시스템 프롬프트

Claude Messages API는 system 필드를 통해 시스템 프롬프트를 설정할 수 있으며, 모델의 동작, 역할 및 컨텍스트를 정의하는 데 사용됩니다.

Python 예시

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "당신은 전문적인 중국어 번역 도우미입니다. 사용자가 입력한 영어를 중국어로 번역해 주세요.",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

system 프롬프트를 설정하면 Claude의 역할과 행동 방식을 정밀하게 제어할 수 있습니다.

스트리밍 응답

이 인터페이스는 스트리밍 응답도 지원합니다. stream 매개변수를 true로 설정하면 점진적으로 반환되는 효과를 얻을 수 있으며, 웹 페이지에서 한 글자씩 표시하는 기능을 구현하는 데 매우 적합합니다.

Python 예시

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

스트리밍 응답은 Server-Sent Events (SSE) 형식으로 반환되며, 각 줄은 event: 및 data:로 시작합니다. 스트리밍 이벤트 유형은 다음과 같습니다.

message_start: 메시지 시작이며, 메시지의 기본 정보와 모델 이름을 포함합니다.
content_block_start: 콘텐츠 블록 시작입니다.
content_block_delta: 콘텐츠 블록의 증분 업데이트이며, 새로 생성된 텍스트 조각을 포함합니다.
content_block_stop: 콘텐츠 블록 종료입니다.
message_delta: 메시지 수준의 증분 업데이트이며, stop_reason 및 최종 usage 정보를 포함합니다. output_tokens_details.thinking_tokens의 권위 있는 값은 마지막 message_delta.usage에서만 읽어야 하며, 이벤트 간에 누적하지 마세요.
message_stop: 메시지 종료입니다.

출력 효과는 다음과 같습니다.

event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"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":"Hi"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! My name is"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. How can I help you today?"}}

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":15}}

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

스트리밍 응답에서 content_block_delta 이벤트는 점진적으로 생성되는 텍스트 내용을 포함하며, 모든 text_delta를 연결하면 완전한 응답을 얻을 수 있습니다.

JavaScript 예시

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Hello, Claude" }],
  }),
};

const response = await fetch("https://api.acedata.cloud/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

다중 턴 대화

다중 턴 대화 기능을 연동하려면 messages 배열에서 user 및 assistant 역할의 메시지를 번갈아 배치하고, 이전 대화 기록도 함께 전달해야 합니다.

Python 예시

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! Nice to meet you. How can I help you today?"},
        {"role": "user", "content": "What is my name?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

반환 결과는 다음과 같습니다.

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Your name is Alice, as you just told me!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

messages에서 전체 대화 기록을 전달하면 Claude는 문맥을 결합하여 정확하게 답변할 수 있습니다.

심층 사고 모델

Claude의 thinking과 thinking summary는 서로 다른 두 가지 개념입니다. 모델은 내부 추론을 수행할 수 있지만 API는 원본 사고 사슬을 반환하지 않습니다. 추론 과정을 표시해야 할 경우 API는 처리된 요약을 반환합니다. 현재 모델에서는 adaptive thinking 사용을 권장하며, output_config.effort를 통해 전체 추론 투입량을 제어합니다.

import requests

url = "https://api.acedata.cloud/v1/messages"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {
        "type": "adaptive",
        "display": "summarized"
    },
    "output_config": {
        "effort": "high"
    },
    "messages": [
        {"role": "user", "content": "What is the sine of 30 degrees?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

응답의 thinking 블록은 다음과 같은 형태입니다.

{
  "type": "thinking",
  "thinking": "The problem asks for a standard trigonometric value...",
  "signature": "opaque-signature"
}

display: "summarized"는 읽기 쉬운 사고 요약을 반환합니다. 이는 원시 사고 체인이 아닙니다.
display: "omitted"는 thinking: ""를 반환하지만, 후속 대화를 지원하기 위해 opaque signature는 계속 유지합니다.
display: "updates"는 Anthropic의 beta 모드이며, anthropic-beta: thinking-display-updates-2026-08-18을 함께 전송해야 합니다. 공식 정의는 추론 본문을 숨기고 도구 호출 사이에 짧은 진행 상황 업데이트를 표시하는 것입니다. 플랫폼은 이 매개변수와 beta 요청 헤더를 원래 값 그대로 전달하며, 강제로 summarized로 재작성하지 않습니다. 실제 출력 내용은 선택한 모델의 지원 여부에 따라 달라집니다.
thinking, output_config, effort, 샘플링 매개변수 및 새 확장 필드는 원래 값 그대로 전달됩니다. 플랫폼은 모델별로 하드코딩된 값 열거나 조합 제한을 유지하지 않으며, thinking 모드를 자동으로 재작성하지도 않습니다. 이러한 매개변수를 수락할지는 선택한 모델이 판단하며, 모델이 반환한 매개변수 오류는 클라이언트에 전달됩니다.
Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 및 Opus 4.7의 display 기본값은 omitted입니다. Opus 4.6, Sonnet 4.6 및 더 이전의 thinking 지원 모델은 기본적으로 summarized를 사용합니다.
Display는 반환 내용과 스트리밍 지연에만 영향을 미치며, 추론을 끄거나 thinking token 청구량을 줄이지 않습니다.
기본적으로 thinking을 활성화하는지와 display 기본값은 서로 독립된 두 가지 문제입니다. Opus 5와 Sonnet 5는 기본적으로 adaptive thinking을 활성화합니다. Opus 5의 경우 thinking을 생략하는 것은 adaptive와 동일하며, output_config.effort를 생략하는 것은 high와 동일합니다. Opus 4.8, 4.7 및 4.6은 명시적으로 활성화해야 합니다.
Thinking과 최종 본문은 함께 max_tokens 출력 예산을 사용합니다. 예산이 너무 작으면 thinking이 대부분의 할당량을 차지하여 본문이 비어 있거나 잘릴 수 있습니다. max_tokens를 늘리거나 low / medium effort를 사용하여 추론 투입량을 제어하세요.
thinking을 끌 수 있는 모델의 경우 thinking: {"type":"disabled"}를 전달할 수 있습니다. between_tools 등의 새 모드 및 effort 조합은 선택한 모델에 따라 달라집니다. 플랫폼은 이전 모델 규칙에 따라 사전에 거부하지 않습니다.
고정 사고 예산은 budget_tokens를 통해 전달할 수 있습니다. 새 모델은 일반적으로 thinking.type=adaptive 및 output_config.effort를 사용합니다. 고정 예산 또는 사고 비활성화 지원 여부는 선택한 모델의 현재 기능을 기준으로 합니다.
다중 턴 대화 및 도구 호출 시 assistant가 반환한 완전한 thinking 블록과 signature를 원본 그대로 다시 전달해야 합니다. signature를 수정하거나 직접 생성하지 마세요.
매개변수 전달은 모든 모델이 모든 기능을 지원한다는 것을 의미하지 않습니다. 프로토콜 간 호출에는 여전히 변환이 필요하며, redacted_thinking 등의 콘텐츠 지원 범위와 오류는 실제로 요청을 처리하는 모델 서비스가 결정합니다.

스트리밍 요청에서 summarized는 thinking_delta를 생성합니다. omitted는 thinking_delta를 생성하지 않고, thinking 블록 수명 주기와 signature_delta만 유지합니다.

비전 모델

Claude는 멀티모달 입력을 지원하며, 텍스트와 이미지를 동시에 처리할 수 있습니다. Messages API에서는 content를 배열 형식으로 설정하고 이미지 콘텐츠 블록을 전달하여 비전 기능을 사용할 수 있습니다.

Base64 인코딩 이미지 사용

import base64
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# 读取并编码图片
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

URL 이미지 사용

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

cURL 예시

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "What'\''s in this image?"
          }
        ]
      }
    ]
  }'

지원되는 이미지 형식에는 image/jpeg, image/png, image/gif, image/webp가 포함됩니다.

문서 및 PDF

PDF는 document 콘텐츠 블록을 사용하며, Base64와 URL 두 가지 안정적인 소스를 지원합니다. Base64 소스는 반드시 application/pdf를 사용해야 합니다.

import base64

with open("report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                },
                "title": "Quarterly report"
            },
            {"type": "text", "text": "Summarize this PDF."}
        ]
    }]
}

URL 소스는 {"type":"url","url":"https://example.com/report.pdf"}로 작성합니다. document는 text/plain 및 text/image 블록으로 구성된 content 소스도 지원합니다. 선택적 필드에는 title, context, citations가 포함됩니다. Files API의 file_id 소스는 독립적인 beta 기능에 속하며, 이 인터페이스의 안정적인 계약에 포함되지 않습니다.

프롬프트 캐시

최상위 cache_control은 캐시 중단점을 마지막 캐시 가능 블록에 자동으로 배치합니다.

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "You are an expert on this reference material.",
    "messages": [{"role": "user", "content": "Summarize the key points."}]
}

정확한 위치 제어가 필요할 때는 동일한 cache_control을 text, image, document, tool_use, tool_result 콘텐츠 블록 또는 도구 정의에 작성할 수도 있습니다. ttl은 5m(기본값)과 1h를 지원합니다. usage.cache_creation_input_tokens 및 usage.cache_read_input_tokens를 통해 캐시 쓰기와 적중을 판단하십시오. 응답에서 usage.cache_creation이 제공되는 경우, ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens입니다. cache_creation이 null이거나 생략된 경우, 캐시 쓰기 총량만 있고 권위 있는 TTL 분할은 없음을 의미합니다. 이때 어느 bucket도 알려진 0으로 간주하지 마십시오. 과금 및 총량은 여전히 aggregate 필드를 기준으로 합니다. 반환 결과 예시:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an API request configuration interface for what appears to be an AI chat completion service. The interface includes parameters for model selection, messages, stream mode, and max tokens settings."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

도구 호출（Tool Use）

Claude Messages API는 기본적으로 도구 호출 기능을 지원하며, 모델이 필요할 때 사전 정의한 도구/함수를 호출할 수 있도록 합니다.

Python 예시

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

모델이 도구 호출을 결정하면, 반환 결과의 content에는 tool_use 유형의 콘텐츠 블록이 포함됩니다:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me check the weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}

stop_reason이 tool_use라는 점에 유의하십시오. 이는 모델이 도구를 호출해야 함을 나타냅니다. 이 결과를 받은 후에는 도구 함수를 실행하고 결과를 tool_result 형식으로 모델에 다시 전달해야 합니다:

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Let me check the weather in San Francisco for you."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "San Francisco, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Sunny, 72°F"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

모델은 도구가 반환한 결과를 기반으로 최종 자연어 응답을 생성합니다.

Chat Completion API와의 차이점

Ace Data Cloud는 두 가지 Claude API 형식을 동시에 제공하며, 둘의 주요 차이점은 다음과 같습니다: Messages API의 usage.input_tokens는 캐시되지 않은 입력만을 의미하며, cache_read_input_tokens와 cache_creation_input_tokens는 독립적인 과금 버킷입니다. 세 항목은 각각 해당 가격에 따라 계산됩니다.

특성	Messages API (`/v1/messages`)	Chat Completion API (`/v1/chat/completions`)
형식	Anthropic 네이티브 형식	OpenAI 호환 형식
시스템 프롬프트	독립된 `system` 필드	`messages`의 `role: "system"`을 통해 전달
응답 구조	`content` 배열(여러 유형 지원)	`choices` 배열(`message` 포함)
스트리밍 형식	SSE 이벤트(여러 이벤트 유형)	SSE `data` 행
심층 사고	네이티브 `thinking` 및 `output_config.effort`	모델 기본 전략 및 호환 파라미터
도구 호출	네이티브 `tools` + `input_schema`	OpenAI 호환 `tools` 형식
Token 통계	`output_tokens_details.thinking_tokens`	`completion_tokens_details.reasoning_tokens`

시스템이 이미 OpenAI 형식의 API와 연동되어 있다면 Chat Completion API를 사용하여 원활하게 전환할 수 있습니다. Claude의 모든 네이티브 기능을 사용해야 한다면 Messages API 사용을 권장합니다.

오류 처리

공개 인터페이스의 오류 응답은 Ace Data Cloud 플랫폼 envelope를 사용합니다: error.code는 안정적인 오류 코드이고, error.message는 설명이며, trace_id는 요청 문제를 조사하는 데 사용됩니다. 일반적인 HTTP 상태는 다음과 같습니다:

400: 요청 파라미터 또는 프로토콜 내용이 유효하지 않습니다.
401: 인증 토큰이 유효하지 않거나, 누락되었거나, 만료되었습니다.
403: 접근 금지, 잔액 부족 또는 할당량 제한입니다.
404: API 또는 모델이 존재하지 않습니다.
413: 요청 본문이 너무 큽니다.
429: 요청이 너무 많습니다.
500 / 503 / 504: 서비스 오류, 일시적 사용 불가 또는 처리 시간 초과입니다.

오류 응답 예시

{
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

이 오류 구조는 Ace Data Cloud의 런타임 계약이며, Anthropic 공식 오류 envelope와 동일하지 않습니다. HTTP 상태 및 error.code에 따라 처리하십시오.

결론

이 문서를 통해 Anthropic 네이티브 형식으로 Claude Messages API를 사용하여 Claude의 대화 기능을 호출하는 방법을 이미 알아보았습니다. Messages API는 기본 대화, 시스템 프롬프트, 스트리밍 응답, 다중 턴 대화, 심층 사고, 시각적 이해, PDF, 프롬프트 캐싱 및 도구 호출 등 풍부한 기능을 지원합니다. 궁금한 사항이 있으시면 언제든지 기술 지원팀에 문의해 주세요.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

Claude Messages API 신청 및 사용

신청 절차

기본 사용

cURL 예시

Python 예시

시스템 프롬프트

Python 예시

스트리밍 응답

Python 예시

JavaScript 예시

다중 턴 대화

Python 예시

심층 사고 모델

비전 모델

Base64 인코딩 이미지 사용

URL 이미지 사용

cURL 예시

문서 및 PDF

프롬프트 캐시

도구 호출（Tool Use）

Python 예시

Chat Completion API와의 차이점

오류 처리

오류 응답 예시

결론

​신청 절차

​기본 사용

​cURL 예시

​Python 예시

​시스템 프롬프트

​Python 예시

​스트리밍 응답

​Python 예시

​JavaScript 예시

​다중 턴 대화

​Python 예시

​심층 사고 모델

​비전 모델

​Base64 인코딩 이미지 사용

​URL 이미지 사용

​cURL 예시

​문서 및 PDF

​프롬프트 캐시

​도구 호출（Tool Use）

​Python 예시

​Chat Completion API와의 차이점

​오류 처리

​오류 응답 예시

​결론

신청 절차

기본 사용

cURL 예시

Python 예시

시스템 프롬프트

Python 예시

스트리밍 응답

Python 예시

JavaScript 예시

다중 턴 대화

Python 예시

심층 사고 모델

비전 모델

Base64 인코딩 이미지 사용

URL 이미지 사용

cURL 예시

문서 및 PDF

프롬프트 캐시

도구 호출（Tool Use）

Python 예시

Chat Completion API와의 차이점

오류 처리

오류 응답 예시

결론