Аналітика аудиторії

Вкажіть тему або сайт бренду й отримайте те, що реальні люди говорять про це в публічних коментарях і обговореннях: слова, якими вони користуються, запитання, які вони ставлять, чого вони очікують від продукту, у чому не погоджуються з авторами, чого бракує в наявному контенті та які теми набирають популярності. Кожен висновок підраховано за незалежними гілками обговорень і пов'язано з коментарями, з яких його взято, тож ваша команда або ваша власна модель ШІ може його перевірити.

Одне дослідницьке завдання читає одну вибірку до 500 прийнятих коментарів і перетворює її на всі дев'ять продуктів (різних поглядів на ті самі дані), наведених нижче. Кожне завдання містить усі дев'ять; ви можете вказати той, що для вас найважливіший.

Значення `products`	Що ви отримуєте
`audience_keywords`	фрази, якими користується аудиторія, згруповані за змістом (частота в коментарях, а не пошуковий обсяг)
`audience_questions`	повторювані запитання з варіантами формулювань, етапом воронки та позначкою, чи автори вже на них відповідають
`website_requirements`	що сайт має сказати або показати: функції, інтеграції, ціни, докази, заперечення; кожен пункт позначено як `must`, `should` або `could`
`comparison_intelligence`	як аудиторія порівнює названі продукти: критерії, причини переходу, прогалини в довірі
`content_brief_from_audience`	бриф для контенту: робоча назва, розділи, запитання, на які треба відповісти, заперечення, FAQ, твердження, яких слід уникати
`audience_content_gaps`	попит, який наявні відповіді покривають погано, із зазначенням матеріалу, який варто створити
`creator_vs_audience_gap`	де коментатори не погоджуються з твердженнями авторів, ставлять їх під сумнів або додають до них умови
`buyer_expectations`	що покупці вважають само собою зрозумілим (`must_have`) і що вирізняє продукт (`differentiator`)
`trend_from_audience`	теми зі статусом `rising`, `stable` або `declining`, нормалізовані на 1 000 релевантних гілок обговорень

Аналітика аудиторії вмикається для ключа на запит: напишіть на support@omev.be. Завдання списуються зі звичайного балансу ключа.

Ціна

Що	Ціна
Одне дослідницьке завдання, усі дев'ять продуктів	$0.99

Ціна списується один раз, коли jobs/create приймає завдання. Завдання, що завершилося зі статусом NO_DATA (замало релевантних публічних обговорень), безкоштовне; завдання COMPLETED_PARTIAL оплачується повністю. Повторний виклик jobs/create з тим самим idempotency_key повертає те саме завдання й повторно не оплачується. estimate, jobs/get, jobs/result і jobs/cancel безкоштовні.

Спочатку перевірте запит

estimate перевіряє тіло запиту, показує нормалізований обсяг дослідження та ціну і не запускає жодної роботи. Він приймає те саме тіло, що й jobs/create; idempotency_key тут необов'язковий.

curl -sS https://llmapi.omev.be/v1/audience-intelligence/estimate \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "1.2",
    "products": ["audience_questions", "buyer_expectations"],
    "topic": {"name": "waterproof sneakers for commuting"},
    "audience": {"description": "city commuters who walk in the rain"},
    "scope": {"platforms": ["youtube", "reddit"], "languages": ["en"], "markets": ["US"]}
  }'

{
  "request_id": "…",
  "supported": true,
  "normalized_scope": {
    "markets": ["US"], "languages": ["en"],
    "from": "2026-03-31T10:00:00Z", "to": "2026-09-27T10:00:00Z",
    "platforms": ["reddit", "youtube"]
  },
  "sample": {"target_accepted_comments": 500, "consent_required": false},
  "quote": {
    "customer_cost_usd": "0.99000000", "currency": "USD", "tier": "single",
    "products": ["audience_content_gaps", "audience_keywords", "audience_questions", "…"],
    "valid_until": "2026-09-27T11:00:00Z"
  },
  "estimated_completion_seconds": {"min": 20, "typical": 240, "max": 1800},
  "warnings": []
}

quote.customer_cost_usd — це ціна завдання. supported: false або примітка в warnings означає, що джерело даних тимчасово недоступне: спробуйте пізніше.

Запуск дослідницького завдання

