API — это способ, которым программы разговаривают друг с другом. Когда ты заказываешь такси в Uber — твоё приложение отправляет запрос через API на сервер Uber. Когда Instagram показывает ленту — приложение получает посты через API.
Чтобы твой код мог общаться с AI, тебе нужен API. Без него ты можешь только вручную писать в чат Claude. С API — твоя программа сама отправляет запросы и получает ответы. Так работают все AI-продукты: Telegram-боты, автоматические ассистенты, системы анализа данных.
API (Application Programming Interface) — интерфейс для общения между программами.
Ключевое слово — интерфейс. Ты уже знаешь интерфейсы:
| Интерфейс | Кто общается | Как |
|---|---|---|
| Кнопки в лифте | Человек → Лифт | Нажимаешь "5" — лифт едет на 5 этаж |
| Экран телефона | Человек → Приложение | Тапаешь кнопку — приложение реагирует |
| API | Программа → Программа | Отправляешь запрос — получаешь ответ |
Аналогия: API — это официант в ресторане. Ты (программа) не ходишь на кухню сама. Ты говоришь официанту (API): "Мне стейк средней прожарки". Он уходит на кухню (сервер), передаёт заказ повару, и возвращается с готовым блюдом (ответом). Тебе не нужно знать, как работает кухня — нужно только знать меню (документацию API) и формат заказа.
Любое общение через API состоит из двух частей:
"Эй, Claude! Вот текст, переведи его на английский."
"Here is the translation of your text."
Это всё. Запрос → Ответ. Каждый раз, когда ты открываешь Instagram и видишь ленту — приложение отправило запрос на сервер ("дай мне новые посты"), а сервер вернул ответ (список постов с фото и текстом).
Запросы передаются по протоколу HTTP. Каждый запрос состоит из трёх частей:
Запрос = Куда + Что хочу + Данные
Разберём на примере Claude API:
https://api.anthropic.com/v1/messages
Это адрес, куда ты отправляешь запрос. Как почтовый адрес на конверте.
# Разберём по частям:
# https:// — протокол (защищённое соединение)
# api.anthropic.com — сервер Anthropic (дом, куда идёт конверт)
# /v1/ — версия API (первая версия)
# /messages — что именно мы хотим (работа с сообщениями)
У каждого сервиса свой адрес:
# Claude: https://api.anthropic.com/v1/messages
# Telegram: https://api.telegram.org/bot{token}/sendMessage
# OpenAI: https://api.openai.com/v1/chat/completions
# Погода: https://api.openweathermap.org/data/2.5/weather
POST — отправить данные и получить ответ
Это как глагол в предложении — ЧТО ты хочешь сделать:
# GET — "покажи мне" (получить данные, ничего не меняя)
# Пример: открыть профиль в Instagram — GET /profile
#
# POST — "создай / обработай" (отправить данные на обработку)
# Пример: отправить сообщение Claude — POST /messages
# Пример: опубликовать пост — POST /posts
#
# PUT — "измени" (обновить существующие данные)
# Пример: изменить описание профиля — PUT /profile
#
# DELETE — "удали" (удалить данные)
# Пример: удалить пост — DELETE /posts/123
Для Claude API мы всегда используем POST — потому что мы отправляем сообщение и хотим получить ответ.
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Что такое API? Объясни в одном предложении."
}
]
}
# "model" — какую модель использовать (Haiku, Sonnet, Opus)
# "max_tokens" — максимум слов в ответе (1024 токена ≈ 750 слов)
# "messages" — история разговора (список сообщений)
# "role" — кто говорит: "user" = ты, "assistant" = Claude
# "content" — сам текст сообщения
Ты отправляешь:
┌──────────────────────────────────────────────┐
│ КУДА: https://api.anthropic.com/v1/messages│
│ МЕТОД: POST │
│ КЛЮЧ: sk-ant-api03-xxxxx (твой пропуск) │
│ ДАННЫЕ: { model: sonnet, message: "Привет" } │
└──────────────────────────────────────────────┘
↓
Сервер Anthropic
Claude думает...
↓
Ты получаешь:
┌──────────────────────────────────────────────┐
│ КОД: 200 (всё ок) │
│ ОТВЕТ: { text: "Привет! Чем могу помочь?" } │
│ ТОКЕНЫ: input: 5, output: 12 │
└──────────────────────────────────────────────┘
Программы общаются через API в формате JSON. Ты уже знаешь его из урока 1.2.
Ответ от Claude API тоже приходит в JSON:
{
"content": [
{
"type": "text",
"text": "API — это способ, которым программы общаются друг с другом."
}
],
"model": "claude-sonnet-4-6",
"usage": {
"input_tokens": 22,
"output_tokens": 35
}
}
# "content" — ответ модели (текст, который сгенерировал Claude)
# "usage" — статистика: сколько токенов потрачено
# "input_tokens" — сколько токенов в твоём вопросе (за это ты платишь)
# "output_tokens" — сколько токенов в ответе Claude (за это тоже платишь)
Чтобы пользоваться API, нужен API-ключ — уникальная строка, которая идентифицирует тебя.
sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Аналогия: API-ключ — это как карта доступа в офис. Без неё тебя не пустят. По ней система знает кто ты, куда тебе можно ходить, и ведёт учёт.
# НИКОГДА так не делай:
api_key = "sk-ant-api03-мой-секретный-ключ" # ключ прямо в коде — ОПАСНО
# ВСЕГДА так:
import os
api_key = os.getenv("ANTHROPIC_API_KEY") # ключ берётся из .env файла
Если кто-то получит твой ключ — он сможет отправлять запросы за твои деньги. Поэтому:
- Храни ключ в .env файле (урок 1.6)
- Добавь .env в .gitignore (урок 1.7)
- Никогда не отправляй ключ в чат, не выкладывай на GitHub
Кроме данных, в каждом запросе есть заголовки — дополнительная информация о запросе.
headers = {
"x-api-key": "твой-ключ", # кто ты (пропуск)
"content-type": "application/json", # формат данных (JSON)
"anthropic-version": "2023-06-01" # версия API
}
Аналогия: Если тело запроса — это письмо внутри конверта, то заголовки — это то, что написано на конверте: обратный адрес, "заказное", "с уведомлением". Почтальон (сервер) сначала читает конверт, чтобы понять куда доставить и как обработать, а потом уже открывает и читает содержимое.
Каждый ответ API приходит с числовым кодом:
# 200 — всё хорошо, запрос выполнен
# 400 — ты отправил неправильный запрос (ошибка в данных)
# 401 — неверный API-ключ (тебя не пускают)
# 404 — такого адреса не существует
# 429 — слишком много запросов, подожди (rate limit)
# 500 — ошибка на сервере (не твоя вина)
Аналогия: Это как ответы от службы доставки: - 200 = "Доставлено" - 400 = "Неверный адрес, проверьте" - 401 = "Карта заблокирована, оплата не прошла" - 429 = "Слишком много заказов, попробуйте позже" - 500 = "У нас сломалась кухня, мы чиним"
Каждый день ты взаимодействуешь с десятками API, не зная об этом:
| Действие | Какой API работает |
|---|---|
| Открываешь Instagram | Instagram API загружает ленту, stories, рекомендации |
| Вызываешь Uber | Google Maps API строит маршрут, Stripe API списывает оплату |
| Оплачиваешь онлайн | Платёжный API (Stripe, PayPal) обрабатывает транзакцию |
| Смотришь погоду | Weather API отдаёт прогноз по твоей геолокации |
| Пишешь Claude | Anthropic API принимает сообщение и возвращает ответ |
Теперь разница в том, что ты будешь вызывать эти API из своего кода, а не через готовое приложение.
Работать с API напрямую (формировать HTTP-запросы вручную) — можно, но неудобно. Поэтому компании делают SDK (Software Development Kit) — готовую библиотеку, которая упрощает работу.
import requests
# Нужно вручную собрать URL, заголовки, тело — много кода
response = requests.post(
"https://api.anthropic.com/v1/messages",
headers={
"x-api-key": "твой-ключ",
"content-type": "application/json",
"anthropic-version": "2023-06-01"
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Привет!"}]
}
)
from anthropic import Anthropic
# SDK делает всю техническую работу за тебя
client = Anthropic() # ключ берёт из .env автоматически
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "Привет!"}]
)
Аналогия: API — это правила дорожного движения. SDK — это навигатор. Ты можешь ехать по правилам сама (чистый API), а можешь включить навигатор (SDK) — он сам проложит маршрут и скажет куда поворачивать.
В следующем уроке мы будем использовать именно SDK — так проще и быстрее.
Открой любой сервис, которым пользуешься (Telegram, Notion, Google Sheets), и найди его API-документацию. Просто загугли: [название сервиса] API documentation. Посмотри какие запросы можно делать.
Вот ответ от Claude API. Прочитай и ответь: что спросил пользователь? Сколько токенов потрачено?
{
"content": [
{
"type": "text",
"text": "Python — это язык программирования, который часто используется для AI и автоматизации."
}
],
"model": "claude-sonnet-4-6",
"usage": {
"input_tokens": 15,
"output_tokens": 28
}
}
Вот запрос к Claude API. Что в нём не так?
{
"model": "claude-sonnet-4-6",
"messages": [
{
"role": "user",
"content": "Привет!"
}
]
}
Задача 1: Что такое API своими словами?
Задача 2: Ты получил код ответа 401. Что произошло и что делать?
Задача 3: Зачем нужен SDK, если можно работать с API напрямую?
Задача 4: Почему API-ключ нельзя писать прямо в коде?
.env.| Термин | Что значит |
|---|---|
| API (Application Programming Interface) | Набор правил, по которым одна программа может общаться с другой — отправлять запросы и получать ответы. |
| HTTP | Протокол (набор правил) передачи данных в интернете, по которому работают сайты и API. |
| Запрос (request) | Сообщение, которое твоя программа отправляет серверу с просьбой что-то сделать или вернуть данные. |
| Ответ (response) | Сообщение, которое сервер отправляет обратно твоей программе с результатом или ошибкой. |
| Endpoint | Конкретный URL-адрес на сервере, к которому ты обращаешься для выполнения определённого действия. |
| JSON | Формат записи данных в виде пар "ключ: значение", который используют API для обмена информацией. |
| Заголовки (headers) | Дополнительная информация в запросе или ответе — например, тип данных, API-ключ или формат. |
| Статус-код | Число в ответе сервера, которое говорит, что произошло: 200 — всё ок, 401 — нет доступа, 500 — ошибка сервера. |
| GET | HTTP-метод для получения данных с сервера — ты просишь, сервер отдаёт. |
| POST | HTTP-метод для отправки данных на сервер — ты передаёшь информацию, сервер её обрабатывает. |
| REST | Стиль построения API, в котором каждый URL представляет ресурс, а действия задаются HTTP-методами. |
| SDK (Software Development Kit) | Готовая библиотека кода, которая упрощает работу с API — не нужно вручную формировать запросы. |
| Клиент API | Программа или код, который отправляет запросы к API — то есть твоё приложение. |
| Сервер | Компьютер, который принимает запросы, обрабатывает их и отправляет ответы — например, сервер Claude. |
В следующем уроке — Первый вызов Claude API. Ты напишешь код, который отправит запрос к Claude и получит ответ. Твой первый AI-запрос из кода!