ChatGPT Ads API: kampaaniate automatiseerimise juhend

ChatGPT Ads API lühivastus

OpenAI ametliku dokumentatsiooni järgi saab Advertiser API kaudu luua ja hallata kampaaniaid, reklaamirühmi ning reklaame, töötada tootevoogudega, seadistada konversioonide mõõtmist ja küsida tulemuste raporteid. Päringud lähevad aadressile https://api.ads.openai.com/v1 ning kasutavad serveris hoitavat Bearer-tüüpi API võtit.

Alustamiseks on vaja ChatGPT Ads reklaamikontot ja Advertiser API võtit, mis luuakse Ads Manageri seadetes. Iga võti on seotud ühe reklaamikontoga. See on oluline agentuurile: ühe kliendi võtit ei tohi kasutada teise kliendi kontol ega koondada kõiki kontosid ühe jagatud saladuse taha.

Kõige turvalisem esimene töövoog on lugeda konto andmed, luua uus kampaania pausil, lisada selle alla pausil reklaamirühm ja reklaam, kontrollida loodud ressursid uuesti API-st ning alles seejärel anda eraldi heakskiiduga aktiveerimiskäsk. API ei muuda reklaami automaatselt heakskiidetuks ega garanteeri tarnet.

Millal API annab päris ärilise võidu?

Ühe väikese kampaania käsitsi loomine Ads Manageris on tavaliselt kiirem kui integratsiooni ehitamine. API väärtus kasvab mahu, korduste ja kvaliteedikontrolli vajadusega. Näiteks saab e-poe uue hooaja kampaaniad luua standardse malli järgi, agentuur saab kontrollida kümnete kontode pausil olevaid kampaaniaid ning turundusmeeskond saab ühendada ChatGPT Ads tulemused oma juhtimisraportiga.

Automatiseerimise eesmärk ei peaks olema võimalikult palju muudatusi. Hea integratsioon vähendab käsitööd, säilitab otsuste jälje ja peatub enne riskantset sammu. Halb integratsioon võib vigase sihtimise, vale eelarve või korduva loomispäringuga vea sekunditega mitmele kampaaniale kopeerida.

Alusta API-st siis, kui suudad nimetada konkreetse korduva ülesande ja selle kontrollreegli. Kui eesmärk on lihtsalt proovida esimest ChatGPT reklaami, kasuta esmalt Ads Managerit ning kogu protsessist teadmine, mille saad hiljem automatiseeritavaks spetsifikatsiooniks muuta.

paljude kampaaniate loomine kinnitatud malli järgi
mitme reklaamikonto seisundi ja tulemuste koondamine
tootekataloogi ning reklaamistruktuuri sünkroniseerimine
korduvate nime-, URL-i ja eelarvereeglite automaatne kontroll
massmuudatuse valideerimine enne selle rakendamist
muudatuste, kinnitajate ja API vastuste auditeeritav logi

Mõista enne koodi neljatasandilist struktuuri

ChatGPT Ads konto struktuur on hierarhiline: reklaamikonto sisaldab kampaaniaid, kampaania reklaamirühmi ja reklaamirühm reklaame. Kampaania kannab eesmärki, eelarvet, ajakava, sihtimist ning konversioonisündmuse valikut. Reklaamirühmas paiknevad pakkumine, kontekstivihjed, sihtrühma korrigeerimised ja vajaduse korral tootevalik. Reklaam sisaldab loovmaterjali ning sihtkohta.

See jaotus aitab vältida levinud viga, kus integratsioon proovib muuta eelarvet reklaami tasemel või loovteksti kampaania tasemel. Iga muudatus peab minema selle ressursi endpointi, millele vastav väli kuulub. Samuti tuleb tarnehäire korral kontrollida kogu vanemate ahelat, mitte ainult reklaami olekut.

Ressursside ID-d on API püsivad viited. Nimede järgi otsing on küll tõstutundetu, kuid sama nimega vasteid võib olla mitu. Salvesta loodud kampaania, reklaamirühma ja reklaami ID oma süsteemi ning kasuta nime inimestele arusaadava sildina, mitte ainsa tehnilise võtmena.

1. Loo võti ja hoia see ainult serveris

Advertiser API võti luuakse Ads Manageri Settings vaates. Võti on konto saladus: ära lisa seda veebilehe JavaScripti, mobiilirakendusse, Git-repositooriumi, kuvatõmmisele, analüütikasse ega vealogi täistekstina. Brauserisse jõudnud võtit tuleb käsitleda lekkinuna ka siis, kui leht polnud avalikult lingitud.

