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

获取个性化内容

最近更新时间2023.12.06 13:56:31

首次发布时间2021.04.09 18:31:35

客户侧调用该接口获取个性化推荐的内容,目前支持的内容体裁有图文、横版短视频、竖版小视频。
每次请求,火山引擎侧默认返回的内容条数在6-15条不等,内容信息包括内容标题、封面图,作者名称、阅读数、播放量、发布时间、点赞数、分享数等,客户侧可使用这些数据,自定义实现UI效果。

请求结构说明
请求域名stream-api.feedcoopapi.com
请求地址/content/stream
请求协议HTTP/HTTPS
请求方式GET/POST
参数类型application/x-www-form-urlencoded

注意

  • 个性化推荐接口耗时正常情况不超过1s,为容忍网络抖动或突发流量,超时时间建议设置为3s。
  • 尽量不要预加载,否则会造成内容浪费,影响推荐效果。如果您为了提升客户端体验流畅度进行了预加载,建议您将内容放到首页进行展现,可以更好的保障推荐效果。
  • 同一个用户需要对应唯一的用户标识,也就是在调用wap注册接口时,该用户的uuid需要保持不变。否则将会被火山引擎侧推荐系统识别为新用户,进而影响推荐效果。涉及更改用户标识,请提前与火山引擎侧沟通,以免造成指标骤降。

请求参数

参数描述类型是否必填说明
api_version接口版本int固定传4
category频道IDString登陆火山引擎内容定制控制台,创建应用-场景-频道后,生成的频道ID就是这里的category。创建频道步骤请参见:信息流运营操作手册
dt设备型号String如iphone5s、Galaxy。建议上传,主要用于推荐分析,提升推荐效果
device_brand设备厂商String如Apple、Samsung。建议上传,主要用于推荐分析,提升推荐效果
os操作系统String如 Android、IOS。主要用于推荐分析,提升推荐效果。注意:IOS系统如果没有正确传入此参数,返回的封面图可能为webp格式,导致图片解析失败。
os_version操作系统版本String如4.0.4。建议上传,主要用于推荐分析,提升推荐效果。火山引擎侧内容详情页会根据此参数进行适配。
client_version应用的版本号String比如1.0.1。主要用于数据排查,提升业务指标

allow_stick

是否输出置顶文章

int

1:是,0:否,默认是0。
您需要结合自身场景控制该参数的传递,比如C端非首刷或者下拉刷新不需要置顶时,控制不传此参数即可。

注意

当同时满足如下几个条件,才会返回置顶内容:
1.在火山引擎内容定制控制台添加并发布了置顶内容;
2.allow_stick值为1;
3.传入的category和火山引擎内容定制控制台的频道ID正确匹配。

stress_test

是否为压测

int

1:是,0:否,默认为0。
当您需要进行压力测试时,必须填入此参数,否则会因命中火山引擎侧的限流机制,而被拦截

off_personal_rec

是否关闭个性化推荐

int

1:是,随机推荐内容,
0:否,个性化推荐内容,
默认为0

ip设备ipString

city

城市名称

String

比如:北京,编码为utf-8。
当请求“本地”频道时,必须填入此参数,否则无法返回本地内容。目前本地频道支持的城市见下文说明。

custom_video_definition指定视频分辨率String枚举值:360p、480p、540p、720p、1080p、all(全部)。
横版短视频支持:360p(默认)、480p、540p、720p、1080p
竖版小视频支持:540p(默认)
默认不传时,短视频下发360p,小视频下发540p,传all时下发视频所有的分辨率。
如果请求的分辨率对于该视频不存在,则会自动降级一档返回内容作为兜底。
特别注意: 分辨率的升档会增加cdn的播放成本,需客户侧谨慎评估,详细咨询火山引擎侧。
allow_force_insert请求强插内容(取值0代表关闭,1代表开启)int频道首刷时传递为1,非首刷场景为0

响应参数

