Kostenlos testen
Handbuch

ChatGPT-Anzeigen (OpenAI Ads)

OpenAI Ads API deklarativ via api-Adapter: Konto, Kampagnen, Anzeigengruppen, Anzeigen, Kennzahlen je Tag; Pausieren, Budget, Anlegen mit derselben Freigabe und demselben Deckel wie Google und Meta.

ChatGPT-Anzeigen (Ads Manager ads.openai.com) laufen über die OpenAI Ads API (Advertiser API, https://api.ads.openai.com/v1/, Doku: developers.openai.com/ads). TaskMonkey bindet sie über den deklarativen api-Adapter ein. Die Tools liegen in config/tenants/_shared/tools/openai_ads/ und stehen damit jedem Workspace zur Verfügung, sobald er einen apis.openai_ads-Block und einen eigenen Key hat (seit 16.11.2026, zuerst meco).

Was die API kann

  • Auth: Authorization: Bearer <Ads-API-Key>. Den Key legt man im Ads Manager unter Settings an. Ein Key gehört zu genau einem Werbekonto (GET /ad_account, deshalb ohne Konto-ID).
  • Lesen: Konto, Kampagnen, Anzeigengruppen, Anzeigen, Insights (Konto, Kampagne, Anzeigengruppe, Anzeige; stündlich, täglich, monatlich oder Summe; Impressionen, Klicks, Kosten, CTR, CPC, CPM; Aufschlüsselung nach Land, Gerät und Plattform), Audit-Logs.
  • Schreiben: Kampagnen, Anzeigengruppen und Anzeigen anlegen und ändern (POST, nicht PATCH), Status über …/activate, …/pause, …/archive (Archivieren ist nicht umkehrbar), Tages- oder Laufzeitbudget je Kampagne, Bilder hochladen (POST /upload), Konto-Ausgabelimits (nur bei Rechnungskauf), Pixel und Conversions-API, Bulk-API.
  • Beträge in Micros der Konto-Währung (1 EUR = 1.000.000). Kosten (spend) in Insights kommen schon in Währungseinheiten.
  • Rate-Limits: 600 Anfragen pro Minute je Endpunkt, 1.200 pro Minute gesamt (je Konto und je IP), Bulk-Jobs 10 pro 10 Sekunden.
  • Ausrichtung im EWR: keine personalisierten Anzeigen, nur Land und Gesprächsthema (context_hints der Anzeigengruppe). Mindestbudget DE: etwa 15 € je Tag und Kampagne im Wochenschnitt (siehe docs/marketing/chatgpt-ads-recherche-2026-10-29.md).

Tools

Tool Art Geld? Freigabe
openaiAdsGetAccount lesen: Konto (Status, Zeitzone, Währung, Prüfung) – –
openaiAdsListCampaigns lesen: Kampagnen mit daily_budget_eur / lifetime_budget_eur – –
openaiAdsListAdGroups lesen: Anzeigengruppen einer Kampagne (context_hints, Gebot) – –
openaiAdsListAds lesen: Anzeigen einer Anzeigengruppe (Text, Ziel-URL, review_status) – –
openaiAdsGetInsights lesen: Kennzahlen je Tag oder als Summe, plus totals – –
openaiAdsGetObject intern: ein Objekt lesen (für die Prüfungen) – –
openaiAdsAccountDailyBudget intern: Summe aktiver Tagesbudgets gegen den Konto-Deckel – –
openaiAdsSetStatus Kampagne, Anzeigengruppe oder Anzeige paused (sofort) oder active ja active: Ja im Chat, ohne Chat Freigabe-Anfrage, autonome Workspaces bis zum Deckel ohne
openaiAdsSetCampaignBudget Tagesbudget einer Kampagne ja Erhöhen wie active, Senken sofort
openaiAdsUploadImage Bild per https-URL hochladen, liefert file_id nein –
openaiAdsCreateCampaign Kampagne anlegen, immer pausiert, mit Tagesbudget nein (pausiert) wie active
openaiAdsCreateAdGroup Anzeigengruppe anlegen, immer pausiert, Festgebot nein (pausiert) wie active
openaiAdsCreateAd Anzeige (chat_card) anlegen, immer pausiert, geht zur Prüfung nein (pausiert) wie active
openaiAdsObjectAction, openaiAdsUpdateCampaignBudget, openaiAdsCreateObject Roh-Schreiber ja nur über die Hüllen (only_via)

Beispiel Kosten je Tag: openaiAdsGetInsights ohne Argumente liefert die letzten 7 Tage je Kampagne und Tag (Tage in Europe/Berlin, heute bis zur letzten vollen Stunde). Ganzes Konto als eine Summe: {"aggregation_level": "ad_account", "granularity": "none"}.

Regeln für Geld

Gleiches Muster wie Meta Ads und Google Ads:

  • Alles wird pausiert angelegt. Live geht etwas nur über openaiAdsSetStatus(status=active), und zwar erst, wenn Kampagne, Anzeigengruppe und Anzeige aktiv sind.
  • Obergrenze je Kampagne apis.openai_ads.max_daily_budget_eur (Default 30), Höchstgebot apis.openai_ads.max_bid_eur (Default 5 €, je Klick bzw. je 1.000 Impressionen). Darüber schreibt TaskMonkey nie.
  • Konto-Deckel der Plattform Platform.ads.max_account_daily_budget_eur (Default 50): Summe aller aktiven ChatGPT-Kampagnen inklusive der neuen bzw. geänderten. Nicht bestimmbar (aktive Kampagne mit Laufzeitbudget, mehr als 500 Kampagnen, Lesefehler) heißt abgelehnt.
  • Nur EUR-Konten. Rechnet das Werbekonto in einer anderen Währung, ändert TaskMonkey keine Budgets und aktiviert nichts.
  • Laufzeitbudgets werden nicht angefasst (die API stellt nur von Laufzeit auf Tag um, nicht zurück), und solche Kampagnen werden nicht aktiviert. Kampagnen aus TaskMonkey haben immer ein Tagesbudget.
  • Freigabe und Autonomie: checkAdsAutonomy (App\Tooling\AdsAutonomy, Plattform openai_ads), sonst requestAdsApproval (Ja im Chat bzw. Freigabe-Anfrage unter /manage/approvals). meco ist per Platform.ads.workspaces.meco autonom. Der Gesamtdeckel autonomous_max_total_daily_eur (meco 50 €/Tag) zählt jetzt Google, Meta und ChatGPT zusammen: Bei jeder autonomen Erhöhung liest checkAdsAutonomy die Tagesbudgets aller anderen eingerichteten Plattformen. Ist eine davon nicht lesbar, gibt es eine Freigabe-Anfrage statt einer autonomen Aktion. Anlegen (pausiert) ändert die Konto-Summe nicht, läuft aber durch dieselbe Prüfung.
  • Ziel-URLs der Anzeigen nur https auf apis.openai_ads.allowed_target_hosts (meco: taskmonkey.de und Subdomains). Ohne Liste wird keine Anzeige angelegt.
  • Archivieren gibt es nicht als Tool (nicht umkehrbar), das geht nur im Ads Manager.

Deckel-Audit (auch für Google und Meta)

Die Regeln oben greifen nur, wenn TaskMonkey selbst schreibt. Anlass 17.11.: Im ChatGPT-Werbekonto lief eine vom OpenAI-Einrichtungsassistenten angelegte Kampagne mit 65 €/Tag an unseren Tools vorbei. Deshalb prüft der Scheduled Task ads_cap_audit (meco, config/tenants/meco/scheduled.php, stündlich, failure_backoff 15 min) mit dem Tool auditAdsBudgetCaps (config/tenants/_shared/tools/ads_audit/), was in den Konten tatsächlich aktiv ist:

  • liest je eingerichteter Plattform alle aktiven Kampagnen mit Tagesbudget (listAdsCampaigns, metaListActiveBudgets, openaiAdsListCampaigns);
  • Verstoß 1: Tagesbudget einer Kampagne über apis.<plattform>.max_daily_budget_eur (nur wenn gesetzt);
  • Verstoß 2: Summe einer Plattform über dem Konto-Deckel Platform.ads.max_account_daily_budget_eur;
  • Verstoß 3: Summe aller Plattformen über dem Gesamtdeckel (Platform.ads.workspaces.<code>.max_total_daily_eur, sonst autonomous_max_total_daily_eur, sonst Konto-Deckel; im Tool als $ctx['platform']['ads']['max_total_daily_eur']). Bei 2 und 3 wird pausiert, bis die Summe wieder passt: zuerst Kampagnen, die beim letzten sauberen Lauf noch nicht aktiv waren, dann die teuerste. Geteilte Google-Budgets zählen einmal.
  • Verstoß = Kampagne über das normale Pause-Tool pausieren (setAdsCampaignStatus PAUSED, metaUpdateStatus PAUSED, openaiAdsSetStatus paused). Budget wird nie geändert, nichts gelöscht. Danach Mail an den Workspace (sendAdminEmail, Empfänger Platform.ads.workspaces.<code>.notify_emails, sonst admin_emails) mit Plattform, Kampagne, Tagesbudget, Grund, Ergebnis.
  • Meta-AdSets zählen mit, außer effective_status PAUSED, ARCHIVED, DELETED, CAMPAIGN_PAUSED (also auch IN_PROCESS, WITH_ISSUES; ohne Feld gilt ACTIVE).
  • Nicht raten: Plattform nicht lesbar (Fehler, zu viele Kampagnen, Konto nicht in EUR — Währung je Konto: Google customer.currency_code per queryAds, Meta currency des Ad-Accounts per metaGetAdAccount, ChatGPT currency_code) oder aktive Kampagne mit Laufzeitbudget = Meldung, nichts pausiert. Die Gesamtsumme gilt dann als Untergrenze; liegt schon sie über dem Deckel, wird trotzdem pausiert. Lesefehler machen den Lauf zum Fehler (Backoff, Monitor).
  • Je Kampagne bzw. Hinweis höchstens eine Mail pro Tag ($ctx['cache']); scheitert die Mail, kommt sie im nächsten Lauf.
  • Probelauf ohne Pausieren: bin/cake test_tool -t meco --tool auditAdsBudgetCaps --args '{"dry_run":true}'.

Wieder einschalten geht nur über die normalen Tools (Obergrenze, Deckel, Freigabe greifen dort). Wer eine Kampagne im Ads Manager selbst anlegt, sollte das Budget dort im Deckel halten, sonst pausiert der Audit sie innerhalb einer Stunde.

Einrichten (pro Workspace)

  1. Im Ads Manager unter Settings einen API-Key anlegen.
  2. In tenants_untracked/<code>/.env als OPENAI_ADS_API_KEY=… ablegen (prod: shared/tenants_untracked/<code>/.env).
  3. In apis.php des Workspaces:
'openai_ads' => [
    'base_url' => 'https://api.ads.openai.com/v1/',
    'headers' => [
        'Authorization' => 'Bearer {{secret:OPENAI_ADS_API_KEY}}',
        'Accept' => 'application/json',
    ],
    'read_timeout' => 25,
    'max_daily_budget_eur' => 30,
    'max_bid_eur' => 5,
    'allowed_target_hosts' => ['example.de'],
],
  1. Prüfen: bin/cake test_tool -t <code> --tool openaiAdsListCampaigns.

Tests: tests/TestCase/Tooling/OpenaiAdsToolsTest.php (Fake-API).

Zuletzt aktualisiert: 2026-11-16