Claude Chat Completion API 신청 및 사용

Anthropic Claude는 매우 강력한 AI 대화 시스템으로, 입력한 프롬프트에 따라 몇 초 만에 유창하고 자연스러운 응답을 생성할 수 있습니다. Claude는 뛰어난 언어 이해 및 생성 능력으로 업계에서 독보적인 존재로 자리 잡았으며, 현재 Claude는 다양한 산업 및 분야에서 널리 사용되고 있으며 그 영향력이 더욱 두드러지고 있습니다. 일상 대화, 창의적 글쓰기, 전문 상담, 코드 프로그래밍 등에서 Claude는 놀라운 지능적 지원을 제공하여 인간의 작업 효율성과 창의성을 크게 향상시킵니다. 이 문서는 Claude Chat Completion API 작업의 사용 프로세스를 주로 소개하며, 이를 통해 공식 Claude의 대화 기능을 쉽게 사용할 수 있습니다.

신청 프로세스

Claude Chat Completion API를 사용하려면 먼저 Claude Chat Completion API 페이지에서 “Acquire” 버튼을 클릭하여 요청에 필요한 자격 증명을 얻을 수 있습니다:

로그인 또는 등록이 되어 있지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 로그인 및 등록 후에는 자동으로 현재 페이지로 돌아옵니다. 첫 번째 신청 시 무료 한도가 제공되어 해당 API를 무료로 사용할 수 있습니다.

기본 사용

다음으로 인터페이스에 해당 내용을 입력할 수 있습니다. 아래 그림과 같이:

이 인터페이스를 처음 사용할 때는 최소한 세 가지 내용을 입력해야 합니다. 하나는 authorization으로, 드롭다운 목록에서 선택하면 됩니다. 또 다른 매개변수는 model로, model은 우리가 Claude 공식 웹사이트 모델 카테고리를 선택하는 것입니다. 여기에는 주로 20종의 모델이 있으며, 자세한 내용은 제공된 모델을 참조할 수 있습니다. 마지막 매개변수는 messages로, messages는 우리가 입력한 질문어 배열입니다. 이는 여러 질문어를 동시에 업로드할 수 있는 배열로, 각 질문어는 role과 content를 포함합니다. 여기서 role은 질문자의 역할을 나타내며, 우리는 user, assistant, system의 세 가지 신원을 제공합니다. 또 다른 content는 우리가 질문하는 구체적인 내용입니다. 또한 오른쪽에 해당 호출 코드 생성이 있으며, 코드를 복사하여 직접 실행할 수도 있고, “Try” 버튼을 클릭하여 테스트할 수도 있습니다. 자주 사용하는 선택적 매개변수:

max_tokens: 단일 응답의 최대 토큰 수를 제한합니다.
temperature: 생성의 무작위성, 0-2 사이의 값으로, 값이 클수록 더 분산됩니다.
n: 한 번에 생성할 후보 응답 수입니다.
response_format: 반환 형식 설정입니다.

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

{
  "id": "msg_bdrk_01Q6WN27v95ypCa1kbanAQ6K",
  "model": "claude-opus-4-20250514",
  "object": "chat.completion",
  "created": 1768619365,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 12,
    "total_tokens": 20,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

반환 결과는 여러 필드를 포함하며, 다음과 같이 설명됩니다:

id: 이번 대화 작업을 생성한 ID로, 이번 대화 작업을 고유하게 식별하는 데 사용됩니다.
model: 선택한 Claude 공식 모델입니다.
choices: Claude가 질문어에 대해 제공한 응답 정보입니다.
usage: 이번 질문-응답 쌍에 대한 토큰 통계 정보입니다.

그 중 choices는 Claude의 응답 정보를 포함하고 있으며, 그 안의 choices는 Claude의 구체적인 응답 정보를 보여줍니다. 아래 그림과 같이 확인할 수 있습니다.

choices 안의 content 필드에는 Claude의 구체적인 응답 내용이 포함되어 있습니다.

스트리밍 응답

이 인터페이스는 스트리밍 응답도 지원하며, 이는 웹 페이지 통합에 매우 유용하여 웹 페이지에서 글자 단위로 표시하는 효과를 구현할 수 있습니다. 스트리밍 응답을 원하면 요청 헤더의 stream 매개변수를 true로 변경하면 됩니다. 아래 그림과 같이 수정하되, 호출 코드는 스트리밍 응답을 지원하도록 적절한 변경이 필요합니다.

stream을 true로 변경하면 API는 해당 JSON 데이터를 줄 단위로 반환하며, 코드 측면에서 우리는 줄 단위 결과를 얻기 위해 적절한 수정을 해야 합니다. Python 샘플 호출 코드:

import requests

url = "https://api.xhuoapi.ai/v1/v1/chat/completions"

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

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

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

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

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": ""}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": "안녕하세요!"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": " 어떻게 도와드릴까요"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": " 오늘?"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 12, "total_tokens": 20, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0}}

data: [DONE]

