SuperAPI AI 工具集

openai-ads-api

营销与增长

查看项目

更新于 10-16 07:17

技能介绍

用途:该技能用于操作 OpenAI Ads Advertiser API,覆盖广告账户检查、广告系列(campaign)、广告组(ad group)、广告(ad)的规划、查看、创建、更新、暂停、激活、归档、预览与报告。核心目标是准确调用 API,并对花费保持显式控制。

主要能力与工作方式:先区分“规划或载荷审查”与“变更真实广告账户”的请求,规划请求不应转化为 API 变更。凭据不打印,优先使用环境变量 OPENAI_ADS_API_KEY,否则读取 ~/.config/openai-ads/token,并要求该文件仅用户可读(chmod 600);两者都没有时,提示用户需在 Ads Manager 签发 Ads API key,并可提供存储到该文件。任何实时变更前调用 GET /ad_account,核对账户 ID、名称、状态、审核状态、时区和货币;变更前先解析 campaign → ad group → ad 层级并检索现有对象。新建广告系列按创意素材、campaign、ad group、ad 的依赖顺序创建,保存返回 ID;除非用户明确要求实时投放,创建对象使用 status: "paused"。预算与出价写入前需以账户货币和整数微秒值双重表达。写入后检索受影响对象并报告 ID 与生效状态,广告还需报告 review_status,预览 24 小时后过期。报告时选择最窄的 insights 范围及明确时间范围、聚合、粒度和字段,has_more 为 true 时按游标取完,派生指标如 CTR、CPC 需标注并防除零。

变更安全:直接指令仅授权其命名的变更;目标不明确时询问账户或对象身份。激活可能产生花费,需明确授权,否则保持暂停并返回激活命令。归档不可逆,仅在明确要求归档确切对象时执行,临时关闭优先用暂停。不得静默提高预算或出价、扩大定向、移除结束时间或清空字段,须先展示前后值。变更超时或结果不确定时先检索或列出对象再重试,不要盲目重复创建或状态转换。报告失败时保留 HTTP 状态和响应体,但隐去 bearer token 等机密。

API 约定:基础地址 https://api.ads.openai.com/v1;认证 Authorization: Bearer $OPENAI_ADS_API_KEY;普通请求用 JSON,POST /upload 接受带 image_url 的 JSON 或带 file 的 multipart 表单;更新用 POST /resource/{id},不用 PATCH 或 PUT;更新 campaign 预算、ad-group bidding_config 或 ad creative 时发送完整嵌套对象;仅状态变更优先使用专用 activate、pause、archive 动作。

完成报告需说明是 dry run 还是实时 API 操作;实时操作需包含已验证的广告账户、受影响资源 ID、最终状态、货币与微秒的预算/出价、广告审核状态及后续事项,且绝不包含 API key。限制:API 可能变化,编写或执行请求前应查阅 https://developers.openai.com/ads/ 官方最新页面,仅使用官方文档;产品 feed、自定义受众、定向、转化优化或转化设置需阅读各自专门指南,不要从快速开始外推。关于收费、价格、具体平台支持或效果数据,资料未提供。