

Введение в использование API для Claude

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



Модели

Smartest model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 4.6: claude-sonnet-4-6
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001



Вызов API



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

import anthropic
import os

message = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
).messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}



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

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

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    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

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

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 httpx

# Вариант 1: изображение в кодировке Base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    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(message.content[0].text)

# Вариант 2: изображение по URL-ссылке
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url.content[0].text)



Расширенное мышление

«Extended thinking» (расширенное мышление) иногда может помочь Claude справиться с очень сложными задачами. В моделях до Claude Opus 4.7 при включённом расширенном мышлении температура должна быть установлена на 1.

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

• Claude Opus 4.8 (claude-opus-4-8, только адаптивное мышление)
• Claude Opus 4.7 (claude-opus-4-7)
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• 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-4-8",
    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}")

При использовании ручного расширенного мышления (type: enabled) параметр budget_tokens определяет максимальное количество токенов, которое Claude разрешено использовать для внутреннего процесса рассуждения. В моделях Claude 4 и более поздних этот лимит применяется к полным токенам мышления, а не к суммированному выводу. Более крупные бюджеты могут улучшить качество ответа, позволяя проводить более тщательный анализ сложных проблем. Если вы не используете чередующееся мышление, budget_tokens должен быть меньше max_tokens, чтобы у Claude оставалось место для написания ответа после завершения мышления.



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

Расширенное мышление можно использовать вместе с использованием инструментов, что позволяет 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-4-8",
    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-4-8",
    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)



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

Расширенное мышление с использованием инструментов в моделях Claude 4 поддерживает «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": "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 использовать какие-либо инструменты.



Вывод в формате JSON

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



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

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

{
  "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.



Обработка блоков контента tool use и tool result



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

Ответ будет иметь 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 в ваших определениях инструментов.



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

При создании сообщения вы можете установить "stream": true, чтобы инкрементально передавать ответ с помощью «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-4-8",
) 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-4-8", "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"}