Claude Messages API 신청 및 사용

Anthropic Claude는 매우 강력한 AI 대화 시스템으로, 입력한 프롬프트에 따라 몇 초 만에 유창하고 자연스러운 응답을 생성할 수 있습니다. Claude Messages API는 Anthropic 공식 원주율 API 형식으로, OpenAI와 호환되는 형식(채팅 완료)과는 달리, Anthropic 고유의 요청 및 응답 구조를 채택하여 Claude의 독특한 능력인 다중 모드 콘텐츠 입력, 도구 호출, 심층 사고(Extended Thinking) 등의 고급 기능을 더 잘 활용할 수 있습니다. 이 문서는 Claude Messages API 작업의 사용 흐름을 주로 설명하며, 이를 통해 우리는 Anthropic 공식과 일치하는 원주율 인터페이스를 사용하여 Claude의 대화 기능을 호출할 수 있습니다.

신청 흐름

Claude Messages API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API 토큰을 받아야 하며, 이를 백업용으로 보관합니다.

로그인 또는 등록이 되어 있지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대하며, 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스에 대해 별도로 신청할 필요가 없습니다. 최초 신청 시 무료 한도가 제공되어 무료로 체험할 수 있으며; 한도가 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.

📘 전체 문서: Claude Messages API →

기본 사용

Claude Messages API의 요청 경로는 /v1/messages로, Anthropic 공식 API와 일치합니다. 우리는 최소한 세 가지 필수 매개변수를 제공해야 합니다:

model: 사용할 Claude 모델을 선택합니다. 최신 플래그십 모델은 claude-fable-5-1(100만 토큰 컨텍스트, 최대 출력 128K 토큰)이며; 기존 claude-fable-5는 여전히 호환성을 유지합니다.
messages: 입력 메시지 배열로, 각 메시지는 role(역할)과 content(내용)를 포함하며, role은 user와 assistant를 지원합니다.
max_tokens: 최대 출력 토큰 수로, 단일 응답의 길이를 제한하는 데 사용됩니다.

자주 사용되는 선택적 매개변수:

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: 토큰 사용 통계입니다. input_tokens는 캐시되지 않은 입력이며; cache_creation_input_tokens 및 cache_read_input_tokens는 각각 캐시 쓰기 및 읽기; output_tokens는 출력 토큰 수입니다. Fable 5.1의 공식 캐시 읽기 기준가는 $0.25/백만 토큰이며, 5분 및 1시간 캐시 쓰기 기준가는 각각$ 12.50 및 $20/백만 토큰입니다; 플랫폼 실제 가격은 패키지 할인에 따라 계산됩니다. 비스트리밍 응답은 Ace Data Cloud에서 기록한 cost를 포함할 수 있습니다.

시스템 프롬프트

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": "안녕하세요, Claude"}
    ]
}

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

스트리밍 응답은 서버 전송 이벤트(SSE) 형식으로 반환되며, 각 행은 event: 및 data:로 시작합니다. 스트리밍 이벤트 유형은 다음과 같습니다:

message_start: 메시지 시작, 메시지의 기본 정보와 모델 이름을 포함합니다.
content_block_start: 콘텐츠 블록 시작.
content_block_delta: 콘텐츠 블록 증분 업데이트, 새로 생성된 텍스트 조각을 포함합니다.
content_block_stop: 콘텐츠 블록 종료.
message_delta: 메시지 수준의 증분 업데이트, stop_reason 및 최종 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":"안녕하세요"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! 제 이름은"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude입니다. 오늘 무엇을 도와드릴까요?"}}

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: "안녕하세요, 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": "안녕하세요, 제 이름은 앨리스입니다."},
        {"role": "assistant", "content": "안녕하세요 앨리스! 만나서 반갑습니다. 오늘 무엇을 도와드릴까요?"},
        {"role": "user", "content": "내 이름이 뭐죠?"}
    ]
}

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

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

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "당신의 이름은 앨리스입니다. 방금 말씀하신 대로요!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

messages에 전체 대화 기록을 전달함으로써 Claude는 맥락을 결합하여 정확한 답변을 할 수 있습니다.

심층 사고 모델

Claude의 사고와 사고 요약은 두 가지 다른 개념입니다: 모델은 내부 추론을 수행할 수 있지만, API는 원래의 사고 체인을 반환하지 않습니다. 추론 과정을 보여줘야 할 때, API는 처리된 요약을 반환합니다. 현재 모델은 적응형 사고를 사용하는 것이 좋으며, 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": "30도 사인의 값은 무엇인가요?"}
    ]
}

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

응답의 사고 블록은 다음과 같습니다:

{
  "type": "thinking",
  "thinking": "문제는 표준 삼각 함수 값을 요구합니다...",
  "signature": "opaque-signature"
}

