Raport wywiadowczy o firmie

Podaj adres strony internetowej i jeden cel, a otrzymasz uporządkowany raport o firmie, z którym Twój własny model AI lub zespół może od razu pracować: co firma sprzedaje i komu, rynek i język klientów, rzeczywistych konkurentów, o co klienci pytają i jakie mają zastrzeżenia w publicznych dyskusjach, a także gotowy plan działania dla wybranego celu. Każda informacja faktograficzna zawiera odnośnik do dowodu, z którego pochodzi.

Jeden raport służy jednemu celowi:

focus	Przeznaczenie
reddit_promotion	promocja firmy na Reddicie: istotne społeczności, zapytania wyszukiwania prowadzące do trafnych wątków, pytania i zastrzeżenia klientów, bezpieczne stwierdzenia
seo_web	promocja firmy w wyszukiwarkach: zapytania komercyjne według intencji, kto dziś zajmuje wyniki, luki w treściach
competitor_intel	analiza firmy jako konkurenta: pozycjonowanie, ceny, funkcje, na co skarżą się jej klienci

Drugi cel dla tej samej firmy to drugie zapytanie. W ciągu 7 dni korzysta ono ponownie z odczytu strony i profilu firmy z pierwszego raportu, dzięki czemu startuje szybciej, a oba raporty opisują firmę tak samo; zadanie pokazuje "core_reused": true.

Wywiad o firmie jest włączany dla klucza na życzenie: napisz na support@omev.be. Koszt raportu jest pobierany ze zwykłego salda klucza.

Głębokość i cena

depth	Cena za dostarczony raport	Co zawiera
standard (domyślnie)	$0.99	raport o firmie bez głosu odbiorców: 3–6 konkurentów i standardowe wyszukiwanie; sekcje z głosem klientów są oznaczone jako nieuwzględnione
extended	$1.99	wszystko z standard, a do tego głos odbiorców (do 300 przeczytanych komentarzy klientów, przy wąskich niszach także fora i inne źródła), 7–8 konkurentów i szersze wyszukiwanie

Płacisz raz za raport, przy pierwszym pobraniu gotowego wyniku, zależnie od jego kompletności:

Kompletność raportu	Opłata
75% lub więcej	pełna cena
40–74%	70% ceny
15–39%	30% ceny
poniżej 15%	bezpłatnie

Częściowa opłata jest zaokrąglana w dół do pełnych centów. Zadanie pokazuje completeness_percent i charged_usd. Nie pobieramy opłat za raport zakończony błędem, stronę, której nie możemy odczytać, anulowane zadanie ani za ponowne pobrania tego samego raportu. Raport domeny zawiera rozszerzony raport o firmie wraz z badaniem społeczności i widoczności w AI.

Uruchomienie raportu

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"
  }'

Pole	Wymagane	Znaczenie
url	tak	strona internetowa firmy; publiczny adres http/https
focus	tak	jedna z wartości reddit_promotion, seo_web, competitor_intel
depth	nie	standard (domyślnie) lub extended
market	nie	kraj lub region, np. "US", albo lista do 10 pozycji, np. ["EU", "DE"]
language	nie	kod języka, np. "en", albo lista do 6 kodów, np. ["en", "de"]
voice	nie	w czyim imieniu są pisane proponowane odpowiedzi: brand (domyślnie) lub community_member; OmevAI nigdy niczego nie publikuje
max_age_days	nie	1–1830; wątki dyskusji starsze niż ta wartość są pomijane w planie działania
client_ref	nie	Twoja własna etykieta klienta końcowego (agencje: podział wydatków na klientów)
idempotency_key	nie	8–200 znaków; ponowne użycie zwraca to samo zadanie zamiast uruchamiać nowe
callback_url	nie	publiczny adres https, który wywołujemy po ukończeniu raportu (zobacz Powiadomienie)
callback_secret	nie	16–200 znaków; z nim każde powiadomienie jest podpisane

Przed uruchomieniem raportu sprawdzamy, czy saldo Twojego klucza pokrywa jego cenę. Jeśli nie, odpowiedź to 402 INSUFFICIENT_BALANCE i nic nie zostaje uruchomione.

Odpowiedź to 202 z zadaniem:

{
  "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
}

Wiele stron naraz

Wyślij do 50 raportów w jednym wywołaniu. Każdy element przyjmuje te same pola co pojedynczy raport.

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"}
    ]
  }'

Odpowiedź to 202 z jednym wpisem na każdy element, w tej samej kolejności. Element z błędem otrzymuje własne error i nie zatrzymuje pozostałych:

{
  "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
}

Saldo musi pokrywać wszystkie poprawne elementy łącznie; w przeciwnym razie wywołanie zwraca 402 INSUFFICIENT_BALANCE i żaden element nie zostaje uruchomiony. Dwa cele dla tej samej strony w jednym wywołaniu korzystają z jednego wspólnego odczytu strony.

Śledzenie zadania

Przygotowanie raportu standard trwa 10–25 minut, a extended do około godziny: usługa czyta stronę, przeprowadza wyszukiwania, sprawdza konkurentów i czyta dyskusje klientów. Sprawdzaj status co 15–30 sekund.

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 przyjmuje wartość queued, running, a następnie jedną z completed, partial, failed, cancelled. W trakcie działania stage pokazuje bieżący etap pracy, na przykład site_read, business_mix, profile_extract, research_plan, market_frame, competitors, search, communities, audience, claim_verify, synthesis, thread_tone, moderation. Raport, który ponownie wykorzystuje wcześniejszy odczyt strony, pokazuje site_core_reused zamiast pierwszych trzech etapów. Traktuj tę listę informacyjnie: mogą pojawić się nowe etapy.

