巨量引擎营销 API 完整文档

知识汲取者2026-05-18 17:57

巨量引擎营销 API 完整文档

基于官方 OceanEngine Open Platform 和 Java SDK (oceanengine-mapi-java-client v1.1.85) 整理

文档更新时间: 2026-05-04

目录

  1. 快速开始
  2. 认证授权
  3. [SDK 配置](#SDK 配置)
  4. [广告主账户 API](#广告主账户 API)
  5. 广告投放结构
  6. 广告组管理
  7. 广告单元管理
  8. 创意管理
  9. [DMP 人群包](#DMP 人群包)
  10. 定向包管理
  11. 数据报表
  12. 资金管理
  13. 错误码参考

1. 快速开始

1.1 Maven 依赖

xml 复制代码 
<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>oceanengine-mapi-java-client</artifactId>
    <version>1.1.85</version>
</dependency>

1.2 环境要求

  • Java 8+
  • Maven 3.x

1.3 核心 API 地址

环境 地址
生产环境 https://api.oceanengine.com
沙箱环境 https://api-sandbox.oceanengine.com

2. 认证授权

巨量引擎 API 采用 OAuth 2.0 协议进行认证授权。

2.1 授权流程

复制代码 
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   用户      │     │   你的应用   │     │  巨量引擎   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                  │                  │
       │  1. 访问授权页面   │                  │
       │─────────────────>│                  │
       │                  │  2. 跳转授权      │
       │<─────────────────│                  │
       │                  │                  │
       │  3. 用户授权      │                  │
       │─────────────────>│                  │
       │                  │  4. 回调code     │
       │<─────────────────│                  │
       │                  │                  │
       │                  │  5. 用code换Token │
       │                  │─────────────────>│
       │                  │                  │
       │                  │  6. 返回Token   │
       │                  │<─────────────────│

2.2 获取授权链接

复制代码 
GET https://api.oceanengine.com/oauth2/authorize

参数:
  - client_id: 应用的 Client ID
  - response_type: 固定为 "code"
  - redirect_uri: 回调地址
  - scope: 授权范围 (如 "advertiser_info")
  - state: 状态参数 (用于防止 CSRF)

2.3 获取 Access Token

接口 : POST /open_api/oauth2/access_token/

java 复制代码 
import com.bytedance.ads.ApiException;
import com.bytedance.ads.ApiClient;
import com.bytedance.ads.api.Oauth2AccessTokenApi;
import com.bytedance.ads.model.Oauth2AccessTokenRequest;
import com.bytedance.ads.model.Oauth2AccessTokenResponse;

// 构建请求
Oauth2AccessTokenApi api = new Oauth2AccessTokenApi();
ApiClient apiClient = api.getApiClient();
apiClient.setBasePath("https://api.oceanengine.com");
api.setApiClient(apiClient);

Oauth2AccessTokenRequest request = new Oauth2AccessTokenRequest();
request.setAppId(1234567890L);           // 应用ID
request.setSecret("your_app_secret");    // 应用密钥
request.setGrantType("auth_code");       // 授权类型
request.setAuthCode("authorization_code_from_callback");  // 授权码

// 调用接口
Oauth2AccessTokenResponse response = api.openApiOauth2AccessTokenPost(request);

// 解析响应
// {
//   "code": 0,
//   "message": "OK",
//   "data": {
//     "access_token": "xxx",
//     "expires_in": 86400,
//     "refresh_token": "xxx",
//     "refresh_token_expires_in": 2592000
//   }
// }
System.out.println("Access Token: " + response.getData().getAccessToken());

2.4 刷新 Refresh Token

接口 : POST /oauth2/refresh_token/

java 复制代码 
// 请求参数:
// grant_type: "refresh_token"
// client_id: 应用ID
// client_secret: 应用密钥
// refresh_token: 刷新令牌

2.5 获取已授权账户

接口 : GET /oauth2/application/accounts

java 复制代码 
// 返回已授权的广告主账户列表
// {
//   "list": [
//     {"account_id": "xxx", "account_name": "xxx"}
//   ]
// }

2.6 Token 有效期

Token 类型 有效期 说明
access_token 24 小时 (86400 秒) 用于 API 请求认证
refresh_token 30 天 (2592000 秒) 用于刷新 access_token

建议:

  • 每日更新 Token，或在 access_token 过期前使用 refresh_token 刷新
  • 建议缓存 Token，避免频繁请求

3. SDK 配置

3.1 初始化 ApiClient

java 复制代码 
import com.bytedance.ads.ApiClient;

ApiClient apiClient = new ApiClient();

// 设置 API 基础地址
apiClient.setBasePath("https://api.oceanengine.com");

// 设置 Access Token (必需)
apiClient.addDefaultHeader("Access-Token", "your_access_token");

// 设置自定义请求头 (可选)
apiClient.addDefaultHeader("X-Custom-Header", "custom_value");

// 设置连接超时 (毫秒)
apiClient.setConnectTimeout(30000);   // 30秒

// 设置读取超时 (毫秒)
apiClient.setReadTimeout(60000);       // 60秒

// 设置写入超时 (毫秒)
apiClient.setWriteTimeout(60000);     // 60秒

// 启用调试模式 (可选，生产环境建议关闭)
apiClient.setDebugging(true);

// 设置临时文件目录 (用于文件下载)
apiClient.setTempFolderPath("/tmp/oceanengine-sdk");

// SSL 配置 (生产环境建议保持默认 true)
apiClient.setVerifyingSsl(true);

3.2 应用配置到 API 实例

java 复制代码 
import com.bytedance.ads.api.AdvertiserInfoV2Api;

AdvertiserInfoV2Api api = new AdvertiserInfoV2Api();
api.setApiClient(apiClient);

4. 广告主账户 API

4.1 获取广告主信息

接口 : GET /2/advertiser/info/

java 复制代码 
import com.bytedance.ads.ApiException;
import com.bytedance.ads.ApiClient;
import com.bytedance.ads.api.AdvertiserInfoV2Api;

AdvertiserInfoV2Api api = new AdvertiserInfoV2Api();
api.setApiClient(apiClient);

try {
    // 参数: advertiser_ids (广告主ID列表)
    Long advertiserId = 1234567890L;

    // 调用接口
    // apiClient.addDefaultHeader("Access-Token", accessToken);
    // AdvertiserInfoV2Response response = api.openApi2AdvertiserInfoGetGet(advertiserId);

    System.out.println("广告主信息查询成功");
} catch (ApiException e) {
    System.err.println("API调用失败: " + e.getMessage());
    System.err.println("HTTP状态码: " + e.getCode());
}

4.2 获取账户余额

接口 : GET /2/advertiser/balance/get/

java 复制代码 
// 返回账户余额信息
// {
//   "balance": 10000.00,
//   "cash_balance": 8000.00,
//   "incentive_balance": 2000.00
// }

5. 广告投放结构

巨量引擎广告投放采用层级结构:

复制代码 
广告主 (Advertiser)
  └── 项目/广告系列 (Campaign)
        └── 广告组 (Ad Group)
              └── 广告计划/单元 (Ad Unit)
                    └── 创意 (Creative)

5.1 各层级说明

层级 说明 典型操作
Campaign (项目) 营销目标，如提升转化 创建、查询、修改预算
Ad Group (广告组) 定向和投放设置 创建、修改出价、定向
Ad Unit (广告单元) 具体投放内容 创建、修改出价、状态
Creative (创意) 广告展示内容 上传、创建、关联素材

6. 广告组管理

6.1 创建广告组

接口 : POST /2/adgroup/create/

java 复制代码 
// 请求示例:
// {
//   "advertiser_id": 123456,
//   "campaign_id": 17283746159,
//   "name": "我的广告组",
//   "billing_event": "CLICK",
//   "bid": 1.5,
//   "budget": 1000.0
// }

6.2 查询广告组列表

接口 : GET /2/adgroup/get/

java 复制代码 
import com.bytedance.ads.model.AdGroupGetV2Filtering;

AdGroupGetV2Filtering filtering = new AdGroupGetV2Filtering();
filtering.setCampaignIds(Arrays.asList(17283746159L));

// 返回分页的广告组列表

6.3 更新广告组

接口 : POST /2/adgroup/update/

java 复制代码 
// 请求示例:
// {
//   "advertiser_id": 123456,
//   "adgroup_id": 789012,
//   "name": "修改后的广告组名",
//   "bid": 2.0
// }

6.4 删除广告组

接口 : POST /2/adgroup/delete/

java 复制代码 
// 请求示例:
// {
//   "advertiser_id": 123456,
//   "adgroup_id": 789012
// }

7. 广告单元管理

广告单元 (Ad Unit) 是广告投放的核心单位，包含投放设置、出价、定向等。

7.1 创建广告单元

接口 : POST /2/ad/create/

java 复制代码 
package com.bytedance.ads.examples;

import com.bytedance.ads.ApiException;
import com.bytedance.ads.ApiClient;
import com.bytedance.ads.api.QianchuanAdCreateV10Api;
import com.bytedance.ads.model.QianchuanAdCreateV10Request;
import com.bytedance.ads.model.QianchuanAdCreateV10Response;

public class QianchuanAdCreateExample {
    public static void main(String[] args) {
        QianchuanAdCreateV10Api api = new QianchuanAdCreateV10Api();
        ApiClient apiClient = api.getApiClient();
        apiClient.setBasePath("https://api.oceanengine.com");
        apiClient.addDefaultHeader("Access-Token", "your_access_token");
        api.setApiClient(apiClient);

        try {
            QianchuanAdCreateV10Request request = new QianchuanAdCreateV10Request();
            request.setAdvertiserId(1234567890L);
            // 设置广告参数：推广目的、商品ID、直播间ID、出价等

            // POST /open_api/v1.0/qianchuan/ad/create/
            QianchuanAdCreateV10Response response = api.openApiV10QianchuanAdCreatePost(request);

            // 返回: {"code": 0, "message": "OK", "data": {"ad_id": 21394857623}}
            System.out.println("千川广告创建成功，ID: " + response.getData().getAdId());
        } catch (ApiException e) {
            System.err.println("创建失败: " + e.getMessage());
        }
    }
}

7.2 查询广告单元

接口 : GET /2/ad/get/

java 复制代码 
// 支持按 campaign_id, adgroup_id, status 等条件过滤
// 返回分页列表，包含基本信息和状态

7.3 更新广告单元

接口 : POST /2/ad/update/

7.4 删除广告单元

接口 : POST /2/ad/delete/

8. 创意管理

8.1 上传图片

接口 : POST /creative/upload/image

http 复制代码 
POST /creative/upload/image
Content-Type: multipart/form-data

advertiser_id: 123456
image_file: @/path/to/image.jpg
filename: my_ad_image.jpg
java 复制代码 
// 响应示例:
// {
//   "creative_id": "CRV123456789",
//   "creative_list": [{
//     "id": "CRV123456789",
//     "type": "IMAGE",
//     "url": "http://example.com/image.jpg"
//   }]
// }

8.2 上传视频

接口 : POST /creative/upload/video

http 复制代码 
POST /creative/upload/video
Content-Type: multipart/form-data

advertiser_id: 123456
video_file: @/path/to/video.mp4
filename: my_ad_video.mp4

8.3 查询创意列表

接口 : GET /2/creative/get/

java 复制代码 
import com.bytedance.ads.ApiException;
import com.bytedance.ads.ApiClient;
import com.bytedance.ads.api.CreativeGetV2Api;
import com.bytedance.ads.model.CreativeGetV2Response;
import com.bytedance.ads.model.CreativeGetV2Filtering;

import java.util.Arrays;
import java.util.List;

public class CreativeGetExample {
    public static void main(String[] args) {
        CreativeGetV2Api api = new CreativeGetV2Api();
        ApiClient apiClient = api.getApiClient();
        apiClient.setBasePath("https://api.oceanengine.com");
        apiClient.addDefaultHeader("Access-Token", "your_access_token");
        api.setApiClient(apiClient);

        try {
            Long advertiserId = 1234567890L;

            // 设置过滤条件
            CreativeGetV2Filtering filtering = new CreativeGetV2Filtering();
            filtering.setCampaignIds(Arrays.asList(17283746159L));
            filtering.setCreativeMaterialMode("CUSTOM_CREATIVE");

            // 指定返回字段
            List<String> fields = Arrays.asList(
                "creative_id", "ad_id", "status",
                "creative_material_mode", "image_mode"
            );

            Long page = 1L;
            Long pageSize = 20L;

            // GET /open_api/2/creative/get/
            CreativeGetV2Response response = api.openApi2CreativeGetGet(
                advertiserId, filtering, fields,
                page, pageSize, null, null
            );

            // 响应示例:
            // {
            //   "code": 0,
            //   "data": {
            //     "list": [{
            //       "creative_id": 20394857623,
            //       "status": "CREATIVE_STATUS_ENABLE",
            //       "image_mode": "CREATIVE_IMAGE_MODE_VIDEO"
            //     }],
            //     "page_info": {"total_number": 50, "page": 1, "page_size": 20}
            //   }
            // }
            System.out.println("创意列表: " + response);
        } catch (ApiException e) {
            System.err.println("查询失败: " + e.getMessage());
        }
    }
}

8.4 删除创意

接口 : POST /creative/delete

9. DMP 人群包

9.1 创建人群包

接口 : POST /api/dmp/audiences

json 复制代码 
{
  "audience_name": "目标人群",
  "description": "目标用户描述",
  "source_type": "file_upload",
  "file_id": 12345
}

9.2 查询人群包列表

接口 : GET /api/dmp/audiences

json 复制代码 
{
  "page": 1,
  "page_size": 20
}

9.3 获取人群包详情

接口 : GET /api/dmp/audiences/{id}

9.4 发布人群包

将 DMP 人群包发布到广告投放平台，使其可用于广告定向。

接口 : POST /dmp/audience/publish

http 复制代码 
POST https://ad.oceanengine.com/open_api/dmp/audience/publish/
Content-Type: application/json

{
    "advertiser_id": 123456,
    "audience_id": "your_audience_id"
}

9.5 推送到云图

接口 : POST /dmp/audience/push

将人群包推送到云图账户，实现精准营销投放。

10. 定向包管理

定向包用于设置广告投放的目标人群。

10.1 功能

  • 创建/更新/删除/查询定向包
  • 关联项目信息
  • 支持否定词管理（项目层级/营销层级）

10.2 否定词管理

类型 说明
项目否定词 批量添加/更新项目层级否定词
营销否定词 批量新增/更新营销层级否定词

作用: 排除不相关的搜索词或关键词，提高广告投放精准度。

11. 数据报表

11.1 报表类型

类型 说明
自定义报表 指标+维度自由组合
消耗报表 投放消耗数据
竞价投放数据 竞价广告详细数据
品牌投放数据 品牌广告数据
直播分析报表 直播间受众/分析数据
落地页数据 橙子建站/第三方落地页效果
下载任务 批量数据导出

11.2 创建下载任务

接口 : POST /report/dmp/create_task/

11.3 查询下载任务

接口 : GET /report/dmp/get_task/

12. 资金管理

12.1 账户钱包

  • 查询账户钱包信息
  • 获取账户实时余额

12.2 资金流水

  • 查询财务流水明细
  • 批量查询账户日流水

12.3 代理商功能

功能 说明
批量余额查询 批量查询账户余额
转账 发起转账、查询转账单
充值 授信充值、预付充值

12.4 资金共享

  • 共享钱包绑定/解绑
  • 批量查询钱包余额
  • 查询共享钱包流水
  • 设置子钱包预算和盯盘规则

13. 错误码参考

13.1 通用错误码

code 说明 解决方案
0 成功 -
10001 系统错误 重试或联系技术支持
10002 授权失败 检查 access_token 是否有效
10003 参数错误 检查请求参数格式
10005 频率限制 降低请求频率
20001 广告主不存在 检查 advertiser_id
20002 账户余额不足 充值后再投放
30001 创意审核拒绝 修改创意内容重新提交
30002 定向包不存在 检查定向包ID

13.2 HTTP 状态码

状态码 说明
200 请求成功
400 请求参数错误
401 未授权或 token 过期
403 无权限访问
429 请求过于频繁
500 服务器内部错误

附录

A. SDK 初始化完整示例

java 复制代码 
package demo;

import com.bytedance.ads.ApiClient;
import com.bytedance.ads.api.AdvertiserInfoV2Api;

public class OceanEngineSDKExample {
    public static void main(String[] args) {
        // 1. 创建 ApiClient
        ApiClient apiClient = new ApiClient();
        apiClient.setBasePath("https://api.oceanengine.com");
        apiClient.addDefaultHeader("Access-Token", "your_access_token");
        apiClient.setConnectTimeout(30000);
        apiClient.setReadTimeout(60000);
        apiClient.setDebugging(true);

        // 2. 创建 API 实例
        AdvertiserInfoV2Api api = new AdvertiserInfoV2Api();
        api.setApiClient(apiClient);

        // 3. 调用接口
        // AdvertiserInfoV2Response response = api.openApi2AdvertiserInfoGetGet(advertiserId);

        System.out.println("SDK 初始化完成");
    }
}

B. HTTP API 调用示例

java 复制代码 
package demo;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class HttpApiExample {
    public static void main(String[] args) throws Exception {
        String urlStr = "https://api.oceanengine.com/open_api/2/user/info/";
        String accessToken = "your_access_token";

        // 发送 GET 请求
        URL url = new URL(urlStr);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("GET");
        connection.setRequestProperty("Access-Token", accessToken);
        connection.setRequestProperty("Accept", "application/json");

        int responseCode = connection.getResponseCode();
        System.out.println("响应码: " + responseCode);

        // 读取响应
        BufferedReader in = new BufferedReader(
            new InputStreamReader(
                responseCode >= 200 && responseCode < 300
                    ? connection.getInputStream()
                    : connection.getErrorStream(),
                StandardCharsets.UTF_8
            )
        );

        StringBuilder response = new StringBuilder();
        String inputLine;
        while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
        }
        in.close();

        System.out.println("响应内容: " + response.toString());
        connection.disconnect();
    }
}

C. 相关资源链接

资源 链接
巨量引擎开放平台 https://open.oceanengine.com
Java SDK 源码 https://github.com/oceanengine/ad_open_sdk_java
沙箱环境 https://api-sandbox.oceanengine.com
开发者控制台 https://console.oceanengine.com

文档生成时间: 2026-05-04
基于官方 OceanEngine Open Platform API v2/v3 版本整理

相关推荐
DevnullCoffe1 小时前
用 MCP 让 AI Agent 直接批量下载亚马逊商品图片——原理、踩坑与实现
爬虫·python·api
Larry_Yanan2 小时前
QML面试常见问题（一）QML中组件呈现方式的方法有哪些
开发语言·c++·qt·ui·面试
Aurorar0rua2 小时前
CS50 x 2024 Notes C -12
c语言·开发语言·学习方法
techdashen2 小时前
深入 Rust enum 的内存世界
开发语言·后端·rust
时光Autistic2 小时前
【安装教程】AI标注工具X-AnyLabeling安装配置
人工智能·python
knight_9___2 小时前
大模型project面试7
人工智能·python·算法·面试·大模型·agent
yuhuofei20212 小时前
【Python入门】Python与PyCharm的安装
开发语言·python·pycharm
吴声子夜歌2 小时前
Java——类加载机制
java·开发语言·python
杨校2 小时前
杨校老师课堂之C++的位运算应用专项训练
开发语言·c++
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03Gemini大升级、AI眼镜首发、Android XR亮相，13天后见分晓04【AI】2026 年具身智能模型和世界模型总结05Codex 手机端连接教程：三分钟搞定，附完整步骤06CC-Switch & Claude 基于 Linux 服务器安装使用指南07人工智能最新动态 AI 日报 · 2026年5月10日08裂开！ChatGPT 居然开始要手机号验证，附详细解决方法09几个好用的ip纯净度检测网站10【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法