Аналітична довідка про компанію

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

Одна довідка відповідає одній меті:

focus	Призначення
reddit_promotion	просування компанії на Reddit: важливі спільноти, пошукові запити, що виводять на релевантні обговорення, запитання та заперечення покупців, безпечні твердження
seo_web	просування компанії в пошуку: комерційні запити за наміром, хто займає видачу сьогодні, прогалини в контенті
competitor_intel	вивчення компанії як конкурента: позиціонування, ціни, функції, на що скаржаться її клієнти

Друга мета для тієї самої компанії — це окремий запит. Протягом 7 днів він повторно використовує прочитання сайту та профіль компанії з першої довідки, тому стартує швидше, а обидві довідки описують компанію однаково; завдання показує "core_reused": true.

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

Глибина та ціна

depth	Ціна за доставлену довідку	Що входить
standard (за замовчуванням)	$0.99	довідка про компанію без голосу аудиторії: 3–6 конкурентів і стандартний пошук; розділи з голосом покупців позначено як не включені
extended	$1.99	усе зі standard, а також голос аудиторії (до 300 прочитаних коментарів покупців, для вузьких ніш додаються форуми та інші джерела), 7–8 конкурентів і ширший пошук

Ви платите один раз за довідку, коли вперше завантажуєте готовий результат, залежно від її повноти:

Повнота довідки	Оплата
75% і більше	повна ціна
40–74%	70% ціни
15–39%	30% ціни
менше 15%	безкоштовно

Часткова сума округлюється униз до цілих центів. Завдання показує completeness_percent і charged_usd. Довідка, що завершилася помилкою, сайт, який ми не можемо прочитати, скасоване завдання та повторні завантаження тієї самої довідки не оплачуються. Звіт за доменом містить розширену довідку разом із дослідженням спільнот і видимості в ШІ.

Запуск довідки

curl -sS https://llmapi.omev.be/v1/cig/jobs/create \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://vessi.com",
    "focus": "reddit_promotion",
    "depth": "standard",
    "client_ref": "acme-client-17",
    "idempotency_key": "acme-17-vessi-reddit-2026-09"
  }'

Поле	Обов'язкове	Значення
url	так	вебсайт компанії; публічна адреса http/https
focus	так	одне зі значень reddit_promotion, seo_web, competitor_intel
depth	ні	standard (за замовчуванням) або extended
market	ні	країна або регіон, наприклад "US", або список до 10 значень, наприклад ["EU", "DE"]
language	ні	код мови, наприклад "en", або список до 6 кодів, наприклад ["en", "de"]
voice	ні	від чийого імені написано запропоновані відповіді: brand (за замовчуванням) або community_member; OmevAI нічого не публікує
max_age_days	ні	1–1830; гілки обговорень, старші за цей вік, не потрапляють до плану дій
client_ref	ні	ваша власна мітка кінцевого клієнта (для агенцій: розподіл витрат за клієнтами)
idempotency_key	ні	8–200 символів; повторне надсилання повертає те саме завдання замість запуску нового
callback_url	ні	публічна адреса https, яку ми викликаємо, коли довідку завершено (див. Сповіщення)
callback_secret	ні	16–200 символів; з ним кожне сповіщення підписується

Перед запуском довідки ми перевіряємо, чи покриває баланс вашого ключа її ціну. Якщо ні, у відповідь надходить 402 INSUFFICIENT_BALANCE і нічого не запускається.

У відповідь надходить 202 із завданням:

{
  "job": {"id": "cig_…", "status": "queued", "stage": "", "focus": "reddit_promotion",
          "depth": "standard", "client_ref": "acme-client-17", "charged_usd": 0},
  "idempotent_replay": false,
  "poll_after_seconds": 10
}

Багато сайтів одночасно

Надсилайте до 50 довідок в одному виклику. Кожен елемент приймає ті самі поля, що й окрема довідка.

curl -sS https://llmapi.omev.be/v1/cig/jobs/batch \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"url": "https://vessi.com", "focus": "reddit_promotion", "client_ref": "acme-17"},
      {"url": "https://vessi.com", "focus": "seo_web", "client_ref": "acme-17"},
      {"url": "https://allbirds.com", "focus": "competitor_intel", "client_ref": "acme-17",
       "callback_url": "https://hooks.example.com/omev", "callback_secret": "a-long-random-secret"}
    ]
  }'

У відповідь надходить 202 з одним записом на кожен елемент, у тому самому порядку. Елемент із помилкою отримує власне поле error і не зупиняє інші:

{
  "items": [
    {"index": 0, "job": {"id": "cig_…", "status": "queued", …}, "idempotent_replay": false},
    {"index": 1, "job": {"id": "cig_…", "status": "queued", …}, "idempotent_replay": false},
    {"index": 2, "error": {"code": "INVALID_URL", "message": "…"}}
  ],
  "poll_after_seconds": 10
}

Баланс має покривати всі коректні елементи разом; інакше виклик повертає 402 INSUFFICIENT_BALANCE і жоден елемент не запускається. Дві мети для того самого сайту в одному виклику використовують одне спільне прочитання сайту.

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

