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

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

Модели

Самая умная модель: Claude Opus 4.6: claude-opus-4-6
Умная модель: Claude Sonnet 4.6: claude-sonnet-4-6
Для быстрых и экономичных задач: 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-6",
    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-6",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

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

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

import anthropic

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

Зрение

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-6",
    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?"},
            ],
        }
    ],
)

# Вариант 2: Изображение, указанное по URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-6",
    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?"},
            ],
        }
    ],
)

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

Расширенное мышление иногда может помочь Claude со сложными задачами. Когда оно включено, температура должна быть установлена на 1.

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

• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

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

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    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}")

Параметр budget_tokens определяет максимальное количество токенов, которое Claude может использовать для своего внутреннего процесса рассуждения. В моделях Claude 4 это ограничение применяется к полным токенам мышления, а не к сводному выводу. Более крупные бюджеты могут улучшить качество ответов, обеспечивая более тщательный анализ сложных проблем. Одно правило: значение max_tokens должно быть строго больше значения budget_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-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    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-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    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",
                }
            ],
        },
    ],
)

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

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

При чередующемся мышлении и ТОЛЬКО при чередующемся мышлении (не при обычном расширенном мышлении) 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.

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

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

Ответ будет иметь 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 для постепенной потоковой передачи ответа с использованием событий, отправляемых сервером (SSE).

Потоковая передача с SDK

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-4-6",
) 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-6", "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"}