Jak skonfigurować konto reklamowe ChatGPT Ads przez API — przewodnik dla agenta AI?

Co realnie powstaje przez API?

Advertiser API OpenAI przyjmuje żądania pod adresem https://api.ads.openai.com/v1 z nagłówkiem Authorization: Bearer. Jeden klucz obsługuje dokładnie jedno konto reklamowe — tak opisuje to dokumentacja uwierzytelniania, odczyt 12 września 2026.

Hierarchia jest trzypoziomowa. Konto zawiera kampanie, kampania grupy reklam, grupa reklamy. Budżet, cel, harmonogram i targeting siedzą na kampanii; stawka i podpowiedzi kontekstowe na grupie; tytuł, treść, obraz i adres docelowy na reklamie.

Agent z dostępem do powłoki wykona żądaniami cały łańcuch: sprawdzenie konta, utworzenie piksela, wydanie klucza Conversions API, definicje zdarzeń, wysyłkę zdarzeń z serwera, kampanię, grupę, przesłanie obrazu, reklamę, podgląd, aktywację i odczyt wyników.

W aplikacjach, które budujemy, zdarzenia konwersji wysyła serwer, nie przeglądarka — dokumentacja nazywa ten kanał bardziej wiarygodnym źródłem pomiaru niż sam piksel. Co w ogóle wysyłać, opisuje tekst o zdarzeniach zamiast odsłon.

Taksonomia jest zamknięta: dokumentacja wymienia trzynaście nazw zdarzeń, w tym page_viewed, lead_created, order_created oraz custom z własną nazwą. Każda ma przypisany kształt danych — contents, customer_action albo plan_enrollment.

Jak skonfigurować konto krok po kroku?

Kolejności nie da się przestawić. Piksel musi istnieć przed definicją zdarzenia, a definicja przed kampanią optymalizowaną na konwersje. Każdy krok kończy się odpowiedzią z identyfikatorem, który wchodzi do następnego wywołania.

1. Sprawdź konto i klucz. Odpowiedź zawiera walutę, strefę czasową, status i przeglądy. Konto ze statusem active może mieć niezamknięty przegląd — dokumentacja ostrzega przed tym wprost.

   curl -G "https://api.ads.openai.com/v1/ad_account" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>"

2. Utwórz piksel. Pola: name od 3 do 1 000 znaków i client_type o wartości web. W odpowiedzi wraca id źródła oraz pixel_id. Kod 404 z treścią Not found znaczy, że konto nie ma włączonego zarządzania pikselami.

   curl -X POST "https://api.ads.openai.com/v1/conversions/pixels" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>" -H "Content-Type: application/json" -d '{"name":"Strona firmowa","client_type":"web"}'

3. Wydaj klucz Conversions API. To inny klucz niż ten do Advertiser API. Wraca w odpowiedzi na to żądanie; endpointu, który odczytałby go później, dokumentacja na 12 września 2026 nie opisuje. Zapisz go od razu w menedżerze sekretów po stronie serwera — nigdy w kodzie przeglądarki, w zmiennych klienta ani w logach.

   curl -X POST "https://api.ads.openai.com/v1/conversions/api_keys" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>" -H "Content-Type: application/json" -d '{"name":"Zdarzenia z serwera"}'

4. Zdefiniuj zdarzenie. Wymagane są name, event_type, attribution_window_days oraz source_ids z dokładnie jednym źródłem. Odpowiedź Client data source not found znaczy, że identyfikator źródła nie należy do tego konta.

   curl -X POST "https://api.ads.openai.com/v1/conversions/event_settings" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>" -H "Content-Type: application/json" -d '{"name":"Zapytania","event_type":"lead_created","attribution_window_days":30,"source_ids":["<ID-ZRODLA>"]}'