Hoia võtit serveri saladuste halduses või juurutuskeskkonna kaitstud muutujas. Anna tootmise võtmele ainult selle töö jaoks vajalik ligipääs, piira seda kasutava teenuse õigusi ja määra omanik, kes saab võtme vajaduse korral tühistada ning asendada. Agentuuris hoia iga kliendi võti eraldi saladusena.

Logides piisab päringu tüübist, konto ja ressursi ID-st, vastuse olekukoodist ning sisemisest korrelatsiooni-ID-st. Authorization päis, üleslaaditud kliendiloend, tundlik sihtkoha parameeter ja täielik API vastus ei pea jõudma tavapärasesse rakenduslogisse.

2. Kontrolli ühendust enne esimest kirjutamist

Esimene päring peaks olema lugemispäring GET /v1/ad_account. Sellega kontrollid, kas võti töötab, millise reklaamikontoga see seotud on ning millised on konto valuuta, ajavöönd, olek ja ülevaatuste info. Kui vastus kirjeldab valet kontot, ära jätka kampaania loomisega.

Aktiivne konto ei tähenda alati, et kõik vajalikud ülevaatused on lõppenud. Salvesta konto ID, valuuta ja ajavöönd integratsiooni konfiguratsiooni ning võrdle neid igal tööjooksul oodatud väärtustega. Nii ei muutu eurodes kavandatud summa kogemata teise valuuta mikrouhikuteks ega lähe ajakava vale päeva alla.

Jaga ühenduse test ja kirjutamisõigus eraldi etappideks. Arendus- või raportiteenus võib vajada ainult andmete lugemist, samal ajal kui kampaaniate muutmise teenus peaks töötama rangema kinnituse ning väiksema kasutajaringiga.

3. Loo esimene kampaania alati pausil

OpenAI soovitab uue kampaania, reklaamirühma ja reklaami luua pausil. Selline järjestus annab võimaluse kontrollida eelarvet, ajakava, sihtimist, pakkumist, kontekstivihjeid, loovmaterjali ja sihtlehte enne, kui süsteem võib hakata reklaami esitama.

Kampaania loomisel vali eesmärgile sobiv bidding_type: impressions, clicks või sobiva mõõtmise korral conversions. Konversioonile optimeerimine eeldab sobivat konversioonisündmuse seadistust. Reklaamirühma fikseeritud pakkumine vajab max_bid_micros väärtust, Maximize Results strateegia puhul seda välja ei lisata.

Seejärel laadi üles vähemalt 640 × 640 piksli suurune JPEG-, PNG- või WebP-pilt, loo reklaam õigesse reklaamirühma ning kasuta ligipääsetavat HTTP- või HTTPS-sihtlehte. Praeguse API juhendi järgi on chat_card pealkiri 3–50 märki ja kirjeldus kuni 100 märki. Kontrolli kehtivaid piire alati enne saatmist, sest API leping võib areneda.

4. Tee korduskatsed idempotentseks

Võrguühendus võib katkeda pärast seda, kui server lõi kampaania, kuid enne seda, kui sinu süsteem vastuse kätte sai. Kui saadad sama loomispäringu uue katsena pimesi uuesti, võid tekitada duplikaadi. OpenAI toetab loomise endpointides Idempotency-Key päist, mis seob korduskatse sama loogilise loomistoiminguga.

Genereeri igale kavandatud ressursile kordumatu võti ja salvesta see enne päringut oma andmebaasi. Kui sama päring ebaõnnestub ebakindla võrguveaga, saada uuesti täpselt sama keha ning sama idempotentsusvõti. Uue kampaania või muudetud päringukeha jaoks kasuta uut võtit.

Konflikti korral ära genereeri kohe uut võtit. Kontrolli esmalt, kas vana võtmega loodi ressurss ning kas korduspäringu sisu erineb algsest. Turvaline kordusloogika vajab piiratud katsete arvu, kasvavat ooteaega ja lõplikku käsitsi ülevaatust.

5. Uuendamisel loe olemasolev seis enne muutmist

Kampaania, reklaamirühma või reklaami muutmisel loe ressursi praegune versioon enne kirjutamist. OpenAI kampaaniajuhend rõhutab, et pesastatud loendid ja sihtimisväljad võivad uuendamisel asendada olemasoleva loendi. Kui saadad ainult ühe uue väärtuse, võid tahtmatult eemaldada varem kinnitatud väärtused.

Ehita soovitud lõppseis praeguse vastuse ja kavandatud muudatuse ühendamisel, valideeri see ning saada täielik vajalik väärtuste komplekt. Kampaania, reklaamirühma ja reklaami uuendused kasutavad POST-päringut; ära eelda, et kõik ressursid järgivad tavapärast PATCH-loogikat. Tootevoo deltauuendusel on eraldi leping.

