广告请求 API

广告投放引擎接口前缀为 /ad，无需鉴权，供投放到页面的 SDK / 广告位实时请求广告。生产环境通常经由 js.adbnk.co（SDK）与主域名访问。

请求前需先在流量主后台创建广告位并获取 zone_key（形如 zone_ab12cd34），见流量主 API · 广告位。

请求广告

GET /ad/request 或 POST /ad/request

zone_id 与 zone 二选一必填。

参数	类型	必填	说明
`zone_id`	int	是*	广告位数字 ID
`zone`	string	是*	广告位编码 `zone_key`（与 `zone_id` 二选一）
`limit`	int	否	返回广告数量，默认 1
`page_url`	string	否	广告所在页面 URL（内容定向，缺省取 Referer）
`page_title`	string	否	页面标题
`page_keywords`	string	否	页面关键词
`page_category`	string	否	页面分类
`page_type`	string	否	页面类型（`article`/`video`/`product` 等）
`page_tags`	string	否	页面标签，逗号分隔
`page_lang`	string	否	页面语言
`_v`	int	否	协议版本，`2` 起启用混淆/签名协议
`_d`	string	否	v2 协议下混淆编码的设备指纹数据

也支持路径形式：GET /ad/request/{zone_id}（按 zone_key 或其数字部分匹配）。

bash

curl "https://api.adbnk.co/ad/request?zone=zone_ab12cd34&limit=1&page_url=https%3A%2F%2Fblog.example.com%2Fpost%2F1"

返回结构

json

{
  "code": 0,
  "message": "success",
  "data": {
    "request_id": "20260710120000a1b2c3d4e5f6a7b8",
    "zone": {
      "id": 5,
      "code": "zone_ab12cd34",
      "width": 300,
      "height": 250,
      "type": "BANNER",
      "refresh": 0
    },
    "ads": [
      {
        "id": "q1w2e3r4t5y6...",
        "type": "IMAGE",
        "title": "夏季大促",
        "description": "全场 5 折起",
        "button_text": "立即选购",
        "brand_name": "Example Shop",
        "image_url": "https://cdn.adbnk.co/creatives/1.jpg",
        "video_url": null,
        "icon_url": null,
        "landing_url": "https://track.adbnk.co/track/click/q1w2e3r4t5y6...",
        "click_url": "https://track.adbnk.co/track/click/q1w2e3r4t5y6...",
        "impression_url": "https://track.adbnk.co/track/impression/q1w2e3r4t5y6...",
        "width": 300,
        "height": 250,
        "pricing_model": "CPC",
        "html": "<!DOCTYPE html>...<span class=\"ad-badge\">AD</span>..."
      }
    ],
    "qa_k": "…",
    "_rand": "…",
    "_ts": 1752200000,
    "_v": 2
  },
  "timestamp": 1752200000
}

无可用广告时返回 data.ads 为空数组、message 为「无可用广告」。

creative 结构

ads[] 中每条即一个可展示的创意：

字段	类型	说明
`id`	string	追踪 ID（`track_id`），加密封装了 request/creative/ad/zone/bid 信息
`type`	string	创意类型：`IMAGE`/`NATIVE`/`VIDEO`/`RICH_MEDIA` 等
`title` / `description`	string	标题 / 描述文案
`button_text`	string	行动号召按钮文案（CTA）
`brand_name`	string	品牌名
`image_url` / `image_url_2`	string	图片 URL
`video_url`	string	视频 URL
`icon_url`	string	图标 URL
`display_url`	string	展示 URL
`landing_url` / `click_url`	string	点击追踪 URL（指向 `track.adbnk.co`）
`impression_url`	string	展示追踪像素 URL
`width` / `height`	int	创意尺寸
`pricing_model`	string	生效计费模式
`html`	string	服务端渲染好的完整广告 HTML，可直接用于 `iframe.srcdoc`
`html_content`	string	富媒体（`RICH_MEDIA`）模板渲染内容（存在时）

展示与点击追踪

SDK 无需自行拼接追踪地址：直接使用返回的 impression_url（展示时请求）与 click_url（点击跳转）即可，其中已内嵌加密 track_id。若直接渲染 html 字段，展示像素已注入其中。上报细节见事件与转化上报。

对于特殊广告位类型，zone 对象会附带额外配置：

POPUP / FLOAT / INTERSTITIAL：trigger（触发方式）、frequency（频次上限）、popup（弹窗行为）。
COUPLET（对联）：couplet（最小屏宽、偏移、关闭按钮等）。
REWARDED（激励）：rewarded（观看时长、可跳过时间、奖励数量/类型）。
EXIT_INTENT：frequency。

广告渲染（iframe 嵌入）

GET /ad/render/{zone_id}

直接返回一段可嵌入的广告 HTML 文档，适合以 <iframe src> 方式引入，无需前端处理 JSON。

html

<iframe src="https://api.adbnk.co/ad/render/5"
        width="300" height="250" frameborder="0" scrolling="no"></iframe>

VAST 视频广告

GET /ad/render/vast/{zone_id}

返回 VAST 2.0 / 4.2 XML，供支持 VAST 的视频播放器加载视频贴片广告。

bash

curl "https://api.adbnk.co/ad/render/vast/5"

激励广告 SSV

激励视频（Rewarded）提供服务端奖励校验（SSV）相关端点，位于 /ad/reward/*（如 /ad/reward/token、/ad/reward/verify、/ad/reward/keys、/ad/reward/ssv-callback）。集成方式以控制台「激励广告」配置与 SDK 文档为准。

下一步：事件与转化上报

广告请求 API ​

请求广告 ​

返回结构 ​

creative 结构 ​

广告渲染（iframe 嵌入） ​

VAST 视频广告 ​

激励广告 SSV ​