볼 수 있듯이, 응답 안에는 많은 data가 있으며, data 안의 choices는 최신의 답변 내용으로, 위에서 설명한 내용과 일치합니다. choices는 추가된 답변 내용이며, 결과에 따라 시스템에 연결할 수 있습니다. 또한 스트리밍 응답의 종료는 data의 내용을 기준으로 판단하며, 내용이 [DONE]이면 스트리밍 응답이 모두 종료된 것입니다. 반환된 data 결과는 여러 필드를 포함하고 있으며, 설명은 다음과 같습니다:

id, 이번 대화 작업을 생성한 ID로, 이번 대화 작업을 고유하게 식별하는 데 사용됩니다.
model, 선택한 Claude 공식 모델입니다.
choices, Claude가 질문에 대해 제공한 답변 정보입니다.

JavaScript도 지원되며, 예를 들어 Node.js의 스트리밍 호출 코드는 다음과 같습니다:

const options = {
  method: "post",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-opus-4-20250514",
    messages: [{ role: "user", content: "안녕하세요" }],
    stream: true,
  }),
};

fetch("https://api.xhuoapi.ai/v1/v1/chat/completions", options)
  .then((response) => response.json())
  .then((response) => console.log(response))
  .catch((err) => console.error(err));

Java 샘플 코드:

JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "claude-opus-4-20250514");
jsonObject.put("messages", [{"role":"user","content":"안녕하세요"}]);
jsonObject.put("stream", true);
MediaType mediaType = "application/json; charset=utf-8".toMediaType();
RequestBody body = jsonObject.toString().toRequestBody(mediaType);
Request request = new Request.Builder()
  .url("https://api.xhuoapi.ai/v1/v1/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.print(response.body!!.string())

다른 언어는 별도로 수정할 수 있으며, 원리는 모두 동일합니다.

다중 회화

다중 회화 기능을 연결하려면 messages 필드에 여러 질문을 업로드해야 하며, 여러 질문의 구체적인 예시는 아래 그림과 같습니다:

Python 샘플 호출 코드:

import requests

url = "https://api.xhuoapi.ai/v1/v1/chat/completions"

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

payload = {
    "model": "claude-opus-4-20250514",
    "messages": [{"role":"user","content":"안녕하세요"},{"role":"assistant","content":"안녕하세요! 어떻게 도와드릴까요 오늘?"},{"role":"user","content":"제가 방금 뭐라고 했죠?"}]
}

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

여러 질문을 업로드하면 다중 회화를 쉽게 구현할 수 있으며, 다음과 같은 답변을 얻을 수 있습니다:

{
  "id": "msg_bdrk_01Y1wfQmd89g968TVbFu57Yc",
  "model": "claude-opus-4-20250514",
  "object": "chat.completion",
  "created": 1768619674,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "당신은 \"안녕하세요\"라고 말했습니다 - 그것이 우리의 대화에서 당신의 첫 번째 메시지였습니다."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 20,
    "total_tokens": 49,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

可以看到，choices 포함的信息与基本 사용的内容是一致的，这个包含了 Claude 针对多个对话进行回复的具体内容，这样就可以根据多个对话内容来回答对应的问题了。

깊이 있는 사고 모델

claude-opus-4-20250514-thinking와 claude-sonnet-4-20250514-thinking 모델은 다른 모델과 다르게, 질문어에 따라 깊이 있는 사고를 통해 답변을 제공하며, 사고 과정의 결과를 반환합니다. 본문에서는 구체적인 예시를 통해 깊이 있는 사고 기능을 시연할 것이며, 다음으로 Claude Chat Completion API 인터페이스에 해당 내용을 입력할 수 있습니다, 아래와 같이:

동시에 오른쪽에 해당 호출 코드 생성이 있으며, 코드를 복사하여 직접 실행할 수도 있고, “Try” 버튼을 클릭하여 테스트할 수도 있습니다.

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

{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "object": "chat.completion",
  "created": 1755444014,
  "model": "claude-sonnet-4-20250514-thinking",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "30도에서의 사인 값은 **1/2** 또는 **0.5**입니다.\n\n이는 기본적인 삼각 함수 값 중 하나입니다. 30-60-90 삼각형에서 변의 비율은 1:√3:2이며, 30° 각에 대한 변의 길이는 1이고, 빗변의 길이는 2입니다. 따라서 sin(30°) = 1/2입니다.",
        "reasoning_content": "사용자가 30도에서의 사인 값을 묻고 있습니다. 이는 기본적인 삼각법 질문입니다.\n\n30도에서의 사인 값은 잘 알려진 값입니다. 30-60-90 삼각형에서 변의 비율은 1:√3:2입니다.\n\n30° 각에 대해:\n- 맞은편 변의 길이는 1\n- 빗변의 길이는 2\n- 따라서 sin(30°) = 맞은편 변/빗변 = 1/2 = 0.5입니다.\n\n이는 일반적으로 암기되는 표준 삼각 함수 값 중 하나입니다."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 60,
    "completion_tokens": 239,
    "total_tokens": 299,
    "prompt_tokens_details": {
      "cached_tokens_details": {}
    },
    "completion_tokens_details": {}
  }
}

可以看到，choices 안의 답변 정보는 깊이 있는 사고 후에 얻어진 것이며, 관련된 사고 과정 내용도 제공됩니다. 여기서 content 중 reasoning_content는 모델의 사고 과정을 나타냅니다. choices 안의 답변 정보는 markdown 문법을 통해 렌더링되어야 최상의 경험을 얻을 수 있으며, 이는 또한 우리 모델의 네트워크 기능의 강력한 장점을 보여줍니다.

시각 모델

claude-sonnet-4-20250514는 Claude가 개발한 다중 모달 대형 언어 모델로, claude-4를 기반으로 시각 이해 능력을 추가했습니다. 이 모델은 텍스트와 이미지 입력을 동시에 처리할 수 있으며, 교차 모달 이해 및 생성을 실현합니다. claude-sonnet-4-20250514 모델의 텍스트 처리는 위의 기본 사용 내용과 일치하며, 아래에서는 모델의 이미지 처리 능력을 사용하는 방법을 간략히 소개합니다. claude-sonnet-4-20250514 모델의 이미지 처리 능력은 원래의 content 내용에 type 필드를 추가하여 사용됩니다. 이 필드를 통해 업로드된 것이 텍스트인지 이미지인지 알 수 있으며, 이를 통해 claude-sonnet-4-20250514 모델의 이미지 처리 능력을 사용할 수 있습니다. 아래에서는 Curl과 Python 두 가지 방법으로 이 기능을 호출하는 방법을 설명합니다.

Curl 스크립트 방식

curl -X POST 'https://api.xhuoapi.ai/v1/v1/chat/completions' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "이 이미지에는 무엇이 있나요?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://cdn.xhuoapi.ai/ueugot.png"
            }
          }
        ]
      }
    ]
  }'