partial to dostarczony raport, w którym jakaś część nie została ukończona; przyczyna jest podana w evidence_base.limitations, a evidence_base.coverage.completeness pokazuje każdą sekcję z tym, co znaleziono, jej celem i minimum. W przypadku failed pole error.code wskazuje przyczynę, na przykład site_unreadable, gdy strona blokuje automatyczne wizyty.

Aby zatrzymać zadanie, wyślij tę samą treść żądania na /v1/cig/jobs/cancel.

Powiadomienie o gotowym raporcie

Z callback_url nie musisz sprawdzać statusu. Gdy zadanie osiągnie completed, partial, failed lub cancelled, wysyłamy POST na ten adres:

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

Nagłówek	Znaczenie
X-Omev-Event-Id	identyfikator zadania; użyj go, aby pomijać powtórne dostarczenia
X-Omev-Signature	sha256= oraz szesnastkowy HMAC-SHA256 surowej treści żądania, obliczony z Twoim callback_secret (wysyłany tylko wtedy, gdy podano sekret)

Odpowiedz dowolnym statusem 2xx. Jeśli wywołanie się nie powiedzie, próbujemy jeszcze dwa razy: po 10 sekundach i po 60 sekundach. Wynik jest widoczny w job.callback_status. Powiadomienie zawiera tylko zadanie; raport pobierz jak zwykle przez /v1/cig/jobs/result.

Sprawdź podpis, zanim zaufasz treści żądania:

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 "")

Pobranie raportu

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_…"}'

Odpowiedź zawiera job, profile (pełny raport) i stage1 (krótkie podsumowanie tego samego raportu w dziesięciu polach). Dopóki zadanie się nie zakończy, wywołanie zwraca 409 JOB_NOT_READY.

Raport składa się z dziewięciu sekcji:

Sekcja	Zawartość
meta	cel, głębokość, docelowy URL, rynek, czas wygenerowania
company	produkt, pozycjonowanie, struktura biznesu, funkcje, oferta, sygnały zaufania
market	profil klienta (ICP), ramy rynku, słowa kluczowe, zapytania klientów
problems	problemy, które rozwiązuje marka, frustracje w danej kategorii
brand_perception	skargi, pochwały i wzmianki znalezione w publicznych źródłach
competition	konkurenci (direct, adjacent, status_quo) wraz z uzasadnieniem, dlaczego każdy z nich konkuruje
audience	pytania, zastrzeżenia i oczekiwania klientów, dosłowne cytaty klientów
playbook	plan dla wybranego celu: społeczności, zapytania wyszukiwania, komunikaty, kolejne kroki, ograniczenia dotyczące stwierdzeń
evidence_base	wszystkie źródła i cytaty, na których opiera się raport, wskaźniki pokrycia, ograniczenia

Elementy zawierają evidence_ids wskazujące na evidence_base.evidence, gdzie każdy wpis ma url źródła i dokładny cytat w quote. Stwierdzenia są oznaczone jako stated (tak twierdzi sama firma), observed (zaobserwowane w niezależnych źródłach) lub inferred (nasz wniosek). Przekazując raport modelowi AI, poleć mu przedstawiać jako fakty wyłącznie elementy stated i observed oraz nigdy nie używać niczego, co znajduje się w playbook.reply_guardrails.do_not_claim.

Błędy

Kod	Kiedy
401	brak klucza API lub nieprawidłowy klucz
402 INSUFFICIENT_BALANCE	saldo klucza nie pokrywa raportu (lub wszystkich poprawnych elementów wywołania dla wielu stron)
404 JOB_NOT_FOUND	nieznane zadanie lub zadanie należące do innego konta
409 JOB_NOT_READY	wynik zażądano przed zakończeniem zadania
422 INVALID_URL	adres nie jest publiczną stroną internetową
422 INVALID_FOCUS, 422 INVALID_DEPTH, 422 INVALID_VOICE	wartość spoza powyższych list
422 INVALID_MARKET, 422 INVALID_LANGUAGE, 422 INVALID_MAX_AGE, 422 INVALID_IDEMPOTENCY_KEY	pole poza zakresem: więcej niż 10 rynków, więcej niż 6 kodów języków, wiek spoza 1–1830 dni, klucz spoza 8–200 znaków
422 INVALID_CALLBACK_URL, 422 INVALID_CALLBACK_SECRET	adres powiadomień nie jest publicznym adresem https lub sekret nie ma 16–200 znaków
422 INVALID_REQUEST, 422 BATCH_TOO_LARGE	wywołanie dla wielu stron bez elementów, z elementem, który nie jest obiektem, lub z więcej niż 50 elementami
429	zbyt wiele zapytań; ponów próbę po krótkiej przerwie

Każdy błąd ma tę samą postać: {"error": {"code": "INVALID_FOCUS", "message": "…"}}. Kody 401 przy błędnym kluczu i 429 działają tak samo we wszystkich API OmevAI; ich format opisano w sekcji Błędy.