display: "summarized"는 읽기 쉬운 사고 요약을 반환합니다; 이는 원래 사고 체인이 아닙니다.
display: "omitted"는 thinking: ""을 반환하지만, 후속 대화를 지원하기 위해 불투명한 signature는 유지합니다.
Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 및 Opus 4.7의 display 기본값은 omitted입니다; Opus 4.6, Sonnet 4.6 및 그 이전의 사고를 지원하는 모델은 기본적으로 summarized를 사용합니다.
Display는 반환 내용과 스트리밍 지연에만 영향을 미치며, 추론을 종료하거나 사고 토큰의 청구를 줄이지 않습니다.
사고의 기본 활성화 여부와 display 기본값은 두 개의 독립적인 문제입니다. Opus 5, Sonnet 5는 기본적으로 적응형 사고를 활성화합니다; Opus 4.8, 4.7 및 4.6은 명시적으로 활성화해야 합니다.
budget_tokens는 여전히 고정 사고 예산을 지원하는 구형 모델에만 사용됩니다. 새로운 모델은 thinking.type=adaptive 및 output_config.effort를 사용해야 하며, Fable 5.1의 사고는 항상 활성화되어 있으며 명시적으로 비활성화할 수 없습니다.
다중 회화 및 도구 호출 시, assistant가 반환한 전체 사고 블록 및 signature를 그대로 반환해야 하며, 수정하거나 임의로 signature를 생성하지 않아야 합니다.
일부 호환 경로는 redacted_thinking을 무손실로 처리할 수 없거나 사고를 명시적으로 비활성화할 수 없으며, 이 경우 매개변수 오류가 반환되며 요청 의미가 조용히 삭제되거나 변경되지 않습니다.

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

시각 모델

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

### Base64로 이미지 사용

```python
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": "이 이미지에는 무엇이 있나요?"
                }
            ]
        }
    ]
}

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": "이 이미지에는 무엇이 있나요?"
                }
            ]
        }
    ]
}

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": "이 이미지에는 무엇이 있나요?"
          }
        ]
      }
    ]
  }'

지원되는 이미지 형식은 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": "분기 보고서"
            },
            {"type": "text", "text": "이 PDF를 요약해 주세요."}
        ]
    }]
}

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

캐시 제어

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

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "당신은 이 참조 자료의 전문가입니다.",
    "messages": [{"role": "user", "content": "주요 사항을 요약해 주세요."}]
}

위치 제어가 필요할 경우, 동일한 cache_control을 text, image, document, tool_use, tool_result 콘텐츠 블록 또는 도구 정의에 작성할 수 있습니다. ttl은 5m(기본값) 및 1h를 지원하며, usage.cache_creation_input_tokens 및 usage.cache_read_input_tokens를 통해 캐시 작성 및 적중을 판단할 수 있습니다. 반환 결과 예시:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "이 이미지는 AI 채팅 완성 서비스로 보이는 API 요청 구성 인터페이스를 보여줍니다. 인터페이스에는 모델 선택, 메시지, 스트림 모드 및 최대 토큰 설정을 위한 매개변수가 포함되어 있습니다."
    }
  ],
  "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": "주어진 위치의 현재 날씨를 가져옵니다.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "도시와 주, 예: 샌프란시스코, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "샌프란시스코의 날씨는 어떤가요?"}
    ]
}

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": "샌프란시스코의 날씨를 확인해 보겠습니다."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "샌프란시스코, 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": "주어진 위치의 현재 날씨를 가져옵니다.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "도시와 주, 예: 샌프란시스코, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "샌프란시스코의 날씨는 어떤가요?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "샌프란시스코의 날씨를 확인해 보겠습니다."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "샌프란시스코, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "맑음, 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` 매개변수	특별 모델 이름으로 트리거(예: `-thinking` 접미사)
도구 호출	원본 `tools` + `input_schema`	OpenAI 호환 `functions` 형식
Token 통계	`input_tokens` / `output_tokens`	`prompt_tokens` / `completion_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": "가져오기 실패"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

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

결론

이 문서를 통해 Claude Messages API를 Anthropic 원본 형식으로 호출하여 Claude의 대화 기능을 사용하는 방법을 이해하게 되었습니다. Messages API는 기본 대화, 시스템 프롬프트, 스트리밍 응답, 다중 회차 대화, 심층 사고, 시각적 이해, PDF, 프롬프트 캐시 및 도구 호출 등 다양한 기능을 지원합니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

프록시

고급

Coding

Claude Messages API 신청 및 사용

신청 흐름

기본 사용

cURL 예시

Python 예시

시스템 프롬프트

Python 예시

스트리밍 응답

Python 예시

JavaScript 예제

다중 회화

Python 예제

심층 사고 모델

시각 모델

URL로 이미지 사용

cURL 예시

문서 및 PDF

캐시 제어

도구 호출 (Tool Use)

Python 예시

Chat Completion API와의 차이점

오류 처리

오류 응답 예시

결론

​신청 흐름

​기본 사용

​cURL 예시

​Python 예시

​시스템 프롬프트

​Python 예시

​스트리밍 응답

​Python 예시

​JavaScript 예제

​다중 회화

​Python 예제

​심층 사고 모델

​시각 모델

​URL로 이미지 사용

​cURL 예시

​문서 및 PDF

​캐시 제어

​도구 호출 (Tool Use)

​Python 예시

​Chat Completion API와의 차이점

​오류 처리

​오류 응답 예시

​결론

신청 흐름

기본 사용

cURL 예시

Python 예시

시스템 프롬프트

Python 예시

스트리밍 응답

Python 예시

JavaScript 예제

다중 회화

Python 예제

심층 사고 모델

시각 모델

URL로 이미지 사용

cURL 예시

문서 및 PDF

캐시 제어

도구 호출 (Tool Use)

Python 예시

Chat Completion API와의 차이점

오류 처리

오류 응답 예시

결론