Python 스크립트 방식

import requests

url = "https://api.xhuoapi.ai/v1/v1/chat/completions"

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

payload = {
    "model": "claude-sonnet-4-20250514",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text", "text": "이 이미지에는 무엇이 있나요?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.xhuoapi.ai/ueugot.png"
                    }
                },
            ],
        }
    ]
}

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

그런 다음 아래와 같은 결과를 얻을 수 있으며, 결과 안의 필드 정보는 위와 일치합니다. 구체적으로는 다음과 같습니다:

{
  "id": "msg_bdrk_01NCrxpZmV17bhQJJRQEFEb9",
  "model": "claude-sonnet-4-20250514",
  "object": "chat.completion",
  "created": 1768628904,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "이 이미지는 AI 채팅 완성 서비스의 API 요청 구성 인터페이스를 보여줍니다. 주요 요소는 다음과 같습니다:\n\n**요청 본문 매개변수:**\n\n1. **model** (필수 문자열) - \"claude-opus-4-202505...\"로 설정 - 사용할 AI 모델을 지정합니다.\n\n2. **messages** (필수 배열) - 대화 기록을 포함하며:\n   - **role** (필수 문자열) - \"user\"로 설정\n   - **content** (필수 문자열) - 메시지 내용으로 \"Hello\"를 포함합니다.\n\n3. **stream** (부울) - \"true\"로 설정 - ChatGPT와 같은 부분 메시지 델타를 활성화합니다.\n\n4. **max_tokens** (숫자) - 응답에서 생성할 수 있는 최대 토큰을 설정하는 필드입니다.\n\n5. **n** (숫자) - 각 입력에 대해 생성할 채팅 완성 선택 수를 지정합니다.\n\n인터페이스는 어두운 테마로 흰색 텍스트가 검은색/어두운 회색 배경에 표시됩니다. 오른쪽 하단에 \"Fill Example\" 버튼이 있으며, API 요청 매개변수를 구성하기 위한 다양한 드롭다운 메뉴와 입력 필드가 있습니다. 메시지 항목을 제거하기 위한 빨간색 쓰레기통/삭제 아이콘이 보입니다."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1570,
    "completion_tokens": 252,
    "total_tokens": 1822,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

답변의 내용은 이미지를 기반으로 하고 있으므로, 위의 두 가지 방법을 통해 claude-3-7-sonnet-20250219 모델의 텍스트 및 이미지 처리 능력을 쉽게 사용할 수 있습니다.

오류 처리

API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:

400 token_mismatched：잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다.
400 api_not_implemented：잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다.
401 invalid_token：권한 없음, 잘못되었거나 누락된 인증 토큰입니다.
429 too_many_requests：요청이 너무 많습니다, 비율 제한을 초과했습니다.
500 api_error：내부 서버 오류, 서버에서 문제가 발생했습니다.

오류 응답 예시

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

결론

이 문서를 통해 Claude Chat Completion API를 사용하여 공식 Claude의 대화 기능을 쉽게 구현하는 방법을 이해하셨습니다. 이 문서가 API를 더 잘 연결하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.

Documentation Index

​신청 프로세스

​기본 사용

​스트리밍 응답

​다중 회화

​깊이 있는 사고 모델

​시각 모델

​오류 처리

​오류 응답 예시

​결론