ChatGPT Ads
Publicité ChatGPT

Démarrage rapide de l'API Ads (Quickstart)

Idée centrale

Ce guide de démarrage rapide documente l'implémentation minimale permettant de faire vivre une campagne publicitaire de bout en bout par l'API REST Ads d'OpenAI : de la vérification de l'accès au compte jusqu'à la lecture des résultats de performance. Le parcours suit exactement la hiérarchie campagne → groupe d'annonces → annonce : une annonce vit dans un groupe d'annonces, qui vit lui-même dans une campagne ; campagnes et groupes d'annonces portent budget et ciblage, les annonces portent le contenu créatif (titre, description, images).

Définition

La séquence minimale en six étapes recommandée par la documentation développeur Ads pour un premier appel API réussi de bout en bout, chaque étape produisant un identifiant consommé par l'étape suivante.

Contexte

S'appuie sur Authentification, compte publicitaire et fichiers dans l'API Ads pour la vérification d'accès et l'upload, sur Campagnes et annonces dans l'API Ads pour la création de campagne/groupe/annonce, et sur Insights et reporting dans l'API Ads pour la lecture finale des métriques. Point de départ recommandé avant Configuration d'un compte partenaire via l'API Ads (API Partner Setup) pour les partenaires gérant des comptes clients. Capturée le 2026-08-08.

Fonctionnement

Étape 1 — Confirmer l'accès au compte

Clé API émise depuis l'onglet Settings du compte Ads Manager (ads.openai.com).

curl -X GET "https://api.ads.openai.com/v1/ad_account" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Accept: application/json"

Réponse : objet ad_account (id, name, url, preview_url, status, timezone, currency_code, review.status) — voir Authentification, compte publicitaire et fichiers dans l'API Ads pour le détail complet.

Étape 2 — Téléverser un asset créatif

curl -X POST "https://api.ads.openai.com/v1/upload" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.com/assets/workspace-planner-card.png" }'

Réponse : {"file_id": "file_901"}.

Étape 3 — Créer une campagne

curl -X POST "https://api.ads.openai.com/v1/campaigns" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring launch",
    "status": "active",
    "budget": { "lifetime_spend_limit_micros": 25000000 }
  }'

Réponse type : {"id": "cmpn_101", ...}, avec par défaut bidding_type: "impressions", conversion_event_setting_ids: [], description/end_time/mode/start_time à null, targeting: {}.

Étape 4 — Créer un groupe d'annonces

curl -X POST "https://api.ads.openai.com/v1/ad_groups" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "cmpn_101",
    "name": "US English",
    "status": "active",
    "context_hints": ["productivity", "team collaboration"],
    "bidding_config": {
      "billing_event_type": "impression",
      "max_bid_micros": 60000
    }
  }'

Réponse type : {"id": "adgrp_301", ...}, avec context_hints, bidding_config repris tels quels.

Étape 5 — Créer une annonce

curl -X POST "https://api.ads.openai.com/v1/ads" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_group_id": "adgrp_301",
    "name": "Planner launch card",
    "status": "active",
    "creative": {
      "type": "chat_card",
      "title": "Try the new workspace planner",
      "body": "Coordinate tasks, docs, and meetings in one place.",
      "target_url": "https://example.com/workspace-planner",
      "file_id": "file_901"
    }
  }'

Réponse type : {"id": "ad_501", ..., "status": "active", "review_status": "in_review"}. Une annonce nouvellement créée porte un status (choisi par l'appelant) distinct d'un review_status (déterminé par la plateforme) — voir Campagnes et annonces dans l'API Ads pour le détail du cycle de revue.

Étape 6 — Récupérer les insights

curl -sS -G "https://api.ads.openai.com/v1/ads/ad_501/insights" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  --data-urlencode "time_granularity=daily" \
  --data-urlencode "limit=7"

Réponse : liste paginée (object: "list", data[], first_id/last_id/has_more), chaque ligne portant un id composite (start=<timestamp>:end=<timestamp>:entity_id=ad_501), readable_time, timezone, impressions, clicks, spend — voir Insights et reporting dans l'API Ads pour le détail complet de ces endpoints.

Étapes suivantes

Le guide renvoie vers les pages de référence complémentaires : Authentification, compte publicitaire et fichiers dans l'API Ads (Authentication, Ad Account, Files), Campagnes et annonces dans l'API Ads (Campaigns, Ads), Ciblage géographique des campagnes dans l'API Ads (Campaign Targeting), Création de campagnes à flux produits via l'API Ads (Product Feeds), Insights et reporting dans l'API Ads.

Éléments essentiels

Distinctions importantes

Ne pas confondre status d'une annonce nouvellement créée (active, choisi par l'appelant) et review_status (in_review dans cet exemple, déterminé par la plateforme après création) : deux informations distinctes sur le même objet.

Cas pratiques

Aucun cas pratique disponible : les valeurs d'exemple (identifiants, montants, dates) sont manifestement fictives et illustratives (adacct_123, cmpn_101, Acme Ads) — à ne jamais confondre avec des données réelles de production.

Erreurs fréquentes

Ne pas oublier de vérifier l'accès au compte (étape 1) avant toute autre opération : c'est le point de départ recommandé pour confirmer que la clé API fonctionne.

Ne pas confondre l'ordre de création : un groupe d'annonces nécessite un campaign_id existant, une annonce nécessite un ad_group_id existant — la hiérarchie campagne → groupe → annonce doit être respectée dans cet ordre.

Limites et nuances

Relations

Points à vérifier

Sources