Claude Platform Docs
Documentation

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

Это руководство предназначено для того, чтобы дать Claude основы использования Claude API. Оно содержит объяснения и примеры идентификаторов моделей/базового Messages API, использования инструментов, потоковой передачи, мышления и ничего более.

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

Это руководство предназначено для того, чтобы дать Claude основы использования Claude API. Оно содержит объяснения и примеры идентификаторов моделей/базового Messages API, использования инструментов, потоковой передачи, мышления и ничего более.

Модели

Recommended default for most work, including complex agentic coding: Claude Opus 5: claude-opus-5
Step up for the hardest long-running agentic and research tasks, at 2x Claude Opus 5 pricing: Claude Fable 5.1: claude-fable-5-1
Previous Opus model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001

Вызов API

Базовый запрос и ответ

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
Output
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Несколько ходов диалога

Messages API не хранит состояние (stateless), а это означает, что вы всегда отправляете в API полную историю диалога. Вы можете использовать этот шаблон для постепенного построения диалога. Предыдущие ходы диалога не обязательно должны действительно исходить от Claude. Вы можете использовать синтетические сообщения assistant.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Предзаполнение ответа Claude

Вы можете предзаполнить (prefill) часть ответа Claude в последней позиции списка входных сообщений. Используйте этот приём, чтобы формировать ответ Claude. В следующем примере используется "max_tokens": 1, чтобы получить от Claude единственный ответ с выбором из нескольких вариантов.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message.content[0].text)

Зрение

Claude может читать в запросах как текст, так и изображения. Для изображений поддерживаются типы источников base64 и url, а также медиатипы image/jpeg, image/png, image/gif и image/webp.

import anthropic
import base64
import httpx2

# Вариант 1: изображение в кодировке Base64
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message.content if block.type == "text"))

# Вариант 2: изображение по ссылке URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message_from_url.content if block.type == "text"))

Мышление

Мышление иногда может помочь Claude с очень сложными задачами. Текущий механизм — это adaptive thinking (адаптивное мышление) (thinking: {"type": "adaptive"}): Claude сам решает, когда и сколько думать, а вы управляете глубиной мышления с помощью параметра effort, а не бюджета токенов. Адаптивное мышление поддерживается в моделях Claude 4.6 и более поздних, а также в Claude Mythos Preview. В моделях Claude 5 и Claude Mythos Preview мышление включено по умолчанию, если параметр thinking опущен.

Температура должна быть установлена в 1 (или оставлена незаданной) всякий раз, когда мышление включено, во всех моделях. В моделях Claude 4.7 и более поздних, а также в Claude Mythos Preview параметр temperature устарел, и принимается только его значение по умолчанию, даже когда мышление выключено.

Мышление поддерживается в следующих моделях:

  • Claude Opus 5 (, только адаптивное мышление, включено по умолчанию)
  • Claude Sonnet 5 (claude-sonnet-5, только адаптивное мышление, включено по умолчанию)
  • Claude Opus 4.8 (, только адаптивное мышление)
  • Claude Opus 4.7 (claude-opus-4-7, только адаптивное мышление)
  • Claude Opus 4.6 (claude-opus-4-6, адаптивное или устаревшее ручное мышление)
  • Claude Sonnet 4.6 (claude-sonnet-4-6, адаптивное или устаревшее ручное мышление)
  • Claude Opus 4.5 (claude-opus-4-5-20251101, только устаревшее ручное мышление)
  • Claude Sonnet 4.5 (claude-sonnet-4-5-20250929, только устаревшее ручное мышление)
  • Claude Haiku 4.5 (claude-haiku-4-5-20251001, только устаревшее ручное мышление)

Как работает мышление

Когда мышление включено, Claude создаёт блоки содержимого thinking, в которых выводит свои внутренние рассуждения. Ответ API включает блоки содержимого thinking, за которыми следуют блоки содержимого text.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# Ответ содержит блоки обобщённого мышления и текстовые блоки
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Ручное расширенное мышление (thinking: {"type": "enabled", "budget_tokens": N}) — это устаревший механизм. Оно работает только в моделях Claude с 4 по 4.6, поддерживающих мышление; модели Claude 4.7 и более поздние отклоняют type: enabled с ошибкой 400 и вместо этого используют адаптивное мышление. При ручном расширенном мышлении budget_tokens задаёт максимальное количество токенов, которое Claude разрешено использовать для внутреннего процесса рассуждения; ограничение применяется к полным токенам мышления, а не к суммаризированному выводу. Если вы не используете чередующееся мышление, budget_tokens должен быть меньше max_tokens, чтобы у Claude оставалось место для написания ответа после завершения мышления.

