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.5: claude-opus-5-5
Step up for the hardest long-running agentic and research tasks, at 2.5x Claude Opus 5.5 pricing: Claude Fable 5.1: claude-fable-5-1
Previous Opus model: Claude Opus 5: claude-opus-5
Smart model: Claude Sonnet 5.5: claude-sonnet-5-5
Previous Sonnet model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 5.5: claude-haiku-5-5
Previous Haiku model: Claude Haiku 4.5: claude-haiku-4-5-20251001

Вызов API

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

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-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-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-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-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-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 с очень сложными задачами. Текущий механизм — это адаптивные размышления (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.5 (claude-opus-5-5, только адаптивные размышления, всегда включены)
Claude Sonnet 5.5 (claude-sonnet-5-5, только адаптивные размышления, включены по умолчанию)
Claude Haiku 5.5 (claude-haiku-5-5, только адаптивные размышления, включены по умолчанию)
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-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:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "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 рассуждать при выборе инструментов и обработке результатов.

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

Ограничение выбора инструмента: поддерживается только tool_choice: {"type": "auto"} (по умолчанию) или tool_choice: {"type": "none"}.
Сохранение блоков размышлений: во время использования инструментов вы должны передавать блоки 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-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-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:
    match block.type:
        case "thinking":
            print(f"Thinking: {block.thinking}")
        case "tool_use":
            print(f"Tool call: {block.name}({block.input})")
        case "text":
            print(f"Response: {block.text}")

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

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

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

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

Параметр	Описание
`name`	Имя инструмента. Должно соответствовать регулярному выражению `^[a-zA-Z0-9_-]{1,128}$`.
`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 Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 и Claude Mythos 5.1 варианты any и tool возвращают ошибку 400. Оставьте tool_choice в значении auto и установите "strict": true в определении инструмента, чтобы гарантировать, что любой вызов, который делает Claude, соответствует input_schema инструмента. См. Строгое использование инструментов.

Вывод JSON

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

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

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

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

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

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

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

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

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

Извлечь name, id и input из блока tool_use.
Запустить в вашей кодовой базе реальный инструмент, соответствующий этому имени инструмента.
Продолжить диалог, отправив новое сообщение с 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-5",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Типы событий

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

message_start: содержит объект Message с пустым content.
Серия блоков содержимого, каждый с content_block_start, одним или несколькими событиями content_block_delta и content_block_stop.
Одно или несколько событий message_delta, указывающих на изменения верхнего уровня в итоговом объекте Message.
Завершающее событие 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-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"}

Cookie settings

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

Модели

Вызов API

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

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

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

Зрение

Размышления

Как работают размышления

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

Сохранение блоков размышлений

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

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

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

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

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

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

Вывод JSON

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

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

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

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

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

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

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

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

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

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

Типы событий

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

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

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

Дельта размышлений

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

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

Модели

Вызов API

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

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

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

Зрение

Размышления

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

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

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

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

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

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

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

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

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

Вывод JSON

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

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

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

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

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

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

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

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

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

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

Типы событий

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

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

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

Дельта размышлений

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