话题下作品 API
用话题 ID 或话题页链接按页拉取话题下作品,可按综合、最多点赞或最新排序;每条返回作品 ID、文案、作者、时长和链接。
按话题拉取作品列表。必填 topic_id(话题 ID 或话题页链接),可用 sort_type 选择综合、最多点赞或最新,用 cursor 翻页。每页约 10 条。
每条含作品 ID、文案、链接、封面、作者、时长和发布时间。作品 ID 可继续查详情或互动数。
请求地址 POST https://www.xmedi.cn/api/v1/douyin/topics/videos。调用成功才扣费,参数错误、平台侧失败或超时不扣费。
成功响应的 meta 含数据血缘,说明见 鉴权与计费。
适用场景
- 活动追踪:按最新排序持续翻页,收录品牌话题下的新作品。
- 达人筛选:按最多点赞看头部作品,再查作者主页。
- 素材库:把作品 ID 和链接入库,供详情和评论接口继续调用。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cursor |
string | 否 | 翻页游标,取上一页 next_cursor;首页留空。 |
page |
integer | 否 | 页码,从 1 起;默认 1;最小 1 |
page_size |
integer | 否 | 每页条数;默认 20;范围 1~100 |
sort_type |
integer | 否 | 排序:0 综合(默认)、1 最多点赞、2 最新发布。 |
topic_id |
string | 是 | 必填。话题 ID,或网页版话题页链接。 |
返回 data 字段
| 字段 | 类型 | 说明 |
|---|---|---|
has_more | boolean | 是否还有下一页。为 true 时带上 next_cursor 继续请求。 |
items | array<object> | 作品列表。每条含 id、title、url、thumbnail、author.name、duration_sec、publish_time。无文案时 title 为空串。 |
page | number | |
page_size | number | |
total | number | 平台不提供话题作品总数,恒为 0。是否翻页看 has_more。 |
调用示例
curl -X POST https://www.xmedi.cn/api/v1/douyin/topics/videos \
-H "X-XMEDI-Key: xm_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"page":1,"topic_id":"1575791821492238"}'
返回示例
以下为 data 的字段结构示意,实际取值以调用结果为准。
{
"has_more": false,
"items": [
{
"author": {
"name": "示例用户"
},
"duration_sec": 15,
"id": "7000000000000000001",
"publish_time": "2026-01-01T00:00:00Z",
"thumbnail": "https://example.com/cover.jpg",
"title": "示例作品文案",
"url": "https://www.douyin.com/video/7000000000000000001"
}
],
"next_cursor": "",
"page": 1,
"page_size": 10,
"total": 0
}
注意事项
- 每页约 10 条。翻页只回传 next_cursor,不要自己递增页码代替游标。
- 某一排序下本页为空时,可改用其他 sort_type 或稍后重试。空列表仍算一次成功调用时才会扣费;无数据的失败返回不扣费。
常见错误码
| code | error_code | 含义与处理 |
|---|---|---|
| 40001 | VALIDATION_ERROR | 参数校验失败,按返回提示修改请求,不扣费 |
| 40100 | UNAUTHORIZED | API Key 缺失、错误或已吊销,到控制台检查 Key |
| 40200 | INSUFFICIENT_BALANCE | 余额不足,充值后重试 |
| 42900 | RATE_LIMITED | 超过每分钟 60 次上限,稍后重试 |
| 50000 | INTERNAL_ERROR | 服务异常,可稍后重试,不扣费 |
| 50300 | NOT_AVAILABLE | 接口暂不可用,不扣费 |
常见问题
- total 为什么是 0?
- 话题作品接口不提供总数。还有没有下一页看 has_more。总播放和参与人数在话题详情里。
- 短链能当 topic_id 吗?
- 不能。请传话题 ID,或网页版 /hashtag/ 链接。分享短链先解析成作品,不是话题。
- 作品 ID 下一步怎么用?
- items[].id 可传给作品详情或作品互动数。
相关接口
需要接入这个接口?
免费注册
注册后创建 API Key,或留下联系方式获取方案