Loovmaterjali muutmine käivitab uue reklaamiülevaatuse. Reklaami ei saa teise reklaamirühma tõsta; selleks tuleb luua uus reklaam soovitud vanema alla. Need reeglid peavad olema integratsiooni töövoos enne avaldamist, mitte kasutaja avastada jäänud veateatena.

6. Kasuta massmuudatust ainult valideeritud paketina

Bulk mutation job sobib suure hulga seotud toimingute jaoks. Ühte töösse mahub ametliku juhendi järgi kuni 1000 operatsiooni ja 16 MiB andmeid. Masspäringu skeem ei ole identne üksiku ressursi loomispäringuga, seega ei tohi valmis üksikpäringuid lihtsalt muutmata kujul masspaketti kopeerida.

Kasuta esmalt validate_only režiimi. See kontrollib paketi lepingut ilma muudatusi rakendamata. Alles eduka valideerimise ja inimese heakskiidu järel saada päris töö, salvesta töö ID, jälgi selle olekut ning loe iga operatsiooni tulemus. Ühe töö üldine lõpetamine ei tähenda, et kõik alamoperatsioonid õnnestusid.

Kampaania hierarhia saab ühe masspaketi sees seostada idempotentsusvõtmetega: reklaamirühm viitab loodava kampaania võtmele ja reklaam loodava reklaamirühma võtmele. See on võimas, kuid nõuab deterministlikku plaani. Kui sisend muutub, loo uus paketiversioon, ära kirjuta eelmise jooksu tähendust üle.

7. Eralda eelvaade, ülevaatus ja päris tarne

Reklaami eelvaade aitab kontrollida, kuidas pealkiri, kirjeldus, pilt ja sihtleht koos mõjuvad. See ei kinnita, et reklaam on ülevaatuse läbinud või saab näitamisi. Reklaami status kirjeldab seadistatud olekut, review_status loovülevaatust ning serving_issues tarne takistusi.

Aktiivne reklaam võib endiselt mitte näidata, kui konto ülevaatus on pooleli, kampaania on pausil, eelarve või ajakava ei luba tarnet, reklaamirühma pakkumine ei sobi eesmärgiga, tootevalik on tühi või loovmaterjal on tagasi lükatud. Kontrolli konto, kampaania, reklaamirühma ja reklaami ahelat ülalt alla.

Kui serving_issues on tühi, ei ole näitamised siiski garanteeritud. Võimalik ulatus võib olla väike, sihtimine liiga kitsas või pakkumine konkurentsivõimetu. Automatiseerimine peab eristama selget blokeerijat, hoiatust ja lihtsalt vähest võimalust; iga nullnäitamist ei tohi lahendada eelarve automaatse tõstmisega.

8. Ehita mõõtmine ja URL-i parameetrid teadlikult

Konto, kampaania, reklaamirühma ja reklaami tasemel saab kasutada jälgimisparameetreid. OpenAI juhendi järgi ühendatakse need päringuhetkel ning sama võtme konfliktis on tugevam siht-URL, seejärel reklaam, reklaamirühm, kampaania ja konto. See võimaldab panna konto tasemele ühised UTM-väljad ning kampaania või reklaami tasemele täpsustuse.

Dokumenteeri parameetrite omanik ja väldi sama võtme juhuslikku defineerimist mitmel tasemel. Enne aktiveerimist genereeri lõplik siht-URL, kontrolli selle pikkust, HTTP vastust, ümbersuunamisi, nõusolekubännerit ja seda, kas vajalikud analüütikasündmused tekivad alles lubatud nõusoleku järel.

Raport ei ole täielik ainult klikkide ja kuluga. Seo Insights andmed veebianalüütika, kvalifitseeritud päringu, müügi või muu ärilise tulemusega. Konversioonisündmuse testendpointi viimaste sündmuste näidis sobib tehniliseks veakontrolliks; ajaloolise ja omistatud tulemuse jaoks kasuta Insights raportit.

9. Arvesta raporti värskuse ja ajavahemikuga

Advertiser API Insights võimaldab küsida tulemusi konto, kampaania, reklaamirühma ja reklaami tasemel. Vali raporti agregatsioon ning väljad selle küsimuse järgi, millele vastad. Kampaania päevane spend ja reklaami klikkide jaotus ei ole sama raport, isegi kui mõlemad tulevad samast API-st.