5. Wyślij zdarzenia z serwera. Inny host i inny klucz. E-mail, telefon, external_id oraz imię i nazwisko idą jako SHA-256 po normalizacji: e-mail przycięty i zamieniony na małe litery, telefon bez znaku plus, spacji i zer wiodących. Identyfikator reklamowy Androida (android_advertising_id) i obref z ciasteczka piksela wysyłasz jawnie, bez hashowania.

   curl -X POST "https://bzr.openai.com/v1/events?pid=<PIXEL-ID>" -H "Authorization: Bearer <KLUCZ-CAPI>" -H "Content-Type: application/json" -d '{"validate_only":true,"events":[{"id":"zam-1","type":"order_created","timestamp_ms":1773892800000,"source_url":"https://example.com/potwierdzenie","action_source":"web","data":{"type":"contents","amount":12999,"currency":"PLN"}}]}'

   Trzymaj validate_only na true, dopóki odpowiedź nie będzie czysta. Kwota amount to liczba całkowita w jednostce podrzędnej waluty, czyli w groszach albo centach.

6. Znajdź identyfikator lokalizacji. Wyszukiwarka zwraca id, canonical_name, country_code i typ. Publiczny katalog lokalizacji w formacie CSV odpowiadał 12 września 2026 stroną weryfikacji przeglądarki, więc identyfikator bierz z tego endpointu.

   curl -G "https://api.ads.openai.com/v1/geo_lookup/search" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>" --data-urlencode "q=Poland" --data-urlencode "limit=5"

7. Utwórz kampanię jako wstrzymaną. Podajesz dokładnie jeden budżet: dzienny albo życiowy. Pola czasu to uniksowe sekundy. Nagłówek Idempotency-Key chroni przed powieleniem obiektu przy ponowieniu zerwanego żądania.

   curl -X POST "https://api.ads.openai.com/v1/campaigns" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>" -H "Idempotency-Key: kampania-001" -H "Content-Type: application/json" -d '{"name":"Test 1","status":"paused","bidding_type":"clicks","budget":{"daily_spend_limit_micros":50000000},"targeting":{"locations":{"include":[{"id":"<ID-LOKALIZACJI>"}]}}}'

8. Dodaj grupę reklam. Obiekt bidding_config jest obowiązkowy, nawet gdy kampania ma już cel. Dla stawki stałej podajesz strategy fixed_bid i max_bid_micros; dla strategii Maximize Results stawkę pomijasz, a kampania musi mieć budżet dzienny.

   curl -X POST "https://api.ads.openai.com/v1/ad_groups" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>" -H "Content-Type: application/json" -d '{"campaign_id":"<CAMPAIGN-ID>","name":"Grupa 1","status":"paused","context_hints":["pomysł na aplikację"],"bidding_config":{"billing_event_type":"click","strategy":"fixed_bid","max_bid_micros":2000000}}'

9. Prześlij obraz, potem utwórz reklamę. Endpoint przesyłania przyjmuje adres obrazu w JSON albo plik binarny; dokumentacja żąda co najmniej 640 na 640 pikseli. Tytuł kreacji ma od 3 do 50 znaków, treść maksymalnie 100.

   curl -X POST "https://api.ads.openai.com/v1/upload" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>" -H "Content-Type: application/json" -d '{"image_url":"https://example.com/karta.png"}'

   curl -X POST "https://api.ads.openai.com/v1/ads" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>" -H "Content-Type: application/json" -d '{"ad_group_id":"<AD-GROUP-ID>","name":"Karta 1","status":"paused","creative":{"type":"chat_card","title":"Tytul do 50 znakow","body":"Tresc do 100 znakow","target_url":"https://example.com/","file_id":"<FILE-ID>"}}'

10. Obejrzyj podgląd, potem włącz. Podgląd wygasa po 24 godzinach i pokazuje wygląd, nie prawo do emisji. Aktywuj od dołu: najpierw reklama, potem grupa, na końcu kampania.

    curl -X POST "https://api.ads.openai.com/v1/ads/<AD-ID>/preview" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>"

    curl -X POST "https://api.ads.openai.com/v1/campaigns/<CAMPAIGN-ID>/activate" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>"

