服务端集成 · 其他 · 推广活动创建

通过 Gravity Engine OpenAPI 创建推广活动，了解认证签名、应用 ID、活动名称、回调链接、请求示例及返回字段。

此接口用于在指定引力应用下创建推广活动，返回系统生成的推广活动 ID。创建的是引力后台的推广活动配置；如需在广告媒体创建投放计划，请使用对应媒体的接口。

接入准备

在引力后台－引力开发者申请开发者应用，审核通过并启用后，获取 app_key。所在主体需已开通 OpenAPI 功能；请求只能操作当前主体有权限的应用。

app_key 是开发者应用的凭证；请求中的 app_id 是引力业务应用 ID，两者用途不同。业务应用 ID 可通过应用信息查询获取。

认证方式

Header	类型	必填	说明
`Authorization`	string	是	按签名生成生成的 JWT 字符串，直接填写，不添加 `Bearer` 前缀
`Content-Type`	string	是	`application/json`

将本次实际发送的全部 body 参数（不含 sign）用于生成 sign，再使用 sign 与 app_key 生成 Authorization。修改任何参数后都需要重新生成两者。以下示例中的 ID、签名、认证字符串和返回数据均为示意值，调用时请替换。

接口信息

请求地址：https://api-insight.gravity-engine.com/openapi/api/v1/user/promoted_object/create/
请求方法：POST
请求格式：JSON body。

body 参数

参数名	必填	类型	说明
`app_id`	是	int	所属引力业务应用 ID，必须为当前主体有权限的应用
`turbo_promoted_object_name`	是	string	推广活动名称，最长 100 个字符，不可为空
`callback_url`	否	string	回调链接，最长 16384 个字符；单条最长 4096 个字符。多条链接使用英文逗号分隔；省略或传空字符串表示不设置
`redirect_url`	否	string	合法的重定向 URL，最长 4096 个字符；省略或传空字符串表示不设置
`remark`	否	string	备注，最长 512 个字符
`sign`	是	string	本次请求的签名，参考签名生成

callback_url 支持公网 http://、https:// 完整链接，也支持 ?key=value 形式的参数填充配置。完整链接会进行公网地址校验，请勿填写本地或内网地址。

turbo_promoted_object_id 由系统自动生成，无需传入。创建后 state 默认为 1（启用）；本接口不提供状态设置或活动更新能力。

请求示例

curl --request POST 'https://api-insight.gravity-engine.com/openapi/api/v1/user/promoted_object/create/' \
  --header 'Authorization: YOUR_AUTHORIZATION' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "app_id": 12345678,
    "turbo_promoted_object_name": "秋季推广活动",
    "remark": "秋季投放",
    "sign": "YOUR_SIGN"
  }'

返回结果

应答示例

{
  "data": {
    "promoted_object": {
      "app_id": 12345678,
      "turbo_promoted_object_id": "a1b2c3d4e5f6g7h8",
      "turbo_promoted_object_name": "秋季推广活动",
      "callback_url": "",
      "redirect_url": "",
      "remark": "秋季投放",
      "state": 1,
      "create_time": "2026-10-17 10:00:00",
      "modify_time": "2026-10-17 10:00:00",
      "create_user_id": 10001,
      "create_user_name": "管理员",
      "operator_id": 10001,
      "operator_name": "管理员",
      "update_user_id": 0,
      "update_user_name": ""
    }
  },
  "extra": {
    "error": "",
    "request_id": "0123456789abcdef0123456789abcdef"
  },
  "code": 0,
  "msg": "成功"
}

返回字段

字段	类型	说明
`code`	int	外层业务状态码，`0` 表示外层处理成功；仍需确认返回了活动 ID
`msg`	string	状态描述
`extra.error`	string	错误描述，正常时为空字符串
`extra.request_id`	string	请求标识，排查问题时请提供
`data.promoted_object`	object	创建的推广活动对象

data.promoted_object 包含以下字段，时间按北京时间（UTC+8）返回：

字段	类型	说明
`app_id`	int	所属引力业务应用 ID
`turbo_promoted_object_id`	string	系统生成的 16 位推广活动 ID
`turbo_promoted_object_name`	string	推广活动名称
`callback_url`	string	回调链接；未设置时为空字符串
`redirect_url`	string	重定向地址；未设置时为空字符串
`remark`	string	备注
`state`	int	活动状态：`1` 启用、`2` 关停
`create_time`	string	创建时间，格式 `YYYY-MM-DD HH:mm:ss`
`modify_time`	string	最后修改时间，格式 `YYYY-MM-DD HH:mm:ss`
`create_user_id` / `create_user_name`	int / string	创建人 ID / 名称
`operator_id` / `operator_name`	int / string	操作人 ID / 名称
`update_user_id` / `update_user_name`	int / string	最后更新人 ID / 名称；尚未更新时通常为 `0` / 空字符串

调用注意事项

以 code=0、extra.error 为空且 data.promoted_object.turbo_promoted_object_id 非空共同确认创建成功。当前接口在部分应用权限、表单校验失败场景下，可能仅返回空的 data，外层仍为 code=0，且不包含字段级错误；此时不能判定创建成功。
接口不提供幂等请求号，同名活动也不保证去重。超时或返回结果不明确时，先通过推广活动列表查询核对，再决定是否重试，避免重复创建。
缺少认证信息、签名错误、开发者应用不可用或请求被限流时，请检查 code、msg 和 extra.error。限流额度以开发者应用实际配置为准；遇到限流请降低调用频率并退避重试。

推广活动创建

本页内容