Мышление с использованием инструментов

Мышление можно использовать вместе с «tool use» (использованием инструментов), что позволяет Claude рассуждать при выборе инструментов и обработке результатов.

Важные ограничения:

  1. Ограничение выбора инструмента: поддерживается только tool_choice: {"type": "auto"} (по умолчанию) или tool_choice: {"type": "none"}.
  2. Сохранение блоков мышления: во время использования инструментов вы должны передавать блоки thinking обратно в API для последнего сообщения ассистента.

Сохранение блоков мышления

import anthropic

client = anthropic.Anthropic()

weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "The city name."}},
        "required": ["location"],
    },
}

weather_data = {"temperature": 72}

# Первый запрос — Claude отвечает блоком мышления и запросом инструмента
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Извлекаем блок мышления и блок использования инструментов
thinking_block = next(
    (block for block in response.content if block.type == "thinking"), None
)
tool_use_block = next(
    (block for block in response.content if block.type == "tool_use"), None
)

# Второй запрос — включаем блок мышления и результат инструмента
continuation = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Обратите внимание: thinking_block передаётся вместе с tool_use_block
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)

for block in continuation.content:
    if block.type == "text":
        print(block.text)

Чередующееся мышление

«Interleaved thinking» (чередующееся мышление) позволяет Claude думать между вызовами инструментов, рассуждая о результатах инструментов перед принятием решения о следующем шаге.

В более старых моделях, использующих ручное расширенное мышление (модели Claude 4, 4.5 и Sonnet 4.6), включите чередующееся мышление, добавив бета-заголовок interleaved-thinking-2025-05-14 в ваш запрос к API:

import anthropic

client = anthropic.Anthropic()

calculator_tool = {
    "name": "calculator",
    "description": "Perform arithmetic calculations.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "The math expression to evaluate.",
            }
        },
        "required": ["expression"],
    },
}

database_tool = {
    "name": "database_query",
    "description": "Query the product database.",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "The database query."}
        },
        "required": ["query"],
    },
}

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[calculator_tool, database_tool],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each?",
        }
    ],
    betas=["interleaved-thinking-2025-05-14"],
)

for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool call: {block.name}({block.input})")
    elif block.type == "text":
        print(f"Response: {block.text}")

При чередующемся мышлении и ТОЛЬКО при чередующемся мышлении (не при обычном ручном расширенном мышлении) budget_tokens может превышать параметр max_tokens, поскольку budget_tokens в этом случае представляет общий бюджет для всех блоков мышления в рамках одного хода ассистента.

Использование инструментов

Указание клиентских инструментов

Клиентские инструменты указываются в параметре верхнего уровня tools запроса к API. Каждое определение инструмента включает:

