广告组

列出广告组

列出某个广告系列下的广告组。

GET /ad_groups

curl -X GET "https://api.ads.openai.com/v1/ad_groups?campaign_id=cmpn_101&limit=10" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "adgrp_301",
      "created_at": 1735689700,
      "updated_at": 1735776100,
      "name": "US English",
      "description": "Primary English-speaking audience.",
      "context_hints": ["productivity", "team collaboration"],
      "status": "active",
      "bidding_config": {
        "billing_event_type": "impression",
        "max_bid_micros": 60000
      }
    }
  ],
  "first_id": "adgrp_301",
  "last_id": "adgrp_301",
  "has_more": false
}

创建广告组

为广告系列创建广告组。

POST /ad_groups

字段说明

上下文提示提供了关于您认为广告何时会有用的额外信息，并有助于指导广告的展示时机。请提供一份描述或关键词列表，说明产品或服务在何时展示可能有用。

Micros 是主要货币单位（例如美元）的百万分之一。max_bid 字段针对的是每个事件，因此 60 美元 CPM（每次展示 0.06 美元）在 API 中应传入 60,000。请注意，货币字段遵循您广告账户的默认货币。

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",
    "description": "Primary English-speaking audience.",
    "context_hints": ["productivity", "team collaboration"],
    "status": "active",
    "bidding_config": {
      "billing_event_type": "impression",
      "max_bid_micros": 60000
    }
  }'

检索广告组

按 ID 获取单个广告组。

GET /ad_groups/{ad_group_id}

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

更新广告组

使用 POST 更新广告组。

POST /ad_groups/{ad_group_id}

更新时所有字段均为可选。可以将 description 设置为 null 以清除它。如果包含 bidding_config，请发送完整对象。status 接受 active（激活）、paused（暂停）或 archived（归档）。

curl -X POST "https://api.ads.openai.com/v1/ad_groups/adgrp_301" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context_hints": ["productivity", "workflow automation"],
    "status": "paused",
    "bidding_config": {
      "billing_event_type": "impression",
      "max_bid_micros": 75000
    }
  }'

通过专用操作更改状态

广告 API 还提供显式的状态转换。已暂停的广告组不会向用户投放广告。仅对不再需要的对象进行归档，因为归档操作是不可逆的。

• POST /ad_groups/{ad_group_id}/activate
• POST /ad_groups/{ad_group_id}/pause
• POST /ad_groups/{ad_group_id}/archive

curl -X POST "https://api.ads.openai.com/v1/ad_groups/adgrp_301/archive" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY"

{
  "id": "adgrp_301",
  "created_at": 1735689700,
  "updated_at": 1735948800,
  "name": "US English",
  "description": "Primary English-speaking audience.",
  "context_hints": ["productivity", "team collaboration"],
  "status": "archived",
  "bidding_config": {
    "billing_event_type": "impression",
    "max_bid_micros": 60000
  }
}