11. Odczytaj wyniki. Cztery endpointy insights zwracają tę samą kopertę listy — first_id, last_id i has_more; kolejną stronę bierzesz, podając last_id jako after. Konwersje przypisane do kampanii czyta się osobnym żądaniem POST na /conversions/insights.

    curl -G "https://api.ads.openai.com/v1/campaigns/<CAMPAIGN-ID>/insights" -H "Authorization: Bearer <TWÓJ-KLUCZ-API>" --data-urlencode "time_granularity=daily" --data-urlencode "limit=7"

Pola, które decydują, czy kampania ruszy

Pułapki, których nie ma w dokumentacji

Pięć rzeczy zmierzyliśmy na żywym koncie 1 września 2026, stawiając kampanię wyłącznie żądaniami HTTP. Żadnej z nich nie znaleźliśmy wtedy w dokumentacji producenta.

• Czas jako tekst ISO kończy się kodem 400 i błędem invalid_type. Pola start_time oraz end_time przyjmują wyłącznie uniksowe sekundy jako liczbę całkowitą.
• Cel conversions odrzuca zdarzenie własne. Ustawienie typu custom dostaje 400 z komunikatem o wymaganym standardowym ustawieniu zdarzenia konwersji.
• Grupa reklam bez bidding_config nie powstanie. Wraca 400 missing_required_parameter, mimo że cel i budżet siedzą piętro wyżej, na kampanii.
• Parametr fields w insights nie przyjmuje nazw płaskich. Trzeba nazw z przedrostkiem poziomu, jak campaign.budget.daily albo ad_group.clicks; płaska nazwa dostaje 400 z listą dozwolonych wartości.
• Seria trzech żądań tworzących reklamy przekracza pięciosekundowy limit czasu klienta. Zerwane połączenie nie znaczy, że nic nie powstało: najpierw pobierz listę reklam, dopiero potem rozważ ponowienie.

Szóstą rzecz sprawdź odczytem. Polskie znaki w podpowiedziach kontekstowych potrafi przekłamać konsola, z której leci żądanie — po zapisie pobierz grupę i porównaj wartości znak po znaku.

Gdzie przebiega granica API?

Granic jest kilkanaście i każda ma inny skutek. Jedna zatrzymuje żądanie, druga zatrzymuje emisję, trzecia każe założyć kampanię od nowa.

Kiedy API nie wystarczy i zostajesz w panelu?

Pierwszy klucz wydaje się wyłącznie w ustawieniach Ads Managera — dokumentacja nie opisuje endpointu, który by go tworzył. Bez tego kroku agent nie ma czym się uwierzytelnić, więc start zawsze jest ręczny.

Piksel i klucz Conversions API powstają żądaniem, ale tylko na koncie, które ma tę funkcję włączoną. Kod 404 z treścią Not found znaczy, że zostaje zakładka konwersji w panelu albo rozmowa z opiekunem po stronie OpenAI.

Płatności ani faktur nie znaleźliśmy w dokumentacji Ads API na dzień 12 września 2026. Są za to limity wydatku konta: okna z datami oraz limit dzienny dla kont rozliczanych fakturą po okresie.

Waluta i strefa czasowa to wybory z chwili zakładania konta i aktualizacja marki ich nie zmienia. Decyzja zapada więc przed pierwszym żądaniem, a poprawka oznacza inne konto.

Przeglądy są osobną warstwą. Reklama ze statusem active i polem review_status w stanie in_review jest włączona, ale nie emituje. API pokazuje stan i powód odmowy — nie przyspiesza decyzji.

Kreacji graficznej API nie wymyśli: przyjmuje gotowy plik albo adres obrazu.

Konwersje policzone po samym wyświetleniu, bez kliknięcia, raportuje panel osobno na poziomie kampanii — do głównej liczby konwersji nie wchodzą.

Który kanał w ogóle ma sens dla konkretnej branży, rozstrzygamy gdzie indziej — kanały i liczby zebrano w tekście o pierwszych 50 klientach branżowych. Podział pracy między agentem a człowiekiem opisuje tekst o rolach i bramkach w zespole z agentami AI.