Извлечение по схеме

Когда использовать

• Карточка товара или объявления: название, цена, наличие, характеристики.
• Списки: вакансии, тарифы, участники, объекты каталога - схемой type: "array".
• Метаданные статьи для индекса: автор, дата публикации, теги, заголовки разделов.
• Мониторинг одного значения на нескольких страницах - батчем urls с одной схемой.

Если нужен весь текст страницы, а разбор вы делаете сами - берите чтение страницы: это 1 кредит вместо 4. Если нужно найти страницы по теме - веб-поиск.

Пример запроса

curl -X POST https://srezai.ru/api/v1/extract \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer srz_live_ВАШ_КЛЮЧ" \
  -d '{
    "url": "https://example.com/product/42",
    "schema": {
      "type": "object",
      "properties": {
        "name":    { "type": "string",  "description": "название товара" },
        "price":   { "type": "number",  "description": "цена в рублях" },
        "inStock": { "type": "boolean", "description": "есть в наличии" }
      },
      "required": ["name", "price"]
    }
  }'

Параметры тела

Сокращённая форма

Полный JSON Schema писать не обязательно. Схему можно задать словарём «поле → тип» - это короче и заметно устойчивее, когда схему составляет модель:

{
  "url": "https://example.com/product/42",
  "schema": {
    "name": "string",
    "price": "number",
    "inStock": "boolean?",
    "tags": "string[]"
  }
}

{
  "schema": {
    "title": "string",
    "author": { "name": "string", "url": "string?" },
    "tags": "string[]"
  }
}

Обе формы можно смешивать: как только у узла есть поле type, он читается как обычный JSON Schema. Так что сокращённую схему всегда можно дополнить в нужном месте полным описанием поля с description и enum.

Полная форма

Поддерживается практичное подмножество JSON Schema:

• type: object, array, string, number, integer, boolean. Корень схемы - object или array.
• properties и required - для объектов, items - для массивов.
• description - короткое пояснение к полю. Заметно повышает точность: «цена в рублях без скидки» отрабатывает лучше, чем просто price.
• enum - список допустимых значений для поля.

Ограничения: до 40 полей и до 4 уровней вложенности, до 100 элементов в массиве результата. Конструкции вне подмножества ($ref, oneOf, pattern, условные схемы) вернут 400 с кодом schema_invalid и указанием проблемного пути в схеме - например schema.properties.price.type.

Схема с корнем array - типовой случай «собери список»:

{
  "url": "https://example.com/jobs",
  "schema": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "title":  { "type": "string" },
        "city":   { "type": "string" },
        "salary": { "type": "integer", "description": "верхняя граница, ₽/мес" },
        "remote": { "type": "boolean" }
      },
      "required": ["title"]
    }
  },
  "instruction": "только вакансии для инженеров"
}

Ответ

{
  "url": "https://example.com/product/42",
  "title": "Кофемолка X200 - купить в магазине",
  "data": {
    "name": "Кофемолка X200",
    "price": 7490,
    "inStock": true
  },
  "missing": [],
  "truncated": false,
  "meta": {
    "tookMs": 6120,
    "sourceChars": 8213,
    "model": "gemini-3-flash-lite",
    "inputTokens": 2480,
    "outputTokens": 64
  }
}

Несколько страниц за раз

Вместо url можно передать urls - до 5 ссылок на бесплатном тарифе и до 10 на подписке PRO, с одной схемой на все страницы. Страницы обрабатываются параллельно, лишние адреса отбрасываются и попадают в meta.skipped.

{
  "urls": [
    "https://example.com/product/42",
    "https://example.com/product/43"
  ],
  "schema": {
    "type": "object",
    "properties": {
      "name":  { "type": "string" },
      "price": { "type": "number" }
    },
    "required": ["price"]
  }
}

Ответ - массив pages в порядке переданных ссылок: успешные с полями data/missing/meta, неудачные - с error и code (ssrf_blocked, read_failed, extract_failed). Одна упавшая ссылка не отменяет остальные: статус остаётся 200. Каждая страница тарифицируется отдельно и отдельной строкой попадает в историю запросов.

Через MCP: extract

Тот же функционал доступен агенту как инструмент extract MCP-сервера - с теми же параметрами url/urls, schema, instruction, engine. Результат приходит блоком json; ненайденные обязательные поля перечисляются отдельной строкой, чтобы агент не принял null за факт со страницы.