Урок 3. API и чтение кода

Откройте PowerShell. Мы отправим запрос к бесплатному тестовому API jsonplaceholder — это «песочница» для тренировки запросов (не требует ключа).

Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/todos/1"

Вы увидите таблицу с полями userId, id, title, completed. PowerShell распознал JSON и показал его таблицей.

Теперь запросите все задачи и посчитайте их количество:

$todos = Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/todos"
$todos.Count

Сколько вернулось? Должно быть 200. Переменная $todos — это коробка, куда мы сложили ответ, чтобы потом с ним работать.

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

$todos[0]
$todos[-1]

Вы только что сделали то же, что и AI-скрипт: отправили запрос, получили JSON, достали поле из ответа.

API могут принимать параметры — как фильтр в интернет-магазине. Параметры идут после знака ?:

Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/todos?userId=1"

Вы получили задачи только пользователя с ID=1. Попробуйте userId=2, userId=3.

Теперь попробуйте другой публичный API — поиск книг:

$books = Invoke-RestMethod -Uri "https://openlibrary.org/search.json?q=learning+design"
$books.docs.Count
$books.docs[0].title

Вы получили список книг по запросу "learning design" и посмотрели название первой. Символ ? отделяет адрес от параметров, = — название параметра от значения, + заменяет пробел.

OpenRouter — это сервис, через который можно обращаться к сотням AI-моделей по единому API. Нам он понадобится в следующем модуле.

Откройте в браузере: openrouter.ai/docs/quick-start

Ваша задача — не понять всё, а найти ответы на три вопроса (запишите в блокнот):

1. Какой URL для отправки запроса? (Подсказка: ищите POST и api/v1/)
2. Какое поле в ответе содержит текст, который сгенерировала модель? (Подсказка: ищите choices и content)
3. Как называется заголовок для передачи API-ключа? (Подсказка: ищите слово Authorization)

Теперь откройте раздел Models: openrouter.ai/models

Найдите одну бесплатную модель (с пометкой "Free") и запишите её полное название (например, google/gemini-2.0-flash-001).

Это тренировка навыка «читать документацию» — самого важного для разработчика. Не бойтесь, если непонятно: ваша цель — найти три конкретных факта, а не понять всё.

GET-запросы просто читают. POST — отправляют данные на сервер. Попробуем на тестовом API:

$body = @{
    title  = "Моя тестовая задача"
    body   = "Учусь отправлять POST-запросы"
    userId = 1
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -Method Post -Body $body -ContentType "application/json"
$response

Вы увидите созданный объект с полем id: 101 — сервер подтвердил создание.

Разбор команды по частям:

• @{ ... } — создали хеш-таблицу (словарь) с данными
• | ConvertTo-Json — превратили в JSON-строку
• -Method Post — указали метод
• -Body $body — передали данные
• -ContentType "application/json" — сказали серверу: «Я посылаю JSON»

Специально сделаем неправильные запросы, чтобы увидеть статус-коды:

1. Несуществующая страница (404):

try { Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/ne-postoi" } catch { $_.Exception.Message }

2. Битый JSON (400):

try { Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -Method Post -Body '{"title": "oops' -ContentType "application/json" } catch { $_.Exception.Message }

Конструкция try { ... } catch { ... } — это «попробуй выполнить, а если ошибка — покажи сообщение, но не падай».

Запомните: если пришёл 4xx — проверьте свой запрос. Если 5xx — подождите и попробуйте позже, проблема не у вас.

Ниже — скрипт на Python, который обращается к AI-модели через OpenRouter API. Ваша задача — не написать такой же, а прочитать и объяснить, что он делает.

import os
import requests
import json

# --- 1. Настройки ---
API_KEY = os.environ.get("OPENROUTER_API_KEY")
MODEL = "google/gemini-2.0-flash-001"
API_URL = "https://openrouter.ai/api/v1/chat/completions"

# --- 2. Запрос ---
system_prompt = "Ты — L&D-методист. Отвечай коротко, по делу."
user_question = "Объясни разницу между RAG и fine-tuning одной фразой."

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": MODEL,
    "messages": [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_question}
    ],
    "temperature": 0.3,
    "max_tokens": 100
}

# --- 3. Отправка ---
response = requests.post(API_URL, headers=headers, json=payload)

# --- 4. Обработка ответа ---
if response.status_code == 200:
    answer = response.json()
    print(answer["choices"][0]["message"]["content"])
else:
    print(f"Ошибка {response.status_code}: {response.text}")

Задание: откройте Блокнот и напишите ответы на вопросы в свободной форме:

1. Что на входе? — Какие данные получает скрипт перед запуском?
2. Что внутри? — Перечислите основные блоки (1–4), которые вы видите. Опишите назначение каждого блока своими словами.
3. Что на выходе? — Что произойдёт, если скрипт выполнится успешно? Что — если ключ не указан?
4. Какие строчки вам непонятны? — Выпишите 1–3 строки. Попробуйте догадаться из контекста.
5. Что такое temperature в payload? — Догадайтесь из контекста.

Не подсматривайте ответы, пока не напишете свои. Дальше — разбор.

Вернитесь в папку вашего учебного проекта. Создайте папку api-demo и внутри — файл openrouter-test.md:

mkdir api-demo
ni api-demo\openrouter-test.md

Откройте файл в редакторе и запишите:

1. Свой первый GET-запрос — URL и что вернулось.
2. Свой первый POST-запрос — какой JSON отправили и какой id присвоил сервер.
3. Ответы на пять вопросов из Упражнения 6 (чтение кода).
4. Три факта, которые вы нашли в документации OpenRouter.
5. 2–3 предложения своими словами: что я понял(а) про API.

Сохраните, закройте. Проверьте через терминал:

cat api-demo\openrouter-test.md

Если у вас есть желание и 15 минут — выполните бонусное упражнение. Оно не обязательно, но даст вам первый реальный опыт общения с AI-моделью через API.

Что нужно:

1. Зайдите на openrouter.ai/keys, зарегистрируйтесь (бесплатно) и создайте API-ключ.
2. Положите немного денег на баланс ($1–2, этого хватит на десятки запросов).
3. Вернитесь в PowerShell. НЕ вставляйте ключ в код — задайте переменную окружения:

$env:OPENROUTER_API_KEY = "ваш-ключ-сюда"

Теперь отправьте запрос к бесплатной модели:

$headers = @{
    "Authorization" = "Bearer $env:OPENROUTER_API_KEY"
    "Content-Type"  = "application/json"
}

$body = @{
    model    = "google/gemini-2.0-flash-001"
    messages = @(
        @{ role = "user"; content = "Привет! Напиши хайку про осень." }
    )
} | ConvertTo-Json -Depth 3

$response = Invoke-RestMethod -Uri "https://openrouter.ai/api/v1/chat/completions" -Method Post -Headers $headers -Body $body
$response.choices[0].message.content

Если всё получилось — вы только что отправили свой первый запрос к AI-модели не через чат-интерфейс, а напрямую через API.

Если что-то пошло не так — проверьте:

• Правильно ли скопирован ключ (весь, без пробелов в начале/конце)
• Есть ли деньги на балансе OpenRouter
• Доступна ли модель google/gemini-2.0-flash-001 (бесплатная, но иногда с задержкой)

Важно: после эксперимента закройте PowerShell (ключ удалится из переменной окружения) и никогда не публикуйте ключ в Git.