You need to enable JavaScript to run this app.
导航

内容推荐接口

最近更新时间2023.09.13 16:33:41

首次发布时间2021.07.05 21:23:10

概述

该接口主要用于图文、视频等内容的个性化推荐。

说明

  • 不建议存储推荐接口返回的数据:
    因图片视频url变化、失效,内容状态发生变化等不可控因素的影响,会导致内容无法展示或者播放,所以不建议存储推荐接口返回的数据,避免出现问题;
  • 不要使用同一个UniqUserId并发请求推荐接口:
    使用同一个UniqUserId进行并发请求,会导致内容展现读取错误,进而返回结果不符预期;
内容推荐

调前准备

  1. 接口鉴权
    详见:接口鉴权
  2. 接口配置
    详见:推荐配置
  3. 调用接口
    注意参数 是否必填,并确保 ServiceName、Action、Version 等url信息正确
    详见:下方接口信息

请求接口

请求方式

post

请求url:

https://cms.volcengineapi.com?Action=Feed&Version=2021-06-17

请求header:

ServiceName: volc_content_api

url组成:

Host: https://cms.volcengineapi.com

Action: Feed

Version: 2021-06-17

请求参数

字段名
字段类型
是否必填
说明
Context
Context
上下文信息
UniqUserId
string
用户唯一标识
Category
string
场景id,取值路径:控制台 - 内容分发 - 场景管理 - 场景ID
PersonalRec
number
是否使用个性化推荐,默认为1,详见:PersonalRec

相关字段取值

PersonalRec
描述
1
使用个性化推荐
0
不使用个性化推荐,按文章发文时间倒排返回
Province
河北、山西、辽宁、吉林、黑龙江、江苏、浙江、安徽、福建、江西、山东、河南、湖北、湖南、广东、海南、四川、贵州、云南、陕西、甘肃、青海、台湾
内蒙古、广西、西藏、宁夏、新疆
北京、天津、上海、重庆
香港、澳门
RefreshType
描述
open
首次打开APP(有置顶,有强插)
refresh
下拉刷新(有置顶,有强插)
loadmore
加载更多

响应字段

字段名
字段类型
是否必填
说明
BaseResp
BaseResp
Data
ArticleList

相关字段取值

GroupType
描述
article
图文
video
视频
short_video
小视频
short_content
短内容
topic
专题
DisplayTag
map - key
map - value
插入
tags
I
置顶
tags
A
TopicSource
描述
cms
通过控制台新建的专题
api
通过接口引入的专题
toutiao_api
火山专题,开通火山专题后返回

请求示例

{
    "UniqUserId": "12345678",
    "Category": "260c69b0",
    "Context": {
        "IP": "",
        "Province": "北京",
        "RefreshType": "open"
    },
    "PersonalRec": 1
}

响应示例

正常响应示例

{
	"BaseResp": {
		"StatusCode": 1000,
		"StatusMessage": "success"
	},
	"Data": {
		"ArticleList": [{
				"Abstract": "在阅读正文前,你必须知道一点:没有几个主力资金会笨到在利好一出炉就将股价直线拉升到涨停,所以请股民朋友们耐心一点,让利好飞一会,也许你会发现不一样的投资机会!",
				"Author": {
					"AuthorAvatarUrl": "https://p3-open.onewsimg.com/img/user-avatar/5a64bb5f28e956991275bad2c97f8a3b~300x300.image",
					"AuthorBizId": "1953162566048499",
					"AuthorId": "1719178065424519",
					"AuthorName": "旌阳财经视角",
					"Description": "财经网站主编兼券商从业,15年投资经验,带你用不一样的视角看A股!",
					"FollowerCount": 0,
					"HomePage": "https://open.toutiao.com/u1953162566048499/?utm_source=cms_test_default_content"
				},
				"CommentCount": 86,
				"CommentUrl": "https://open.toutiao.com/a7049397754094764580/comment/?utm_source=cms_test_default_content",
				"Content": "",
				"CoverImages": [{
					"Height": 572,
					"Url": "http://p9-open-sign.onewsimg.com/tos-cn-i-qvj2lq49k0/8b1f4b14fa8440ae9426b5aae369477f~tplv-obj.jpeg?scene=feed.article&x-expires=1704413000&x-signature=AHGgUrtqSADCcQLg7C%2FMD1emn1c%3D",
					"Weight": 1023,
					"Width": 1023
				}],
				"DiggCount": 1573,
				"Extra": "",
				"GenerateType": "toutiao_api",
				"GroupId": 1721064642450455,
				"GroupType": "article",
				"Link": "https://open.toutiao.com/a7049397754094764580/?utm_source=cms_test_default_content&label=wap",
				"OpenId": "7049397754094764580",
				"PublishTime": 1641332100,
				"DisplayTag": {
          "tags": "A"
         },
				"Tags": [
					"九安医疗",
					"美好,一直在身边",
					"中国移动",
					"数字货币",
					"体育",
					"金轮股份",
					"CES",
					"南风股份",
					"恒宝股份",
					"唐德影视",
					"金运激光",
					"神州信息",
					"雪人股份",
					"易华录",
					"天喻信息",
					"中国人民银行",
					"*ST川化",
					"我的第一部5G手机",
					"投资",
					"银行",
					"热点图文"
				],
				"Title": "1月5日A股猛料:五大部委联合发文!4板块将迎来重要政策面催化",
				"GoodsIds": ["test_goods_1", "test_goods_2"],
				"GoodsList": [{
						"GoodsId": "test_goods_1",
						"GoodsName": "测试商品1",
						"Keywords": "a;b",
						"Description": "测试用",
						"GoodsSourceId": "1722272335075342"
					},
					{
						"GoodsId": "test_goods_2",
						"GoodsName": "测试商品2",
						"Keywords": "a;b;c",
						"Description": "测试用",
						"GoodsSourceId": "1722272335075342"
					}
				]
			},
			{
				"Abstract": "基建板块现阶段震荡蓄能为元旦后冲刺做准备!现阶段是收集筹码的好时机,基建行情大方向明确向上,且政策面和基本面都支持,唯一不确定的利空是中国移动正式_上市前后二三天引起的波动!预计中国移动最快元旦前.上市,慢则元旦节日后一周内上市!个人意见,仅供参考!",
				"Author": {
					"AuthorAvatarUrl": "https://p3-open.onewsimg.com/img/user-avatar/5631696dc3f94b19161c24b2c432cedb~300x300.image",
					"AuthorBizId": "3913858107048077",
					"AuthorId": "1720074930427915",
					"AuthorName": "基金分析雨",
					"Description": "近我者富",
					"FollowerCount": 0,
					"HomePage": "https://open.toutiao.com/u3913858107048077/?utm_source=cms_test_default_content"
				},
				"CommentCount": 0,
				"CommentUrl": "https://open.toutiao.com/a7044899212504515086/comment/?utm_source=cms_test_default_content",
				"Content": "",
				"DiggCount": 8,
				"Extra": "",
				"GenerateType": "toutiao_api",
				"GroupId": 1720074930426939,
				"GroupType": "article",
				"Link": "https://open.toutiao.com/a7044899212504515086/?utm_source=cms_test_default_content&label=wap",
				"OpenId": "7044899212504515086",
				"PublishTime": 1640269006,
				"Tags": [
					"经济",
					"中国移动",
					"5g快乐年",
					"财经",
					"股票",
					"证券投资基金",
					"美好,一直在身边",
					"新能源",
					"行业-图文"
				],
				"Title": "基建分析(基金)",
				"GoodsIds": ["test_goods_1", "603176"],
				"GoodsList": [{
						"GoodsId": "test_goods_1",
						"GoodsName": "测试商品1",
						"Keywords": "a;b",
						"Description": "测试用",
						"GoodsSourceId": "1722272335075342"
					},
					{
						"GoodsId": "603176",
						"GoodsName": "汇通集团",
						"Keywords": "603176",
						"Description": "测试用",
						"GoodsSourceId": "1722281316786190"
					}
				],
				"TopicInfo": {
					"TopicId": "17xxxxxxxxxxx",
					"TopicSource": "cms"
					"OpenId": "",
					"TopicName": "专题测试",
					"Description": "",
					"CoverImgUrl": "",
					"ShareImgUrl": "",
					"LandingPageUrl": "",
					"ExtInfo": ""
				}
			}
		],
		"RequestId": "02164327841732700000000000000000000ffff0ae47b5995002d"
	}
}