OpenAI raportijuhendi järgi jõuavad näitamised, klikid ja CTR vaatesse minutitega, kulu ning CPC või CPM võivad hilineda kauem ja konversioonid uuenevad päevapõhiselt. Konversiooniraportile tasub anda vähemalt üks päev. Ära käivita paanikareeglit selle peale, et värske tunni spend või konversioonide arv on veel null.

Tee toorandmete laadimine korduvaks ja parandatavaks: lae värskeid päevi uuesti, erista konto ajavööndit raportisüsteemi ajavööndist ja märgi juhtimisvaates, millal andmeid viimati värskendati. Tulemuse tõlgendamisel võrdle sobiva pikkusega perioodi, mitte paari minuti tarnekatset.

10. Töötle vead enne korduskatset

Autentimisviga vajab võtme ja Bearer-päise kontrolli, ligipääsuviga konto ning funktsiooni saadavuse kontrolli, valideerimisviga väljade parandamist ja resource not found täpse ID ning konto kontrolli. Neid ei lahenda sama päringu kiire kordamine. Konflikt võib viidata idempotentsusvõtme valele taaskasutusele või aegunud ressursiversioonile.

Ajutise vea või rate limit vastuse puhul järgi serveri retry-juhist ja kasuta piiratud arvu kasvava viivitusega katseid. Advertiser API ülevaade kirjeldab jagatud limiite: 600 päringut minutis endpointi kohta ja 1200 päringut minutis kokku; bulk-tööde loomisel 10 päringut 10 sekundi jooksul reklaamikonto kohta. Kontrolli kehtivaid limiite dokumentatsioonist ning ära ehita integratsiooni püsivalt piiri peal töötama.

Massoperatsiooni tulemustes kontrolli iga nurjunud operatsiooni retryable ja retry_after_seconds välju. Korda ainult neid toiminguid, mille kordamine on ohutu. Kui sisend või konto seis vahepeal muutus, loe andmed uuesti ja ehita uus plaan.

Turvalise agentuuritöö arhitektuur

Agentuuri integratsioonis peaks kliendi reklaamikonto jääma kliendile ning API võti olema ühe konto ulatusega. Veebipõhine juhtpaneel ei tohi kunagi anda brauserile päris võtmeid; kasutaja saadab kavandatud muudatuse agentuuri serverile, server valideerib õigused ja reeglid ning alles seejärel suhtleb OpenAI API-ga.

Jaga protsess vähemalt kolmeks rolliks: ettevalmistaja loob muudatuse, kinnitaja kontrollib eelarvet ja mõju ning teenus rakendab ainult kinnitatud versiooni. Suurema eelarve, aktiveerimise, arhiivimise või massmuudatuse puhul nõua tugevamat kinnitust kui nime parandamisel. Iga rakendus peaks jätma muutumatu jälje sellest, kes, millal, millist enne- ja pärastseisu kinnitas.

Lisa kaitsepiirid: maksimaalne lubatud eelarvemuudatus, lubatud valuuta ja riigid, siht-URL-i domeenide loend, paus vaikimisi, duplikaadinimede hoiatus ning automaatne peatamine, kui konto ID ei vasta konfiguratsioonile. Need kontrollid on väärtuslikumad kui võimalus kampaania ühe sekundiga aktiivseks teha.

Praktiline näide: 40 kohaliku kampaania turvaline loomine

Oletame, et jaekett soovib luua sama pakkumise 40 piirkonnale. Sisendfail sisaldab piirkonna nime, siht-URL-i, eelarvet ja kinnitatud reklaamteksti. Integratsioon kontrollib esmalt duplikaate, URL-ide vastuseid, valuutat, eelarvepiire ning teksti pikkust. Seejärel loob ta validate_only masspaketi ja annab inimesele kokkuvõtte: mitu kampaaniat, milline kogumaht ning millised read ei läbinud kontrolli.

Pärast kinnitamist saadetakse päris masspakett. Kõik ressursid luuakse pausil, iga hierarhiatase saab oma idempotentsusvõtme ja tulemused salvestatakse ressursi ID kaupa. Nurjunud operatsioonid lähevad eraldi parandusringi; õnnestunud kampaaniaid ei looda uuesti.

Lõpuks loeb süsteem loodud kampaaniad API-st tagasi, kontrollib eelarvet, ajakava, sihtimist, reklaamirühma ja reklaami olekut ning koostab aktiveerimisnimekirja. Aktiveerimine on eraldi heakskiit, mitte loomistöö automaatne jätk. Nii annab API kiiruse ilma kontrolli kaotamata.

Tootmisküpsuse kontrollnimekiri

