API
verified · type: how-to · verified: 2026-07 · review: 30d · updated: 2026-07-25 · [api]

LLM API 퀵스타트 (Anthropic + AI SDK)

동작하는 호출을 빠르게 띄우고, 가장 심하게 드리프트하는 버전 사실을 못박는 문서. TS/웹 스택 복붙용.

1. Anthropic Messages API — 최소 호출

모든 게 단일 엔드포인트 POST /v1/messages 를 통한다. 툴·구조화출력·스트리밍·캐싱·thinking 은 전부 이 하나의 엔드포인트 기능이지 별도 API 가 아니다.

필수 헤더 (verified 2026-07):

x-api-key: $ANTHROPIC_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

TypeScript:

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();  // ANTHROPIC_API_KEY 를 env 에서 자동 로드

const response = await client.messages.create({
  model: "claude-opus-5",          // 현재 기본값 (verified 2026-07)
  max_tokens: 16000,
  system: "You are a helpful assistant.",  // 최상위, 메시지가 아님
  messages: [{ role: "user", content: "프랑스 수도는?" }],
});
// content 는 블록 리스트 — .type 확인 후 .text 읽기
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}

Python:

import anthropic
client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    system="You are a helpful assistant.",
    messages=[{"role": "user", "content": "프랑스 수도는?"}],
)
for block in response.content:
    if block.type == "text":
        print(block.text)

⚠️ 항상 stop_reason 을 먼저 분기한 뒤 content[0] 를 읽어라 (end_turn/max_tokens/tool_use/pause_turn/refusal). refusal 이면 content 가 비어있을 수 있다.

모델 노트 (verified 2026-07): thinking 은 thinking: {type: "adaptive"} (4.6+ 모델). 옛 budget_tokens 는 Opus 4.7/4.8/5·Sonnet 5·Fable 5 에서 400 으로 거부된다. Opus 5 는 thinking 이 기본 ON(필드 생략 = adaptive) — 4.7/4.8 은 생략 시 OFF 였다. effort 는 output_config: {effort: "low"|"medium"|"high"|"xhigh"|"max"} 에. assistant prefill 도 4.6+/Fable 5 에서 400 거부 → 구조화 출력 쓰기.

스트리밍

const stream = client.messages.stream({
  model: "claude-opus-5", max_tokens: 64000,
  messages: [{ role: "user", content: "이야기 써줘" }],
});
for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta")
    process.stdout.write(event.delta.text);
}
const final = await stream.finalMessage();

토큰 카운팅

POST /v1/messages/count_tokens 를 써라. tiktoken 절대 쓰지 마라 — OpenAI 토크나이저라 Claude 를 ~15~20% 과소집계한다.

2. Vercel AI SDK v6 — 프로바이더 무관 레이어

프로바이더 간(텍스트 생성·구조화출력·툴콜·임베딩·스트리밍)을 하나의 인터페이스로 정규화하는 TS 툴킷. AI Gateway 는 라우팅 레이어(키 하나, creator/model 문자열, 프로바이더 페일오버).

⚠️ 버전 핀 — 팩트체크 교정됨 (verified 2026-07): ai@latest 는 이제 v7 (7.0.37). 이 위키는 v6 을 의도적으로 타깃한다. - npm i ai@6 → ai-v6 dist-tag = 6.0.235 - 프로바이더 패키지는 3.x 라인 (⚠️ 4.x 아님 — 4.x 는 v7/latest 라인이다. ai@6 + 4.x 프로바이더 = 메이저 버전 불일치): - @ai-sdk/anthropic@3.0.102 - @ai-sdk/openai@3.0.88 - @ai-sdk/gateway@3.0.157 - @ai-sdk/react@3.0.237 - (또는 그냥 @ai-sdk/<pkg>@3)

텍스트 생성

import { generateText, streamText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

const { text } = await generateText({
  model: anthropic("claude-opus-5"),
  prompt: "양자컴퓨팅을 한 문단으로.",
});

AI Gateway (프로바이더 무관 라우팅)

import { generateText, gateway } from "ai";

// 평범한 문자열이 Gateway 로 자동 라우팅
const { text } = await generateText({
  model: "anthropic/claude-opus-5",   // creator/model-name — 점(dotted) 표기!
  prompt: "Hello world",
});

⚠️ Gateway 는 점 표기(claude-opus-4.8), first-party 는 대시 표기(claude-opus-4-8). 헷갈리지 마라. 인증은 env AI_GATEWAY_API_KEY.

구조화 출력 — v6 에서 변경됨

generateObject/streamObject 는 v6 에서 deprecated. Output 사용:

import { generateText, Output } from "ai";
import { z } from "zod";

const { output } = await generateText({
  model: "anthropic/claude-opus-5",
  output: Output.object({
    schema: z.object({ name: z.string(), amount: z.string().nullable() }),
  }),
  prompt: "라자냐 레시피 생성.",
});
// 스트리밍: streamText + partialOutputStream (v5 의 partialObjectStream 이름 바뀜)

툴 콜링 — v6 에서 변경됨

툴 이름은 객체 키에서 파생(name 프로퍼티 제거), 스키마 필드는 inputSchema(옛 parameters 아님):

import { generateText, tool, stepCountIs } from "ai";
import { z } from "zod";

const { text } = await generateText({
  model: "anthropic/claude-opus-5",
  tools: {
    getWeather: tool({
      description: "현재 날씨",
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => `${location} 22도 맑음`,
    }),
  },
  stopWhen: stepCountIs(5),
  prompt: "파리 날씨?",
});

v6 형태 함정 박스

  • generateObject/streamObject → Output.object
  • 툴: parameters→inputSchema, name 제거
  • 에이전트: Experimental_Agent→ToolLoopAgent (system→instructions)
  • 임베딩: textEmbeddingModel→embeddingModel
  • 메시지: CoreMessage→ModelMessage
  • v5→v6 자동 마이그레이션: npx @ai-sdk/codemod v6

3. OpenAI 패리티 한 줄

  • Responses API (/v1/responses) 가 2026 신규 프로젝트 권장 기본값. Assistants API 는 2026-08-26 하드 선셋으로 deprecated.
  • Chat Completions (/v1/chat/completions) 는 "OpenAI-호환" 게이트웨이들이 구현하는 형태 — 계속 문서화 유지.
  • Anthropic SDK 는 OpenAI-호환이 아니다 — @anthropic-ai/sdk/anthropic 를 써라.

스탠드얼론 SDK 버전 (verified 2026-07)

패키지 버전
ai (latest = v7) 7.0.37
ai (ai-v6) 6.0.235
openai (Node) 6.49.0
openai (Python) 2.48.0
anthropic (Python) 0.120.0

참고