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

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

• Карточка товара или объявления: название, цена, наличие, характеристики.
• Списки: вакансии, тарифы, участники, объекты каталога — схемой 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 ссылок с одной схемой. Страницы обрабатываются параллельно.

{
  "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 за факт со страницы.