异常响应示例

{
	"Data": null,
	"BaseResp": {
		"StatusMessage": "not find task category",
		"StatusCode": 1001
	}
}

错误代码

详见:错误代码表:volc_content_api

FAQ

  • 火山内容状态监测: 管理平台实时监测主端(头条等)内容状态变化,如内容被删除时,平台同步删除,不推荐该内容;
  • 接口下发内容数量: 内容候选量足够的情况下,一次下发12条内容;暂不支持修改配置;
  • 内容兜底下发策略: 内容被刷完或候选池内容数量不足,会触发兜底策略,与PersonalRec字段取值无关,接口随机返回内容;
  • 接口分发规则配置: 置顶规则最多配置5条内容置顶,强插规则最多配置10条内容强插,其它规则详见:新建分发任务
  • 强插规则配置失效:
    • 任何情况下,强插和置顶规则都不会失效;
    • 置顶与强插规则相互独立,强插位,从所有置顶内容的后一位算起;
    • 置顶不会失效的机制,可用于固定条数、高质内容的卡片轮播展示场景;
  • 接口返回的图片大小: 图片资源均为url;
  • 客户侧自有内容详情页搭建: 内容引入接口 提供 OpenId 内容外部主键ID,内容推荐接口 返回该字段,客户通过该id查询自有内容库,搭建内容详情页;
  • 客户侧如何嵌入火山内容的link详情页字段?
    link组成:内容正文+相关推荐+内容评论
    方式一:webview直接加载link字段的详情页url;
    方式二:若在h5中嵌入link(类似分享页),且不需要展示评论模块(可配置评论隐藏,请联系火山人员),可使用iframe方式(因评论数量是随主端动态变化的);
    技术关键点:iframe加载的整个容器是可见 / 可撑开的,避免设置display相关样式;
    在iframe onload的时机下,向合作方H5以postMessage的方式同步内容高度,这个高度供合作方设置iframe高度,此时iframe不可滚动。
    <!DOCTYPE html>
    <html>
    <head>
            <meta charset="utf-8">
            <title>测试</title>
    </head>
    <body>
    <div>
      <iframe id="articlebox"></iframe>
    </div>
    
    <script>
            var articleBoxIframe = document.getElementById('articlebox');
            // 合作方H5 接收信息
            window.addEventListener('message', (e) => {
              try {
                // data json字符串:{ contentHeight: 300}
                var data = JSON.parse(e.data || '{}') || {};
                console.log('测试'+JSON.stringify(data))
                var contentHeight = data.contentHeight;
                articleBoxIframe.style.height = contentHeight + 'px'
                console.log('文章高度: ' + contentHeight)
              } catch(err) {
                  console.log(err)
              }
            })
    
            articleBoxIframe.src = 'https://open.toutiao.com/xxxxx'
    </script>
    </body>
    </html>
    

注意

若需排查日志,请提供 RequestId