参数
描述
类型
说明
ret
响应结果
long
参见“错误码”说明
msg
本次请求是否成功
String
success:成功
req_id
本次请求标识
String
火山引擎侧使用该字段进行具体问题追踪和排查
data
内容数据
List
默认随机返回6-15条内容数据
extra
附加信息
JSONObject

请求示例

POST /content/stream?access_token=xxx&timestamp=1695624033&signature=xxx&nonce=123&partner=xxx HTTP/1.1
Host: stream-api.feedcoopapi.com
Content-Type: application/x-www-form-urlencoded

category=xxx&os=IOS&client_version=1.0.1&api_version=4

响应示例

{
    "ret": 0,
    "msg": "success",
    "message": "success",
    "data": [
        {
            "abstract": "简介:\n这是一期《传记系列》也是一期《艺术系列》我们来聊聊梵高。",
            "article_type": "短视频",
            "article_url": "https://open.toutiao.com/a7280005848263459386/?...",
            "comment_count": 231,
            "comment_url": "...",
            "cover_images": [
                {
                    "url": "https://p9-open-sign.byteimg.com/tos-cn-i-0004/oUpeHAAwKABxfr1eET5HAhP4ADAjXiAAhQ22E3~tplv-tt-cut:960:540.jpeg?scene=content&x-expires=1727162300&x-signature=1C7mSW3ckFKyjQ8UX4FiiFOoojI%3D",
                    "height": 540,
                    "width": 960
                }
            ],
            "cover_mode": 1,
            "digg_count": 2787,
            "group_id": "7280005848263459386",
            "has_video": true,
            "publish_time": 1695008447,
            "share_count": 388,
            "share_url": "https://open.toutiao.com/a7280005848263459386/?...",
            "title": "一个疯子割掉了自己的耳朵,但他死后,变成了被全世界追捧的天才",
            "user_info": {
                "avatar_url": "https://p3-open-sign.onewsimg.com/user-avatar/c2083b5831764d958d54dba75d619394~tplv-obj.jpeg?scene=core&x-expires=1758698219&x-signature=SncczxahXH5DGhGf9lHRndXXa6E%3D",
                "description": "每周一更新,抖音/西瓜更有完整视频内容。",
                "follow": false,
                "follower_count": 4896215,
                "home_page": "https://open.toutiao.com/u4770026843/?...",
                "name": "xxx",
                "user_id": 4770026843,
                "user_verified": false,
                "verified_content": ""
            },
            "video_watch_count": 203002,
            "video_detail": {
                "video_duration": 2359.936,
                "video_list": [
                    {
                        "url": "http://mercury.snssdk.com/video/url/?...",
                        "height": 720,
                        "width": 1280,
                        "definition": "720p"
                    }
                ]
            },
            "article_classification": [
                [
                    "人文社科",
                    "艺术"
                ],
                [
                    "科学科技",
                    "科学"
                ]
            ],
            "is_stick": false,
            "filter_words": [
                {
                    "id": "8:0",
                    "name": "看过了"
                },
                {
                    "id": "9:1",
                    "name": "内容太水"
                },
                {
                    "id": "6:85562",
                    "name": "不想看:疯子"
                }
            ],
            "data_source": "Stream3"
        },...
    ],
    "req_id": "20230925151820BE40E84E79DA990B6B59",
    "has_more": true
}

示例效果图

图文视频

本地频道-城市列表

当请求“本地”频道时,需要同时传入city,目前支持的城市如下

