첫 번째 API 호출

준비하기

먼저 platform.claude.com에서 API 키를 발급받으세요. 첫 API 호출 전에 Claude Console의 Billing 페이지에서 크레딧이 있는지 확인하세요. 크레딧이 없다면 거기서 추가하면 됩니다.



발급받은 API 키를 .env.local 파일에 저장해서 버전 관리 시스템 밖에 두세요. 소스 파일에 키를 하드코딩하면 GitHub에 키가 유출되는 대표적인 원인이 됩니다 — 환경 변수 파일에 보관하세요.

다음으로 SDK를 설치합니다:

요청의 구조

모든 API 호출은 messages.create 함수를 거칩니다. 다음 세 가지를 지정합니다:

• 모델 — 요청을 처리할 Claude 모델
• 최대 토큰 수 제한 — 응답 길이의 상한선
• 메시지 목록 — user 또는 assistant 역할을 가진 객체들로, 다른 곳에서 Claude와 대화할 때와 비슷한 구조입니다

가장 기본적인 형태는 다음과 같습니다:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const msg = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 2048,
  messages: [{
    role: "user",
    content: "Hello, Claude",
  }],
});

실제 예제: 버그가 있는 코드 리뷰하기

이번에는 "hello"보다 조금 더 흥미로운 걸 Claude에게 줘봅시다. 버그가 있는 코드를 보여주고 리뷰를 요청해 보겠습니다. 전체 내용은 이렇습니다 — 파일 하나, 약 20줄의 코드입니다:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const buggyCode = `
function add(a, b) {
  return a - b;
}
`;

const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 2048,
  system: "You are a terse senior code reviewer. Give feedback in one paragraph.",
  messages: [
    { role: "user", content: `Review this code:\n${buggyCode}` },
  ],
});

for (const block of response.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

여기서 주목할 두 가지가 있습니다:

1. system 프롬프트는 페르소나를 형성하는 곳입니다. 저는 수다스럽지 않고 간결한 시니어 리뷰어를 원하므로, 그냥 그렇게 말해줍니다.
2. 응답의 message.content는 문자열이 아니라 블록의 배열입니다. 기본적인 텍스트 응답의 경우 보통 text 타입의 블록이 하나뿐이지만, Claude는 텍스트, 도구 호출, thinking 등 여러 블록을 반환할 수 있으므로 항상 순회하면서 타입을 확인해야 합니다.

실행해보면, Claude는 add가 실제로는 뺄셈을 하고 있다는 것을 발견하고 한 문단으로 알려줍니다. 그게 전부입니다. 그게 전체 API 호출입니다.



스크립트에서 제품으로

실제 제품에서는 동일한 messages.create 구조가 요약 엔드포인트 같은 기능의 핵심 엔진이 됩니다. 데이터베이스에서 회의록을 가져와서, "인사이트와 리스크를 추출하라"는 시스템 프롬프트와 함께 Claude에게 전달하고, 결과를 해당 행에 다시 저장한 뒤 UI로 반환합니다. 동일한 호출이며 — 단지 라우트 핸들러로 감싸져 있을 뿐입니다.



요약

• 첫 번째 API 호출은 모델, 토큰 제한, 메시지를 가진 messages.create 함수입니다.
• API 키는 .env.local 파일에 저장해서 버전 관리 시스템 밖에 두세요.
• Claude의 동작을 형성하기 위해 시스템 프롬프트를 추가하세요.
• 응답 content는 블록의 배열입니다 — 각 블록의 type을 순회하며 확인하세요.
• 여기서부터는 모든 것이 이 패턴 위에 쌓여갑니다.