# 推广活动创建

> 来源：https://help.gravity-engine.com/docs/server-integration/other-apis/promoted-object-create
> 通过 Gravity Engine OpenAPI 创建推广活动，了解认证签名、应用 ID、活动名称、回调链接、请求示例及返回字段。



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

## 接入准备 [#接入准备]

在[引力后台－引力开发者](https://web.gravity-engine.com/#/manage/develop)申请开发者应用，审核通过并启用后，获取 `app_key`。所在主体需已开通 OpenAPI 功能；请求只能操作当前主体有权限的应用。

`app_key` 是开发者应用的凭证；请求中的 `app_id` 是引力业务应用 ID，两者用途不同。业务应用 ID 可通过[应用信息查询](/docs/server-integration/other-apis/app-info)获取。

## 认证方式 [#认证方式]

| Header          | 类型     | 必填 | 说明                                                                                 |
| --------------- | ------ | -- | ---------------------------------------------------------------------------------- |
| `Authorization` | string | 是  | 按[签名生成](/docs/server-integration/request-signing)生成的 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 参数 [#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 | 本次请求的签名，参考[签名生成](/docs/server-integration/request-signing) |

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

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

### 请求示例 [#请求示例]

```bash
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"
  }'
```

## 返回结果 [#返回结果]

### 应答示例 [#应答示例]

```json
{
  "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`，且不包含字段级错误；此时不能判定创建成功。
* 接口不提供幂等请求号，同名活动也不保证去重。超时或返回结果不明确时，先通过[推广活动列表](/docs/server-integration/other-apis/promoted-object-list)查询核对，再决定是否重试，避免重复创建。
* 缺少认证信息、签名错误、开发者应用不可用或请求被限流时，请检查 `code`、`msg` 和 `extra.error`。限流额度以开发者应用实际配置为准；遇到限流请降低调用频率并退避重试。