巨量引擎营销 API 完整文档

苏承栈

2026-07-03 • 👁 0人浏览过

巨量引擎营销 API 完整文档基于官方 OceanEngine Open Platform 和 Java SDK (oceanengine-mapi-java-client v1.1.85) 整理文档更新时间: 2026-05-04 目录快速开始认证授权 SDK 配置广告主账户 API 广告投放结构广告组管理广告单元管理创意管理 DMP 人群包定向包管理数据报表资金管理错误码参考 1. 快速开始 1.1 Maven 依赖



org.openapitools

oceanengine-mapi-java-client

1.1.85

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/

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/

// 请求参数:

// grant_type: "refresh_token"
// client_id: 应用ID
// client_secret: 应用密钥
// refresh_token: 刷新令牌

2.5 获取已授权账户接口 :

GET /oauth2/application/accounts

// 返回已授权的广告主账户列表

// {
//   "list": [
//     {"account_id": "xxx", "account_name": "xxx"}
//   ]
// }

2.6 Token 有效期 Token 类型有效期说明 access_token24 小时 (86400 秒)用于 API 请求认证refresh_token30 天 (2592000 秒)用于刷新 access_token 建议 : 每日更新 Token，或在 access_token 过期前使用 refresh_token 刷新建议缓存 Token，避免频繁请求 3. SDK 配置 3.1 初始化 ApiClient

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 实例

import com.bytedance.ads.api.AdvertiserInfoV2Api;


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

4. 广告主账户 API 4.1 获取广告主信息接口 :

GET /2/advertiser/info/

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/

// 返回账户余额信息

// {
//   "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/

// 请求示例:

// {
//   "advertiser_id": 123456,
//   "campaign_id": 17283746159,
//   "name": "我的广告组",
//   "billing_event": "CLICK",
//   "bid": 1.5,
//   "budget": 1000.0
// }

6.2 查询广告组列表接口 :

GET /2/adgroup/get/

import com.bytedance.ads.model.AdGroupGetV2Filtering;


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


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

6.3 更新广告组接口 :

POST /2/adgroup/update/

// 请求示例:

// {
//   "advertiser_id": 123456,
//   "adgroup_id": 789012,
//   "name": "修改后的广告组名",
//   "bid": 2.0
// }

6.4 删除广告组接口 :

POST /2/adgroup/delete/

// 请求示例:

// {
//   "advertiser_id": 123456,
//   "adgroup_id": 789012
// }

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

7.1 创建广告单元接口 :

POST /2/ad/create/

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/

// 支持按 campaign_id, adgroup_id, status 等条件过滤

// 返回分页列表，包含基本信息和状态

7.3 更新广告单元接口 :

POST /2/ad/update/

7.4 删除广告单元接口 :

POST /2/ad/delete/

8. 创意管理 8.1 上传图片接口 :

POST /creative/upload/image

POST /creative/upload/image

Content-Type: multipart/form-data


advertiser_id: 123456
image_file: @/path/to/image.jpg
filename: my_ad_image.jpg

// 响应示例:

// {
//   "creative_id": "CRV123456789",
//   "creative_list": [{
//     "id": "CRV123456789",
//     "type": "IMAGE",
//     "url": "http://example.com/image.jpg"
//   }]
// }

8.2 上传视频接口 :

POST /creative/upload/video

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/

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 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

{

"audience_name": "目标人群",
"description": "目标用户描述",
"source_type": "file_upload",
"file_id": 12345
}

9.2 查询人群包列表接口 :

GET /api/dmp/audiences

{

"page": 1,
"page_size": 20
}

9.3 获取人群包详情接口 :

GET /api/dmp/audiences/{id}

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

接口 :

POST /dmp/audience/publish

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_id20002账户余额不足充值后再投放30001创意审核拒绝修改创意内容重新提交30002定向包不存在检查定向包ID 13.2 HTTP 状态码状态码说明 200请求成功400请求参数错误401未授权或 token 过期403无权限访问429请求过于频繁500服务器内部错误附录 A. SDK 初始化完整示例

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 调用示例

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.comJava 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 版本整理

相关文章