ПараметрОписание
nameИмя инструмента. Должно соответствовать регулярному выражению ^[a-zA-Z0-9_-]{1,64}$.
descriptionПодробное текстовое описание того, что делает инструмент, когда его следует использовать и как он себя ведёт.
input_schemaОбъект JSON Schema, определяющий ожидаемые параметры инструмента.
{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Лучшие практики для определений инструментов

Предоставляйте чрезвычайно подробные описания. Это, безусловно, самый важный фактор производительности инструментов. Ваши описания должны объяснять каждую деталь об инструменте, включая:

  • Что делает инструмент
  • Когда его следует использовать (и когда не следует)
  • Что означает каждый параметр и как он влияет на поведение инструмента
  • Любые важные оговорки или ограничения

Рассмотрите использование input_examples для сложных инструментов. Для инструментов с вложенными объектами, необязательными параметрами или входными данными, чувствительными к формату, вы можете предоставить конкретные примеры с помощью поля input_examples (бета). Это помогает Claude понять ожидаемые шаблоны входных данных. Подробности см. в разделе Предоставление примеров использования инструментов.

Пример хорошего описания инструмента:

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Управление выводом Claude

Принудительное использование инструментов

Вы можете заставить Claude использовать конкретный инструмент, указав его в поле tool_choice:

tool_choice = {"type": "tool", "name": "get_weather"}

При работе с параметром tool_choice есть четыре возможных варианта:

  • auto позволяет Claude самостоятельно решать, вызывать ли какие-либо из предоставленных инструментов (по умолчанию).
  • any сообщает Claude, что он должен использовать один из предоставленных инструментов.
  • tool заставляет Claude всегда использовать определённый инструмент.
  • none запрещает Claude использовать какие-либо инструменты.

В Claude Fable 5.1 и Claude Mythos 5.1 any и tool возвращают ошибку 400. Оставьте tool_choice в значении auto и установите "strict": true в определении инструмента, чтобы гарантировать, что любой вызов, который делает Claude, соответствует input_schema инструмента. См. Строгое использование инструментов.

Вывод JSON

Инструменты не обязательно должны быть клиентскими функциями. Вы можете использовать инструменты всякий раз, когда хотите, чтобы модель возвращала вывод JSON, соответствующий предоставленной схеме.

Цепочка рассуждений

При использовании инструментов Claude часто показывает свою «chain of thought» (цепочку рассуждений), то есть пошаговые рассуждения, которые он использует, чтобы разбить задачу на части и определить, какие инструменты использовать.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Параллельное использование инструментов

По умолчанию Claude может использовать несколько инструментов для ответа на запрос пользователя. Вы можете отключить это поведение, установив disable_parallel_tool_use=true.

Обработка блоков содержимого использования инструментов и результатов инструментов

Обработка результатов клиентских инструментов

Ответ имеет stop_reason со значением tool_use и один или несколько блоков содержимого tool_use, которые включают:

  • id: уникальный идентификатор данного конкретного блока использования инструмента.
  • name: имя используемого инструмента.
  • input: объект, содержащий входные данные, передаваемые инструменту.

Когда вы получаете ответ с использованием инструмента, вам следует:

  1. Извлечь name, id и input из блока tool_use.
  2. Запустить в вашей кодовой базе фактический инструмент, соответствующий этому имени инструмента.
  3. Продолжить диалог, отправив новое сообщение с tool_result:
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

Обработка причины остановки max_tokens

Если ответ Claude обрывается из-за достижения лимита max_tokens во время использования инструментов, повторите запрос с более высоким значением max_tokens.

Обработка причины остановки pause_turn

При использовании серверных инструментов, таких как веб-поиск, API может вернуть причину остановки pause_turn. Продолжите диалог, передав приостановленный ответ обратно как есть в последующем запросе.

Устранение ошибок

Ошибка выполнения инструмента

Если сам инструмент выдаёт ошибку во время выполнения, верните сообщение об ошибке с "is_error": true:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Недопустимое имя инструмента

Если попытка Claude использовать инструмент недопустима (например, отсутствуют обязательные параметры), повторите запрос с более подробными значениями description в определениях ваших инструментов.

Потоковая передача сообщений

При создании Message вы можете установить "stream": true, чтобы постепенно получать ответ посредством «streaming» (потоковой передачи) с использованием «server-sent events» (событий, отправляемых сервером), или SSE.

Потоковая передача с помощью SDK

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-5",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Типы событий

Каждое событие, отправляемое сервером, включает именованный тип события и связанные данные JSON. Каждый поток использует следующую последовательность событий:

  1. message_start: содержит объект Message с пустым content.
  2. Серия блоков содержимого, каждый с content_block_start, одним или несколькими событиями content_block_delta и content_block_stop.
  3. Одно или несколько событий message_delta, указывающих на изменения верхнего уровня в итоговом объекте Message.
  4. Завершающее событие message_stop.

Предупреждение: количество токенов, показанное в поле usage события message_delta, является накопительным.

Типы дельт блоков содержимого

Текстовая дельта

{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Hello frien" }
}

Дельта входного JSON

Для блоков содержимого tool_use дельты представляют собой частичные строки JSON:

{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

Дельта мышления

При использовании мышления с потоковой передачей:

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Let me solve this step by step..."
  }
}

Пример базового запроса с потоковой передачей

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

Was this page helpful?