curl -sS https://llmapi.omev.be/v1/audience-intelligence/jobs/create \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "1.2",
    "idempotency_key": "acme-17-sneakers-2026-09",
    "products": ["audience_questions", "buyer_expectations"],
    "topic": {"name": "waterproof sneakers for commuting"},
    "audience": {"description": "city commuters who walk in the rain"},
    "scope": {"platforms": ["youtube", "reddit"], "languages": ["en"], "markets": ["US"]}
  }'

Поле	Обов'язкове	Значення
`schema_version`	так	`1.0`, `1.1` або `1.2`; використовуйте `1.2`
`idempotency_key`	так для `jobs/create`	8–200 символів; повторне надсилання повертає те саме завдання замість запуску нового
`product` або `products`	ні	продукт, який для вас найважливіший, або список продуктів із таблиці вище; не більше одного з двох полів. Завдання в будь-якому разі будує всі дев'ять
`topic.name`	`name` або `website_url`	тема, 3–300 символів
`topic.website_url`	`name` або `website_url`	сайт бренду; назву бренду буде зчитано із сайту
`topic.description`	ні	до 2 000 символів, що уточнюють тему
`topic.include_terms`, `topic.exclude_terms`	ні	до 50 термінів у кожному, щоб розширити або звузити те, що вважається релевантним
`audience.description`	ні	кого ви хочете почути, 3–2 000 символів
`audience.roles`, `audience.company_size`	ні	додаткові підказки для бізнес-аудиторій
`scope.platforms`	ні	будь-які з `youtube`, `reddit`, `linkedin`, `tiktok`, `instagram`, `threads`, `facebook`, `twitter`, `web`
`scope.languages`	ні	мови коментарів, за замовчуванням `["en"]`, до 10
`scope.markets`	ні	коди країн, наприклад `["US"]`; порожнє значення означає весь світ
`scope.period`	ні	`{"days": 7…365}` (за замовчуванням 180) або `{"from": "…Z", "to": "…Z"}` в UTC, з інтервалом 7–365 днів
`entities`	ні	продукти або компанії для порівняння: `{"name": "…", "kind": "product", "aliases": ["…"]}`; без них `comparison_intelligence` використовує порівняння, знайдені в коментарях
`creator_seeds`	ні	канали або спільноти, які треба прочитати: `{"platform": "youtube", "url": "https://…"}`; спільнота Reddit — це `https://www.reddit.com/r/<name>`, окрема гілка Reddit — це URL гілки з `"kind": "publication"`
`source_mode`	ні	`discover` (за замовчуванням) знаходить джерела самостійно; `seeds_only` читає лише ваші `creator_seeds`
`data_mode`	ні	`refresh_if_needed` (за замовчуванням) повторно використовує свіжі дані для того самого обсягу дослідження й доповнює їх; `fresh` збирає дані заново; `corpus_only` використовує лише дані, уже зібрані для вашого облікового запису
`output`	ні	`max_signals` (1–100, за замовчуванням 30), `max_evidence_per_signal` (1–20, за замовчуванням 5), `include_short_quotes` і `include_markdown` (обидва за замовчуванням `true`)
`limits`	ні	`max_creators` (за замовчуванням 30, до 100), `max_publications` (за замовчуванням 300, до 1 000), `max_comments` (за замовчуванням 15,000, до 50 000), `deadline_seconds` (за замовчуванням 1,800, 60–3 600)

Важливі значення за замовчуванням:

Якщо задано лише topic.website_url, завдання читає всі платформи, а також незалежні форуми й блоги.
Якщо задано topic.name без scope.platforms, завдання читає лише YouTube. Перелічіть потрібні вам платформи.

Відповідь — 202 із завданням:

{
  "request_id": "…",
  "job": {"id": "aij_…", "status": "QUEUED", "stage": "VALIDATE", "progress": 0,
          "created_at": "…", "deadline_at": "…", "currency": "USD", "warnings": []},
  "idempotent_replay": false,
  "poll_after_seconds": 3
}

Відстеження завдання

Завдання зазвичай триває кілька хвилин і зупиняється не пізніше, ніж спливе limits.deadline_seconds. Опитуйте статус кожні 5–10 секунд.

curl -sS https://llmapi.omev.be/v1/audience-intelligence/jobs/get \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "aij_…"}'

job.progress змінюється від 0 до 100; job.coverage_so_far показує, скільки даних зібрано на цей момент.