序号城市名
A安阳, 鞍山, 安庆, 安康, 阿坝, 阿拉善, 阿克苏, 阿勒泰, 阿里, 安顺, 澳门
B北京, 蚌埠, 保定, 本溪, 包头, 亳州, 滨州, 白城, 百色, 白山, 白银, 宝鸡, 保山, 巴彦淖尔, 巴中, 北海, 毕节, 博尔塔拉, 巴音郭楞
C重庆, 成都, 长春, 长沙, 承德, 常州, 滁州, 巢湖, 沧州, 常德, 昌都, 昌吉, 长治, 朝阳, 潮州, 郴州, 楚雄, 赤峰, 池州, 崇左
D大连, 东莞, 德州, 丹东, 大理, 大庆, 大同, 大兴安岭, 达州, 德宏, 德阳, 定西, 迪庆, 东营
E鄂州, 鄂尔多斯, 恩施
F福州, 阜阳, 佛山, 抚州, 防城港, 抚顺, 阜新
G广州, 贵阳, 桂林, 赣州, 广元, 甘南, 甘孜, 广安, 贵港, 果洛, 固原
H杭州, 合肥, 哈尔滨, 海口, 衡阳, 邯郸, 呼和浩特, 黄冈, 黄石, 湖州, 衡水, 呼伦贝尔, 黄山, 海北, 海东, 海南, 海西, 哈密, 汉中, 鹤壁, 河池,鹤岗, 黑河, 和田, 河源, 菏泽, 贺州, 红河, 淮安, 淮北, 怀化, 淮南, 黄南, 惠州, 葫芦岛
J吉林, 济南, 九江, 揭阳, 酒泉, 嘉兴, 荆州, 锦州, 佳木斯, 吉安, 江门, 焦作, 嘉峪关, 金昌, 晋城, 景德镇, 荆门, 金华, 济宁, 晋中,鸡西, 济源
K昆明, 开封, 喀什, 克拉玛依, 克孜勒苏
L兰州, 廊坊, 六安, 乐山, 来宾, 柳州, 聊城, 莱芜, 拉萨, 洛阳, 凉山, 连云港, 辽阳, 辽源, 丽江, 临沧, 临汾, 临夏, 临沂, 林芝, 丽水,六盘水, 陇南, 龙岩, 娄底, 漯河, 泸州, 吕梁
M绵阳, 马鞍山, 茂名, 眉山, 梅州, 牡丹江
N南京, 南昌, 南宁, 宁波, 南通, 南充, 南平, 南阳, 那曲, 内江, 怒江, 宁德
P莆田, 濮阳, 盘锦, 攀枝花, 平顶山, 平凉, 萍乡, 普洱
Q青岛, 秦皇岛, 泉州, 衢州, 曲靖, 黔东南, 黔南, 黔西南, 庆阳, 清远, 钦州, 齐齐哈尔, 七台河
R日照, 日喀则
S上海, 深圳, 沈阳, 石家庄, 三门峡, 三明, 三亚, 商洛, 商丘, 苏州, 汕头, 汕尾, 十堰, 遂宁, 上饶, 山南, 绍兴, 邵阳, 双鸭山, 朔州, 四平, 松原, 绥化, 随州, 宿迁, 宿州, 石嘴山, 韶关
T天津, 太原, 唐山, 台州, 塔城, 泰安, 铁岭, 台湾, 泰州, 天水, 铜川, 通化, 通辽, 铜陵, 铜仁, 吐鲁番
W武汉, 温州, 无锡, 乌鲁木齐, 芜湖, 潍坊, 威海, 渭南, 文山, 乌海, 乌兰察布, 武威, 吴忠, 梧州
X西安, 厦门, 湘潭, 徐州, 许昌, 信阳, 西宁, 咸阳, 宣城, 新乡, 湘西, 襄阳, 咸宁, 孝感, 锡林郭勒, 兴安, 邢台, 新余, 忻州, 西双版纳, 香港
Y扬州, 银川, 宜昌, 岳阳, 榆林, 烟台, 雅安, 延安, 延边, 盐城, 阳江, 阳泉, 宜宾, 伊春, 宜春, 伊犁, 营口, 鹰潭, 益阳, 永州, 玉林, 运城, 云浮, 玉树, 玉溪
Z珠海, 肇庆, 张家口, 中山, 淄博, 驻马店, 枣庄, 张家界, 张掖, 漳州, 湛江, 昭通, 郑州, 镇江, 中卫, 周口, 舟山, 株洲, 自贡, 资阳, 遵义