Claude Chat Completion API 신청 및 사용

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

신청 절차

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

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

📘 전체 문서: Claude Chat Completion API →

기본 사용

이제 화면에서 해당 내용을 입력할 수 있으며, 그림과 같습니다:

이 인터페이스를 처음 사용할 때는 최소 세 가지 내용을 입력해야 합니다. 하나는 authorization이며, 드롭다운 목록에서 직접 선택하면 됩니다. 또 다른 매개변수는 model이며, 최신 플래그십인 claude-fable-5-1 사용을 권장합니다. 기존 claude-fable-5도 계속 호출할 수 있습니다. 마지막 매개변수는 messages이며, 질문 문구 배열로서 각 요소에는 role과 content가 포함됩니다. role은 user, assistant, system을 지원하고, content는 구체적인 내용입니다. Claude Fable 5.1은 100만 Token 컨텍스트와 최대 128K Token 출력을 지원합니다. 동시에 오른쪽에 해당 호출 코드가 생성되는 것을 확인할 수 있으며, 코드를 복사하여 바로 실행하거나 「Try」 버튼을 직접 클릭하여 테스트할 수 있습니다. 자주 사용하는 선택적 매개변수:

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

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

{
  "id": "msg_bdrk_01Q6WN27v95ypCa1kbanAQ6K",
  "model": "claude-opus-4-8",
  "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,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

반환 결과에는 여러 필드가 있으며, 다음과 같이 소개합니다:

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

Chat Completions 형식에서 usage.prompt_tokens는 총 입력량입니다. prompt_tokens_details.cached_tokens와 prompt_tokens_details.cache_write_tokens는 각각 캐시 읽기 및 쓰기 세부 정보를 기록합니다. completion_tokens_details.reasoning_tokens는 completion_tokens의 하위 집합이므로, 총량 또는 비용을 계산할 때 다시 더하지 마세요. 비스트리밍 응답은 usage.cost 객체를 반환할 수도 있으며, 여기서 amount는 실제 크레딧 소모량, currency는 측정 단위, list_amount는 할인 전 금액(있는 경우)입니다. Chat-compatible의 필드명은 reasoning_tokens이며, 네이티브 Messages API는 output_tokens_details.thinking_tokens를 사용합니다. 두 프로토콜의 wire schema는 서로 다르므로 클라이언트는 필드명을 혼용해서는 안 됩니다. 그중 choices에는 Claude의 응답 정보가 포함되어 있으며, 그 안의 choices는 Claude 응답의 구체적인 정보로, 그림과 같이 확인할 수 있습니다.

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

스트리밍 응답

이 인터페이스는 스트리밍 응답도 지원하며, 이는 웹페이지 연동에 매우 유용하고 웹페이지에서 한 글자씩 표시되는 효과를 구현할 수 있습니다. 응답을 스트리밍으로 반환하려면 요청 헤더의 stream 매개변수를 변경하여 true로 수정할 수 있습니다. 수정 사항은 그림과 같지만, 스트리밍 응답을 지원하려면 호출 코드도 이에 맞게 변경해야 합니다.

stream을 true로 수정한 후 API는 해당 JSON 데이터를 한 줄씩 반환하며, 코드 수준에서 한 줄씩의 결과를 얻기 위해 համապատասխան 수정이 필요합니다. Python 예시 호출 코드:

import requests

url = "https://api.acedata.cloud/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": "Hello!"}, "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": " How can I help you"}, "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": " today?"}, "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, "cache_write_tokens": 0}, "completion_tokens_details": {"reasoning_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: "Hello" }],
    stream: true,
  }),
};

fetch("https://api.acedata.cloud/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":"Hello"}]);
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.acedata.cloud/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.acedata.cloud/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"},{"role":"assistant","content":"Hello! How can I help you today?"},{"role":"user","content":"What I say just now?"}]
}

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": "You said \"Hello\" - that was your first message to me in our conversation."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 20,
    "total_tokens": 49,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

choices에 포함된 정보는 기본 사용의 내용과 일치하며, 여기에는 Claude가 여러 대화에 대해 답변한 구체적인 내용이 포함되어 있어 여러 대화 내용을 기반으로 해당 질문에 답변할 수 있습니다.

심층 사고

차세대 Claude 모델은 모델 기본 정책에 따라 추론을 수행할 수 있으며, -thinking 모델 접미사를 통해 트리거할 필요가 없습니다. Chat-compatible 응답은 OpenAI 호환 usage 필드인 completion_tokens_details.reasoning_tokens를 사용합니다. reasoning_tokens는 이미 completion_tokens에 포함되어 있으므로 중복하여 더하지 마십시오. 추론과 표시되는 본문은 출력 token 상한을 공유하므로, max_tokens가 작을 경우 본문이 비어 있거나 잘릴 수 있습니다. 이러한 경우 출력 예산을 늘리거나, 사용하는 모델에서 지원하는 경우 더 낮은 추론 투입을 선택하십시오. 네이티브 thinking, output_config.effort, thinking 콘텐츠 블록 및 서명 반환이 필요한 경우 /v1/messages를 사용하십시오. Messages에 해당하는 usage 필드는 output_tokens_details.thinking_tokens이며, Chat-compatible의 completion_tokens_details.reasoning_tokens와 혼용하지 마십시오.

비전 모델

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.acedata.cloud/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": "What'\''s in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          }
        ]
      }
    ]
  }'

Python 스크립트 방식

import requests

url = "https://api.acedata.cloud/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": "What's in this image?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.acedata.cloud/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,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_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의 대화 기능을 쉽게 구현하기 위해 Claude Chat Completion API를 사용하는 방법을 이해했습니다. 이 문서가 해당 API를 더 잘 연동하고 사용하는 데 도움이 되기를 바랍니다. 궁금한 점이 있으시면 언제든지 기술 지원팀에 문의하십시오.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

Claude Chat Completion API 신청 및 사용

신청 절차

기본 사용

스트리밍 응답

다중 턴 대화

심층 사고

비전 모델

오류 처리

오류 응답 예시

결론

​신청 절차

​기본 사용

​스트리밍 응답

​다중 턴 대화

​심층 사고

​비전 모델

​오류 처리

​오류 응답 예시

​결론

신청 절차

기본 사용

스트리밍 응답

다중 턴 대화

심층 사고

비전 모델

오류 처리

오류 응답 예시

결론