列出广告
列出某个广告组下的广告。
GET /ads
| 参数 | 类型 | 必需 | 备注 |
|---|---|---|---|
ad_group_id | string | 是 | 父级广告组 ID。 |
limit | 整数 | 否 | 介于 1 和 500 之间。默认值为 20。 |
after | string | 否 | 下一页的游标。 |
before | string | 否 | 上一页的游标。 |
order | string | 否 | asc 或 desc。 |
curl -X GET "https://api.ads.openai.com/v1/ads?ad_group_id=adgrp_301&limit=10" \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY"{
"object": "list",
"data": [
{
"id": "ad_501",
"name": "Planner launch card",
"created_at": 1735689800,
"updated_at": 1735776200,
"creative": {
"type": "chat_card",
"title": "Try the new workspace planner",
"body": "Coordinate tasks, docs, and meetings in one place.",
"file_id": "file_901",
"image_url": "https://cdn.openai.com/ads/file_901.png",
"target_url": "https://example.com/workspace-planner"
},
"status": "active",
"review_status": "approved"
}
],
"first_id": "ad_501",
"last_id": "ad_501",
"has_more": false
}创建广告
为广告组创建一个广告。
POST /ads
| 字段 | 类型 | 必需 | 备注 |
|---|---|---|---|
ad_group_id | string | 是 | 父级广告组 ID。 |
name | string | 是 | 3 到 1000 个字符，且必须包含非空格字符。用于组织，不会向最终用户显示。 |
creative.type | string | 是 | 目前必须为 chat_card。 |
creative.title | string | 是 | 3 到 50 个字符。 |
creative.body | string | 是 | 最多 100 个字符。 |
creative.target_url | string | 是 | 目标 URL。 |
creative.file_id | string | 是 | 由 POST /upload 返回的文件 ID。 |
status | string | 是 | active（激活）或 paused（暂停）。 |
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"
}
}'检索广告
通过 ID 获取单个广告。
GET /ads/{ad_id}
curl -X GET "https://api.ads.openai.com/v1/ads/ad_501" \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY"更新广告
使用 POST 更新广告。
POST /ads/{ad_id}
更新时所有字段均为可选。如果包含 creative，请发送完整的创意对象。status 接受 active（激活）、paused（暂停）或 archived（归档）。
curl -X POST "https://api.ads.openai.com/v1/ads/ad_501" \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Planner launch card v2",
"status": "paused",
"creative": {
"type": "chat_card",
"title": "Plan work faster",
"body": "Bring tasks, docs, and meetings together.",
"target_url": "https://example.com/workspace-planner",
"file_id": "file_901"
}
}'审核状态
每个广告响应都包含 review_status，其状态可以是
in_review（审核中）rejected（已拒绝）approved（已批准）
如果您的广告被拒绝，说明它违反了我们的广告政策。请编辑您的广告以重新提交审核。
通过专用操作更改状态
Ads API 还公开了明确的状态转换。已暂停的广告不会投放给客户。仅归档您不再使用的对象，因为归档操作不可逆。
POST /ads/{ad_id}/activatePOST /ads/{ad_id}/pausePOST /ads/{ad_id}/archive
curl -X POST "https://api.ads.openai.com/v1/ads/ad_501/pause" \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY"{
"id": "ad_501",
"name": "Planner launch card",
"created_at": 1735689800,
"updated_at": 1736035200,
"creative": {
"type": "chat_card",
"title": "Try the new workspace planner",
"body": "Coordinate tasks, docs, and meetings in one place.",
"file_id": "file_901",
"image_url": "https://cdn.openai.com/ads/file_901.png",
"target_url": "https://example.com/workspace-planner"
},
"status": "paused",
"review_status": "approved"
}