Как использовать Claude API для разработки: полное руководство 2026

Claude API от Anthropic даёт разработчикам программный доступ к одной из наиболее способных языковых моделей 2026 года. Строите ли вы AI-ассистента для кодирования, пайплайн анализа документов, чат-бота или автономного агента — Claude API предоставляет все необходимые примитивы: стриминг ответов, tool use (вызов функций), vision (анализ изображений), расширенное мышление, кэширование промптов и Batches API для высоконагруженных задач.

Это руководство охватывает всё, что нужно разработчику, чтобы пройти от нуля до готовой к продакшену интеграции с Claude — с реальными примерами на TypeScript и Python.

Получение API-ключа

Зайдите на console.anthropic.com, создайте аккаунт. После верификации почты перейдите в раздел API Keys в левой панели и нажмите Create Key. Сразу сохраните ключ — он показывается только один раз.

Anthropic использует тарификацию по потреблению. Новые аккаунты получают небольшой бесплатный кредит. Для продакшена добавьте способ оплаты и настройте лимиты расходов. Никогда не встраивайте ключ в код — используйте переменные окружения:

# .env (добавьте в .gitignore!)
ANTHROPIC_API_KEY=sk-ant-api03-...

Настройка SDK

TypeScript / Node.js

npm install @anthropic-ai/sdk
# или
pnpm add @anthropic-ai/sdk

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

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

Python

pip install anthropic
# или с uv:
uv add anthropic

import anthropic, os

client = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
)

SDK — тонкие обёртки над REST API. Оба поддерживают async/await нативно. TypeScript SDK поставляется с полными определениями типов.

Базовый запрос

Основной вызов API — messages.create. Передаёте название модели, лимит токенов и массив сообщений в формате [{role, content}].

TypeScript

const message = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "Объясни разницу между TCP и UDP простыми словами.",
    },
  ],
});

console.log(message.content[0].text);

Python

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Объясни разницу между TCP и UDP простыми словами.",
        }
    ],
)

print(message.content[0].text)

Объект ответа содержит content (массив блоков контента), stop_reason (end_turn, max_tokens, tool_use или stop_sequence) и usage (количество входных и выходных токенов для биллинга).

Системные промпты

Системные промпты определяют роль, ограничения и поведение AI. Они передаются как параметр верхнего уровня system (не как сообщение), что позволяет кэшировать их отдельно для экономии.

const message = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 2048,
  system: `Ты — старший TypeScript-инженер, проверяющий код для продакшен-кодовой базы.
Твои ревью краткие, конкретные и практичные. Ты выявляешь:
- Уязвимости безопасности и проблемы валидации ввода
- Узкие места производительности
- Отсутствующую обработку ошибок
- Проблемы с типами TypeScript

Ты не комментируешь стиль, если он не влияет на читаемость существенно.
Форматируй ревью как маркированный список со ссылками file:line где применимо.`,
  messages: [{ role: "user", content: `Проверь этот обработчик маршрута API:

${code}` }],
});

Лучшие практики системных промптов

• Будьте конкретны в формате — скажите Claude точно, какую структуру вывода вы ожидаете
• Определяйте, что НЕ делать — ограничения часто полезнее инструкций
• Включайте примеры — для задач структурированного вывода добавьте few-shot примеры в системный промпт
• Задавайте тон и персону — «Ты — лаконичный API без лишних слов» даёт другой результат, чем «Ты — полезный ассистент»
• Стабильный контент в system, динамический в user — это позволяет кэшировать промпты

Стриминг ответов

Для пользовательских интерфейсов стриминг критичен для воспринимаемой отзывчивости. Claude начинает отдавать токены почти мгновенно, SDK предоставляет интерфейс async iterator.

TypeScript

const stream = client.messages.stream({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Напиши короткое стихотворение о компиляторах." }],
});

for await (const chunk of stream) {
  if (
    chunk.type === "content_block_delta" &&
    chunk.delta.type === "text_delta"
  ) {
    process.stdout.write(chunk.delta.text);
  }
}

const finalMessage = await stream.finalMessage();
console.log("
Всего токенов:", finalMessage.usage.output_tokens);

Python

with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Напиши короткое стихотворение о компиляторах."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Tool Use (вызов функций)

Tool use — механизм, который превращает Claude из генератора текста в агента, взаимодействующего с реальным миром. Вы определяете инструменты (функции), а Claude решает, когда и как их вызывать на основе контекста разговора.

Определение инструментов

const tools: Anthropic.Tool[] = [
  {
    name: "get_weather",
    description: "Получает текущую погоду для указанного места.",
    input_schema: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "Город и страна, например 'Москва, Россия'",
        },
        unit: {
          type: "string",
          enum: ["celsius", "fahrenheit"],
          description: "Единица температуры. По умолчанию celsius.",
        },
      },
      required: ["location"],
    },
  },
];