`status`	Значення
`QUEUED`, `RUNNING`	очікування або виконання
`WAITING_PROVIDER`, `RETRY_WAIT`	очікування джерела даних або повторна спроба; продовжуйте опитування
`COMPLETED`	звіт готовий
`COMPLETED_PARTIAL`	звіт готовий, але вибірка менша, ніж планувалося; див. `warnings` і `product_readiness`
`NO_DATA`	не знайдено достатньо релевантних публічних обговорень; звіту немає
`BUDGET_EXHAUSTED`, `EXPIRED`, `FAILED`	завдання завершилося без повного звіту; причину пояснюють `stop_reason` і `public_error_code`
`CANCELLED`	ви скасували завдання

Щоб зупинити завдання, надішліть {"job_id": "aij_…"} на /v1/audience-intelligence/jobs/cancel. Відповідь — 202, поки завдання зупиняється, або 200, якщо його вже скасовано.

Завантаження звіту

curl -sS https://llmapi.omev.be/v1/audience-intelligence/jobs/result \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "aij_…"}'

До завершення завдання виклик повертає 409 JOB_NOT_READY. Завдання, що завершилося без звіту (наприклад, NO_DATA), повертає {"job": {…}, "report": null}.

Звіт:

Поле	Вміст
`status`, `products`	фінальний статус і побудовані продукти
`product_results`	один об'єкт на продукт, ключ — назва продукту; кожен містить список `items` у форматі цього продукту
`product_readiness`	для кожного продукту: `sufficient`, `insufficient_sample` або `no_evidence`, із поясненням причини
`summary`	короткий підсумок простою мовою
`research_question`, `scope`	що досліджувалося: тема, аудиторія, період, запитані та фактично охоплені платформи
`methodology`	чиї думки представляє вибірка, як відбиралися джерела, обмеження
`coverage`	скільки коментарів зібрано, прийнято й виключено, унікальні гілки обговорень, платформи, найбільша частка одного джерела
`signals`	базові висновки: `type` (запитання, больова точка, очікування, заперечення, порівняння, тренд…), `label`, `strength` (`anecdotal`, `emerging`, `recurring`, `strong`), лічильники та `evidence_ids`
`evidence`	коментарі, на яких ґрунтуються висновки: платформа, публікація, текст коментаря, релевантність
`contradictions`, `warnings`	висновки, що суперечать один одному, і все, що обмежує звіт
`rendered_markdown`	той самий звіт у форматі Markdown, коли `output.include_markdown` має значення `true`

Лічильники рахують унікальні гілки обговорень, а не окремі коментарі, тож одна гучна гілка не може штучно роздути тему. Сприймайте висновки anecdotal як підказки, а не як факти.

Звіти доступні протягом 90 днів після завершення завдання; після цього виклик повертає 410 RESULT_EXPIRED.

Вузькі теми

Завдання розраховане на 500 прийнятих коментарів — це максимум. Для ніші, де стільки коментарів немає, можна погодитися на меншу вибірку з 200–499 коментарів за тією самою ціною: встановіть sample_policy.mode у значення narrow, sample_policy.target_accepted_comments — у цільову кількість, і додайте sample_policy.narrow_topic_consent із зареєстрованим текстом згоди, часом її прийняття та версією політики. Перш ніж вбудовувати це у свій продукт, зверніться на support@omev.be за точним формулюванням.

Помилки

Код	Коли
`401`	ключ API відсутній або недійсний
`403`	ключ не може використовувати цей продукт
`404`	невідоме завдання або завдання, що належить іншому обліковому запису
`409 JOB_NOT_READY`	звіт запитано до завершення завдання
`409 IDEMPOTENCY_CONFLICT`	`idempotency_key` уже використано з іншим тілом запиту
`409 JOB_ALREADY_TERMINAL`	скасування надіслано для завдання, яке вже завершилося
`410 RESULT_EXPIRED`	звіт старший за 90 днів
`422 INVALID_ARGUMENT`	поле відсутнє або виходить за допустимі межі; тіло відповіді називає це поле
`429`	забагато запитів або забагато завдань у черзі; повторіть спробу після короткої паузи

Для 409, 410 і 422 тіло відповіді містить наведений вище код сервісу. Інші статуси повертають загальне тіло помилки, див. Помилки.

Ціна​

Спочатку перевірте запит​

Запуск дослідницького завдання​

Відстеження завдання​

Завантаження звіту​

Вузькі теми​

Помилки​