ChatGPT Ads
Publicité ChatGPT

Authentification, compte publicitaire et fichiers dans l'API Ads

Idée centrale

L'API Ads d'OpenAI (developers.openai.com/ads) est une API REST distincte de l'interface Ads Manager, destinée aux développeurs et intégrateurs techniques. Chaque requête s'authentifie par une clé API portée par un en-tête Authorization: Bearer, scopée à un seul compte publicitaire. Cette page regroupe les trois éléments socles sur lesquels reposent tous les autres points de terminaison de cette API : le mécanisme d'authentification, la ressource « compte publicitaire » (ad_account), et le point de terminaison générique de téléversement de fichiers (/upload), utilisé aussi bien pour les visuels de créations publicitaires que pour le favicon de marque du compte.

Définition

Trois ressources fondatrices de l'API REST Ads d'OpenAI, documentées ensemble parce qu'elles constituent le socle technique partagé (authentification, identité du compte, gestion des fichiers) consommé par toutes les autres pages de cette même API — notamment Campagnes et annonces dans l'API Ads.

Contexte

Cette page documente trois pages de la référence API (« api-reference ») de la documentation développeur Ads d'OpenAI : Authentication, Ad Account et Files. Ces trois pages appartiennent à un ensemble de huit pages de référence documentant une seule API REST cohérente (api.ads.openai.com/v1), aux côtés de Campaigns, Ads, Conversion Setup, Insights et Ad Groups — voir Campagnes et annonces dans l'API Ads, Configuration de la mesure de conversion dans l'API Ads (Conversion Setup) et Insights et reporting dans l'API Ads pour les autres pages de cette référence.

Point à vérifier signalé pour l'ensemble de la documentation technique : la page de référence « Ad Groups » (api-reference/ad-groups) n'a pas été récupérée dans le lot de sources traité ici. Elle documenterait le niveau intermédiaire de la hiérarchie campagne → groupe d'annonces → annonce. Son absence est un point à vérifier partout où la structure complète de l'API est pertinente.

Cette API est distincte de l'interface Ads Manager elle-même : elle s'adresse à un public de développeurs et de partenaires techniques (agences, plateformes) plutôt qu'aux annonceurs opérant depuis l'interface. Capturée le 2026-08-08.

Fonctionnement

Authentification et conventions générales

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

Ressource « compte publicitaire » (ad_account)

Lire les métadonnées du compte — GET /ad_account

Récupère les métadonnées du compte publicitaire courant (celui associé à la clé API utilisée). Aucun corps de requête ni paramètre de requête.

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

Réponse d'exemple :

{
  "id": "adacct_123",
  "name": "Acme Ads",
  "url": "https://www.acme.example",
  "preview_url": null,
  "status": "active",
  "timezone": "UTC",
  "currency_code": "USD",
  "review": {
    "status": "approved"
  }
}

Champs documentés :

ChampDescription
idIdentifiant du compte publicitaire, préfixe adacct_.
nameNom d'affichage du compte.
urlDestination principale du compte.
preview_urlURL de prévisualisation du favicon, quand disponible (nullable).
statusStatut du compte, quand disponible (« when an account status is available ») — exemple donné : active.
timezoneFuseau horaire du compte publicitaire.
currency_codeDevise du compte — exemple donné : USD.
review.statusStatut de revue de marque du compte — exemple donné : approved.

Mettre à jour les métadonnées de marque — POST /ad_account/brand

Définit le nom du compte et/ou déclenche une nouvelle revue de marque en changeant le favicon. Au moins un des deux champs suivants est requis :

ChampTypeRequisNotes
namestringNonNom d'affichage mis à jour du compte.
favicon_file_idstringNonID de fichier téléversé avec purpose: "account_favicon" (voir section Files ci-dessous).
 
curl -X POST "https://api.ads.openai.com/v1/ad_account/brand" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "favicon_file_id": "file_123"
  }'

La réponse contient le compte mis à jour. Il est recommandé d'interroger (« poll ») GET /ad_account jusqu'à ce que review.status vaille approved : un compte dans tout autre statut de revue ne peut pas diffuser d'annonces (« An account with any other review status cannot serve ads »).

Cette opération doit être activée pour le compte publicitaire concerné : si l'appel renvoie 403, il faut contacter son représentant partenaire OpenAI — l'activation n'est donc pas automatique pour tous les comptes.

Téléversement de fichiers — POST /upload

Point de terminaison unique et générique, utilisé pour deux usages distincts selon le champ optionnel purpose : fournir un visuel de création publicitaire (consommé par Campagnes et annonces dans l'API Ads) ou fournir un favicon de marque de compte (consommé par POST /ad_account/brand ci-dessus).

Téléverser depuis une URL d'image (JSON, champ image_url) :

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

Téléverser un fichier binaire (multipart/form-data) :

curl -X POST "https://api.ads.openai.com/v1/upload" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -F "file=@workspace-planner-card.png"

Téléverser un favicon de compte — régler purpose à account_favicon. Contrainte explicite : l'image doit faire au moins 128 × 128 pixels. L'API peut résoudre le favicon directement depuis le site web du client :

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://www.acme.example",
    "purpose": "account_favicon"
  }'

Ou en téléversement local, purpose comme champ de formulaire multipart :

curl -X POST "https://api.ads.openai.com/v1/upload" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -F "purpose=account_favicon" \
  -F "file=@acme-favicon.png"

Le file_id retourné s'assigne ensuite au compte via POST /ad_account/brand (voir ci-dessus).

Utilisation du fichier dans une annonce : le file_id retourné se passe dans creative.file_id lors de la création ou de la mise à jour d'une annonce via POST /ads — voir Campagnes et annonces dans l'API Ads.

Éléments essentiels

Distinctions importantes

Ne pas confondre l'objet Ad Account de l'API (GET /ad_account, ressource API REST authentifiée par jeton porteur) avec les paramètres de compte de l'interface Ads Manager documentés dans Configuration d'un compte Ads Manager : les deux couvrent des notions proches (identité et statut du compte) mais l'un est une ressource programmatique consommée par des intégrations techniques, l'autre un ensemble d'écrans destinés aux annonceurs.

Ne pas confondre les champs status (statut général du compte) et review.status (statut de revue de marque) : ce sont deux informations distinctes, chacune illustrée par un seul exemple de valeur (active et approved respectivement) dans les sources disponibles — la liste exhaustive des valeurs possibles pour chacun n'est pas documentée par ces pages.

Cas pratiques

Aucun cas pratique disponible : les sources ne fournissent que des exemples de requêtes et de réponses génériques (Acme Ads, file_123), pas de retour d'intégration réelle.

Erreurs fréquentes

Ne pas tenter d'appeler POST /ad_account/brand sans vérifier au préalable que la fonctionnalité est activée pour le compte : une réponse 403 signifie qu'il faut contacter un représentant partenaire OpenAI, pas retenter la requête telle quelle.

Ne pas oublier de fournir une image d'au moins 128 × 128 pixels pour un favicon de compte (purpose: "account_favicon") : c'est la seule contrainte de taille explicitement documentée pour POST /upload.

Ne pas supposer qu'un POST /ad_account/brand réussi rend immédiatement le compte apte à diffuser : il déclenche une revue asynchrone qu'il faut interroger via GET /ad_account jusqu'à review.status: "approved".

Limites et nuances

Relations

Points à vérifier

Sources