Агентный цикл

async function runAgentLoop(userMessage: string) {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  while (true) {
    const response = await client.messages.create({
      model: "claude-opus-4-6",
      max_tokens: 4096,
      tools,
      messages,
    });

    messages.push({ role: "assistant", content: response.content });

    if (response.stop_reason === "end_turn") {
      const textBlock = response.content.find((b) => b.type === "text");
      return textBlock?.type === "text" ? textBlock.text : "";
    }

    if (response.stop_reason === "tool_use") {
      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of response.content) {
        if (block.type === "tool_use") {
          const result = await executeToolCall(block.name, block.input);
          toolResults.push({
            type: "tool_result",
            tool_use_id: block.id,
            content: JSON.stringify(result),
          });
        }
      }

      messages.push({ role: "user", content: toolResults });
    }
  }
}

Для продакшен агентных рабочих процессов рассмотрите подключение Claude к вашим внутренним сервисам через MCP-серверы. Каталог Mindaxis MCP содержит готовые серверные интеграции для баз данных, GitHub, Slack и десятков других сервисов.

Vision: анализ изображений

Claude может анализировать изображения, диаграммы, скриншоты и документы. Изображения передаются как base64-данные или URL в массиве контента.

import fs from "fs";

const imageData = fs.readFileSync("./screenshot.png");
const base64Image = imageData.toString("base64");

const response = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: base64Image,
          },
        },
        {
          type: "text",
          text: "Определи все UI-компоненты, видимые на этом скриншоте, и предложи улучшения макета.",
        },
      ],
    },
  ],
});

Поддерживаемые форматы изображений: JPEG, PNG, GIF и WebP. Максимальный размер изображения — 5MB. Для анализа документов можно также использовать поддержку PDF от Anthropic.

Расширенное мышление (Extended Thinking)

Расширенное мышление даёт Claude дополнительное «черновое» пространство для рассуждений над сложными задачами перед формированием финального ответа.

const response = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 16000,
  thinking: {
    type: "enabled",
    budget_tokens: 10000,
  },
  messages: [
    {
      role: "user",
      content: "Проанализируй временну́ю сложность этого алгоритма и предложи оптимизации: ...",
    },
  ],
});

for (const block of response.content) {
  if (block.type === "thinking") {
    console.log("Рассуждения Claude:", block.thinking);
  } else if (block.type === "text") {
    console.log("Финальный ответ:", block.text);
  }
}

Расширенное мышление наиболее ценно для: сложных алгоритмических задач, многошаговой математики, стратегического планирования и задач, требующих тщательного взвешивания компромиссов. Оно существенно увеличивает потребление токенов — используйте его избирательно.

Кэширование промптов

Кэширование промптов — одна из наиболее эффективных техник оптимизации затрат. Когда вы помечаете части промпта через cache_control: { type: "ephemeral" }, Anthropic кэширует этот контент на 5 минут. Последующие запросы с тем же кэшированным префиксом тарифицируют только новые токены — кэшированные токены стоят ~10% от обычной цены входных токенов.

const response = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: largeDocumentOrCodebase, // Этот большой блок кэшируется
      cache_control: { type: "ephemeral" },
    },
    {
      type: "text",
      text: "Ты — эксперт по анализу кода. Отвечай на вопросы о кодовой базе выше.",
    },
  ],
  messages: [{ role: "user", content: userQuestion }],
});

Идеальные сценарии для кэширования промптов: чат-боты с большим системным промптом или документом, инструменты анализа кода где одна кодовая база запрашивается много раз, Q&A по документу где контент документа переиспользуется. На рабочих нагрузках с высоким hit rate кэширование промптов может снизить затраты на 60–80%.

Batches API

Batches API позволяет отправить до 10 000 запросов в одном пакетном задании, которое обрабатывается асинхронно в течение 24 часов. Цена батч-запросов на 50% ниже реалтаймовых — существенная экономия для высоконагруженных офлайн-задач: обогащение данных, классификация документов, генерация отчётов.