Підготовка довідки standard триває 10–25 хвилин, extended — до приблизно години: сервіс читає сайт, виконує пошук, перевіряє конкурентів і читає обговорення покупців. Перевіряйте статус кожні 15–30 секунд.

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

status спочатку має значення queued, потім running, а далі одне з completed, partial, failed, cancelled. Під час виконання stage показує поточний етап роботи, наприклад site_read, business_mix, profile_extract, research_plan, market_frame, competitors, search, communities, audience, claim_verify, synthesis, thread_tone, moderation. Довідка, яка повторно використовує попереднє прочитання сайту, показує site_core_reused замість перших трьох. Сприймайте цей перелік як довідковий: можуть з'являтися нові етапи.

partial означає доставлену довідку, у якій певну частину не завершено; причину вказано в evidence_base.limitations, а evidence_base.coverage.completeness показує кожен розділ із тим, що знайдено, його ціллю та мінімумом. У разі failed поле error.code пояснює причину, наприклад site_unreadable, коли сайт блокує автоматизовані відвідування.

Щоб зупинити завдання, надішліть те саме тіло запиту на /v1/cig/jobs/cancel.

Сповіщення про готовність довідки

Якщо вказано callback_url, перевіряти статус не потрібно. Коли завдання переходить у стан completed, partial, failed або cancelled, ми надсилаємо POST на цю адресу:

{"event": "cig.job.finished", "job": {"id": "cig_…", "status": "completed", …}}

Заголовок	Значення
X-Omev-Event-Id	ідентифікатор завдання; за ним можна відкидати повторні доставки
X-Omev-Signature	sha256= і шістнадцятковий HMAC-SHA256 необробленого тіла запиту, обчислений з вашим callback_secret (надсилається, лише якщо ви вказали секрет)

Відповідайте будь-яким статусом 2xx. Якщо виклик не вдався, ми робимо ще дві спроби: через 10 секунд і через 60 секунд. Результат показано в job.callback_status. Сповіщення містить лише завдання; довідку завантажуйте, як зазвичай, через /v1/cig/jobs/result.

Перевіряйте підпис, перш ніж довіряти тілу запиту:

import hashlib, hmac

def is_from_omev(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

Завантаження довідки

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

Відповідь містить job, profile (повна довідка) і stage1 (стислий підсумок тієї самої довідки з десяти полів). Доки завдання не завершено, виклик повертає 409 JOB_NOT_READY.

Довідка складається з дев'яти розділів:

Розділ	Вміст
meta	мета, глибина, цільова URL-адреса, ринок, час генерації
company	продукт, позиціонування, структура бізнесу, функції, пропозиція, сигнали довіри
market	профіль покупця (ICP), контекст ринку, ключові слова, запити покупців
problems	проблеми, які вирішує бренд, розчарування в категорії
brand_perception	скарги, похвала та згадки, знайдені в публічних джерелах
competition	конкуренти (direct, adjacent, status_quo) із поясненням, чому кожен із них є конкурентом
audience	запитання, заперечення й очікування покупців, дослівні цитати покупців
playbook	план для обраної мети: спільноти, пошукові запити, меседжі, наступні кроки, обмеження щодо тверджень
evidence_base	усі джерела й цитати, на які спирається довідка, показники охоплення, обмеження

Елементи містять evidence_ids, що вказують на записи в evidence_base.evidence, де кожен запис має url джерела та точну цитату quote. Твердження позначено як stated (так стверджує сама компанія), observed (помічено в незалежних джерелах) або inferred (наш висновок). Передаючи довідку ШІ-моделі, вкажіть їй подавати як факти лише елементи stated і observed та ніколи не використовувати нічого з переліку playbook.reply_guardrails.do_not_claim.

Помилки

Код	Коли виникає
401	ключ API відсутній або недійсний
402 INSUFFICIENT_BALANCE	баланс ключа не покриває довідку (або всі коректні елементи виклику для кількох сайтів)
404 JOB_NOT_FOUND	невідоме завдання або завдання, що належить іншому обліковому запису
409 JOB_NOT_READY	результат запитано до завершення завдання
422 INVALID_URL	адреса не є публічним вебсайтом
422 INVALID_FOCUS, 422 INVALID_DEPTH, 422 INVALID_VOICE	значення поза наведеними вище переліками
422 INVALID_MARKET, 422 INVALID_LANGUAGE, 422 INVALID_MAX_AGE, 422 INVALID_IDEMPOTENCY_KEY	поле поза допустимими межами: понад 10 ринків, понад 6 кодів мов, вік поза 1–1830 днями, ключ поза 8–200 символами
422 INVALID_CALLBACK_URL, 422 INVALID_CALLBACK_SECRET	адреса для сповіщень не є публічною адресою https або секрет не має довжини 16–200 символів
422 INVALID_REQUEST, 422 BATCH_TOO_LARGE	виклик для кількох сайтів без елементів, з елементом, який не є об'єктом, або з понад 50 елементами
429	забагато запитів; повторіть спробу після короткої паузи

Кожна помилка має однаковий вигляд: {"error": {"code": "INVALID_FOCUS", "message": "…"}}. Помилки 401 через неправильний ключ і 429 працюють однаково для всіх API OmevAI; їхній формат описано в розділі Помилки.