API ühendus on tootmisküps alles siis, kui õnnestunud päringu kõrval on läbi mõeldud ka ebakindel vastus, vale konto, osaliselt nurjunud masspakett, ülevaatuse ootel loovmaterjal ja inimese tehtud paralleelne muudatus. Testi neid olukordi väikese eelarvega pausil ressurssidel enne, kui annad automatiseerimisele ulatusliku kirjutamisõiguse.

võti asub serveri saladuste halduses ja selle omanik on teada
GET /v1/ad_account kontrollib konto ID-d, valuutat, ajavööndit ja ülevaatusi
uued kampaaniad, reklaamirühmad ja reklaamid luuakse pausil
loomispäringutel on püsivad idempotentsusvõtmed
uuendamisel loetakse olemasolev seis ja säilitatakse vajalikud loendid
masspakett läbib validate_only kontrolli ja inimese kinnituse
eelvaadet ei käsitleta ülevaatuse ega tarne kinnitusena
vead liigitatakse enne korduskatset ja rate limit juhiseid järgitakse
raportis on nähtav andmete värskus, ajavöönd ja äriline tulemus
eelarve, aktiveerimise ja arhiivimise muudatustest jääb auditijälg

Kas ehitada ise või tellida integratsioon?

Ise ehitamine sobib ettevõttele, kellel on püsiv arendusmeeskond, selge kampaaniamudel ja piisav maht. Väikese reklaamimahu puhul võib Ads Manager koos hea tööjuhendi ja raportiga anda sama ärilise tulemuse väiksema hoolduskuluga. API ei vähenda vajadust kampaaniastrateegia, loovlahenduse ega mõõtmise järele.

Kala Ruudus aitab kõigepealt valida, milline töövoog päriselt automatiseerimist väärib. Kaardistame konto omandi, kampaania hierarhia, sisendi, kinnitused, veaolukorrad, mõõtmise ja auditijälje. Seejärel saame ehitada väikese turvalise piloodi või ühendada Advertiser API olemasoleva e-poe, andmelao või juhtimisraportiga.

Saada meile oma reklaamikontode arv, korduv käsitöö, kasutatav tehniline platvorm ja soovitud tulemus. Vastame konkreetse piloodiplaaniga: mida API kaudu automatiseerida, mis jätta inimese otsuseks ning kuidas kontrollida, et kiirus ei tekitaks eelarve- või kvaliteediriski.

Korduma kippuvad küsimused

Mis on ChatGPT Ads API?

ChatGPT Ads API ehk OpenAI Advertiser API on programne liides reklaamikonto kampaaniate, reklaamirühmade, reklaamide, tootevoogude, mõõtmise ja raportite haldamiseks. Selle kasutamiseks on vaja reklaamikontot ja Ads Manageri seadetes loodud API võtit.

Kas ChatGPT Ads API võtit võib kasutada veebilehe JavaScriptis?

Ei. API võti peab jääma serveri saladuseks. Brauserisse, mobiilirakendusse, avalikku repositooriumi või tavapärasesse logisse jõudnud võtit tuleb käsitleda lekkinuna ning see asendada.

Kas API kaudu loodud reklaam hakkab kohe näitama?

Ei pruugi. Ressursid tasub luua pausil. Aktiveerimise järel peab reklaam vastama ülevaatusele, sihtimisele, eelarvele, pakkumisele ja kogu konto hierarhia tingimustele. Eelvaade ei kinnita tarnekõlblikkust.

Kuidas vältida sama kampaania topeltloomist?

Kasuta loomispäringul Idempotency-Key päist, salvesta võti enne päringut ja kasuta sama loogilise toimingu korduskatsel sama võtit ning sama päringukeha. Uue ressursi jaoks kasuta uut võtit.

Kas ChatGPT Ads API toetab massmuudatusi?

Jah. Bulk mutation job võimaldab ametliku juhendi järgi kuni 1000 operatsiooni ja 16 MiB paketti. Enne rakendamist kasuta validate_only kontrolli ning loe pärast töö lõppu iga operatsiooni tulemus eraldi.

Kas Advertiser API sobib ühe väikese kampaania jaoks?

Tehniliselt võib sobida, kuid ühe kampaania puhul on Ads Manager sageli kiirem ja odavam. API väärtus tekib korduvates, mahukates või range kontrolli ning raportiühendust vajavates töövoogudes.

Loe edasi

Kontrollitud allikad

Artikli tootefaktid kontrolliti 25. septembril 2026.

Oluline

Platvormi võimalused, saadavus ja hinnastus võivad muutuda. Kontrollime kampaania planeerimisel alati konto hetkeolukorda ning OpenAI ametlikku dokumentatsiooni.

ChatGPT Ads API: kampaaniate automatiseerimise praktiline juhend