// Создаём батч
const batch = await client.messages.batches.create({
  requests: documents.map((doc, i) => ({
    custom_id: `doc-${i}`,
    params: {
      model: "claude-haiku-4-5",
      max_tokens: 512,
      messages: [
        {
          role: "user",
          content: `Классифицируй этот тикет поддержки как: bug, feature-request или question. Ответь только категорией.

${doc.text}`,
        },
      ],
    },
  })),
});

console.log("Batch ID:", batch.id);

// Опрашиваем статус
let result = await client.messages.batches.retrieve(batch.id);
while (result.processing_status !== "ended") {
  await new Promise((resolve) => setTimeout(resolve, 30000));
  result = await client.messages.batches.retrieve(batch.id);
}

// Скачиваем результаты
for await (const item of await client.messages.batches.results(batch.id)) {
  if (item.result.type === "succeeded") {
    const text = item.result.message.content[0];
    if (text.type === "text") {
      console.log(`${item.custom_id}: ${text.text}`);
    }
  }
}

Обработка ошибок и рейт-лимиты

SDK Anthropic выбрасывает типизированные ошибки, которые можно обрабатывать соответствующим образом:

async function callWithRetry(params: Anthropic.MessageCreateParamsNonStreaming) {
  const maxRetries = 3;
  let lastError: Error | undefined;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.messages.create(params);
    } catch (error) {
      if (error instanceof Anthropic.RateLimitError) {
        const delay = Math.pow(2, attempt) * 1000;
        console.warn(`Rate limit. Повтор через ${delay}мс...`);
        await new Promise((resolve) => setTimeout(resolve, delay));
        lastError = error;
      } else if (error instanceof Anthropic.APIStatusError && error.status >= 500) {
        const delay = 1000 * (attempt + 1);
        await new Promise((resolve) => setTimeout(resolve, delay));
        lastError = error;
      } else {
        throw error;
      }
    }
  }
  throw lastError;
}

Ключевые типы ошибок: AuthenticationError (401) — неверный API-ключ; RateLimitError (429) — слишком много запросов, нужен backoff; APIStatusError (529) — API перегружен, повторяйте с экспоненциальной задержкой.

Стратегии оптимизации затрат

1. Выбирайте правильную модель

• claude-haiku-4-5 — самая быстрая и дешёвая, для классификации, извлечения данных, простых Q&A
• claude-sonnet-4-6 — сбалансированная по возможностям и цене, рабочая лошадка для большинства задач
• claude-opus-4-6 — максимальные возможности, максимальная цена, для сложных рассуждений и критических выводов

Маршрутизируйте простые задачи на Haiku, сложные — на Opus. Одно это изменение может снизить затраты в 5–20 раз на смешанных нагрузках.

2. Используйте кэширование промптов

Кэшируйте большие, стабильные системные промпты и контексты документов. 10-кратное снижение стоимости кэшированных токенов быстро накапливается на conversational или document-heavy нагрузках.

3. Ограничивайте длину вывода

Устанавливайте max_tokens агрессивно. Если нужна только метка классификации — ставьте max_tokens: 10. Неиспользованная ёмкость бесплатна, но вывод тарифицируется поттокенно.

4. Используйте Batches для офлайн-обработки

Любая нагрузка, не требующая реалтайм-результатов, должна использовать Batches API для скидки 50%.

От сырого API к MCP-серверам

По мере зрелости вашей интеграции с Claude вы, вероятно, построите сложные обёртки инструментов: доступ к БД, API-клиенты, файловые инструменты, веб-поиск. При определённой сложности управление этим как inline-определениями инструментов становится громоздким.

MCP (Model Context Protocol) — стандарт для этого случая. Вместо определения инструментов inline в вызовах API вы упаковываете их как MCP-серверы, к которым может подключиться любой совместимый клиент (Claude Code, Cursor, Claude Desktop или ваш собственный агент на SDK).

Каталог Mindaxis MCP предоставляет готовые, прошедшие аудит безопасности MCP-серверы для наиболее распространённых интеграций. Используйте Mindaxis Builder для сборки вашего стека MCP-серверов и экспорта корректной конфигурации для каждого инструмента.

Заключение

Claude API — один из наиболее способных и хорошо спроектированных API для разработчиков в 2026 году. Ключевые выводы: начните с базового messages.create, сразу добавьте стриминг для пользовательских интерфейсов, используйте tool use для агентных сценариев, внедрите кэширование промптов как только промпты стабилизируются, применяйте Batches API для офлайн-обработки, и грамотно маршрутизируйте задачи между моделями. Изучите паки Mindaxis для готовых конфигураций Claude под самые распространённые сценарии разработки.