TikTok 评论 API
异步获取视频评论与回复,支持按页和全部采集。
按页或自动翻页获取视频评论,可以包含所选主评论的全部可获取回复。
测试 TikTok 评论 API →生成异步任务
POST https://api.goanyapi.com/api/v1/tiktok-comments/tasks使用 Authorization: Bearer YOUR_API_KEY 鉴权,请求体为 JSON。HTTP 202 表示任务已受理,不表示评论已采集完成。保存返回的 data.task_id,然后使用下方查询接口获取进度和结果。
输入参数
| 参数 | 类型 | 位置 | 必填 | 约束与默认值 | 说明 |
|---|---|---|---|---|---|
Authorization | string | Header | 是 | Bearer YOUR_API_KEY | 当前账户的 API Key。 |
Content-Type | string | Header | 建议 | application/json | 发送 JSON 请求体时使用。 |
video_url | string | JSON body | 是 | — | 完整 HTTPS TikTok 视频地址;允许分享参数、页面片段和末尾斜杠,采集前自动去除。不支持短链接。 |
mode | string | JSON body | 否 | page / all; 默认: page | page 获取一页主评论;all 自动翻页获取全部可获取主评论。 |
cursor | string | JSON body | 否 | pattern: ^[0-9]+$ | 采集主评论的数字字符串游标;仅 page 模式允许。省略从第一页开始,后续使用 collection.next_cursor。 |
include_replies | boolean | JSON body | 否 | 默认: false | 是否采集所选主评论的全部可获取回复;主评论和回复合并计费。 |
请求示例
POST /api/v1/tiktok-comments/tasks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json{"video_url":"https://www.tiktok.com/@user/video/7702491752548027656","mode":"page","cursor":"0","include_replies":true}video_url 必填,使用完整 HTTPS 视频地址,暂不支持短链接。允许携带分享查询参数(例如 ?is_from_webapp=1&sender_device=pc)、页面片段和末尾斜杠,采集前自动去除。以下两个地址定位同一个视频:
https://www.tiktok.com/@spidey.glow/video/7686957509826923808?is_from_webapp=1&sender_device=pc
https://www.tiktok.com/@spidey.glow/video/7686957509826923808mode 为 page(默认)或 all。cursor 是可选数字字符串,仅 page 模式允许,默认从第一页开始,下一页使用 collection.next_cursor。include_replies 为布尔值,默认 false。主评论与回复均固定每批 40 条,不接受公开 count 参数。按页模式获取一页主评论,勾选回复后继续获取这些主评论的全部可获取回复;全部模式自动翻页,不要求填写数量上限。
提交返回 HTTP 202、data.task_id 与 data.status=queued。提交本身不扣费,但余额须足以支付第一档。每次提交为独立任务。
输出参数
以下字段均位于响应正文中。生成任务返回任务元数据,计数和已扣积分初始为 0,items 初始为空;不要将受理响应当作最终采集结果。
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 请求成功为 ok;任务状态见 data.status。 |
message | string | 请求成功时为 ok。 |
data.task_id | string | 任务 ID,格式为 ttc_ 加 32 位十六进制字符。 |
data.status | string | queued:任务已受理,不代表采集完成。 |
data.created_at | string (ISO 8601) | UTC 创建时间。 |
data.expires_at | string (ISO 8601) | UTC 保留截止时间,提交后 30 天。 |
data.counts.comments | integer | 生成任务时为 0。 |
data.counts.replies | integer | 生成任务时为 0。 |
data.counts.total | integer | 生成任务时为 0。 |
data.billing.credits_used | number | 截至当前已扣积分;生成任务时为 0。 |
data.billing.records_per_unit | integer | 每个计费档位的记录数,主评论与回复合并计数。 |
data.billing.credits_per_unit | number | 任务创建时锁定的每档积分费率,后续费率调整不影响已有任务。 |
data.collection.complete | boolean | 所选采集范围是否完成,succeeded 时为 true。 |
data.collection.has_more | boolean | 主评论采集分页是否还有下一页;不表示已保存结果分页。 |
data.collection.next_cursor | string | null | page 模式下一页主评论游标;all 模式或无下一页时为 null。 |
data.collection.stop_reason | string | null | 正常执行为 null;停止原因可为 insufficient_credits 或 collection_failed。 |
data.items | array | 生成任务时为空数组 [];结果通过查询接口获取。 |
data.results.has_more | boolean | 已保存结果是否还有下一批;仅为结果分页标志,不表示任务已经完成。 |
data.results.next_cursor | string | null | 下一次查询的 result_cursor;没有更多已保存记录时为 null。 |
响应示例(HTTP 202)
以下为结构示例,不代表真实任务;为便于阅读,省略了 created_at、expires_at、billing.records_per_unit 和 billing.credits_per_unit,实际响应仍包含这些字段。具体费率以任务返回的 billing.credits_per_unit 为准。
{ "code": "ok", "message": "ok", "data": { "task_id": "ttc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "queued", "counts": { "comments": 0, "replies": 0, "total": 0 }, "billing": { "credits_used": 0 }, "collection": { "complete": false, "has_more": true, "next_cursor": null, "stop_reason": null }, "items": [], "results": { "has_more": false, "next_cursor": null } }}查询状态与已保存结果
Catalog 标识:tiktok-comments-task;MCP 工具:goanyapi_tiktok_comments_task。
GET https://api.goanyapi.com/api/v1/tiktok-comments/tasks/{task_id}同样使用 Authorization: Bearer YOUR_API_KEY 鉴权。无请求体,任务 ID 放在路径中,结果分页参数放在 URL 查询参数中。
输入参数
| 参数 | 类型 | 位置 | 必填 | 约束与默认值 | 说明 |
|---|---|---|---|---|---|
Authorization | string | Header | 是 | Bearer YOUR_API_KEY | 当前账户的 API Key。 |
task_id | string | Path | 是 | pattern: ^ttc_[a-f0-9]{32}$ | 生成任务返回的任务 ID,必须属于当前账户。 |
result_cursor | string | Query | 否 | pattern: ^[0-9]+$ | 读取已保存结果的数字字符串偏移;使用 results.next_cursor,省略从第一批读取。与采集游标 cursor 不同。 |
limit | integer | Query | 否 | 1–100; 默认: 100 | 单次查询返回的最大记录数,不影响采集数量或扣费。 |
请求示例
GET /api/v1/tiktok-comments/tasks/{task_id}?limit=100
Authorization: Bearer YOUR_API_KEY每 5 秒轮询。limit 为 1~100 的整数,默认 100;result_cursor 使用 results.next_cursor 返回的数字字符串。结果分页与采集分页独立。查询、重复读取和下载免费。
采集以有时间预算的后台批次执行。queued 或 running 时请继续轮询,以唤醒后续批次;没有后续查询时,长任务可能保持待处理。关闭页面不会删除已保存结果,之后查询相同任务 ID 可继续推进。
状态为 queued、running、succeeded、partial、failed。部分完成时返回 collection.stop_reason,值为 insufficient_credits 或 collection_failed,已付费结果保留。counts.comments/replies/total 是已保存去重数量,billing.credits_used 是已扣积分。collection.complete 表示所选采集范围是否完成。记录包含实际公开评论字段、type=comment|reply 和 parent_comment_id;保留 null、空字符串和字段缺失,ID 与游标均为字符串。
输出参数
HTTP 200 表示本次查询成功;任务是否完成由 data.status 和 data.collection.complete 判断。items 只包含当前结果页,counts.total 是整个任务已保存的总数,两者可以不同。
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 请求成功为 ok;任务状态见 data.status。 |
message | string | 请求成功时为 ok。 |
data.task_id | string | 任务 ID,格式为 ttc_ 加 32 位十六进制字符。 |
data.status | string | queued / running / succeeded / partial / failed,见任务状态说明。 |
data.created_at | string (ISO 8601) | UTC 创建时间。 |
data.expires_at | string (ISO 8601) | UTC 保留截止时间,提交后 30 天。 |
data.counts.comments | integer | 已保存的去重主评论数。 |
data.counts.replies | integer | 已保存的去重回复数。 |
data.counts.total | integer | 已保存的总记录数,即主评论加回复。 |
data.billing.credits_used | number | 截至当前已扣积分;生成任务时为 0。 |
data.billing.records_per_unit | integer | 每个计费档位的记录数,主评论与回复合并计数。 |
data.billing.credits_per_unit | number | 任务创建时锁定的每档积分费率,后续费率调整不影响已有任务。 |
data.collection.complete | boolean | 所选采集范围是否完成,succeeded 时为 true。 |
data.collection.has_more | boolean | 主评论采集分页是否还有下一页;不表示已保存结果分页。 |
data.collection.next_cursor | string | null | page 模式下一页主评论游标;all 模式或无下一页时为 null。 |
data.collection.stop_reason | string | null | 正常执行为 null;停止原因可为 insufficient_credits 或 collection_failed。 |
data.items | array | 当前结果分页的已保存评论记录,尚无结果时为 []。 |
data.results.has_more | boolean | 已保存结果是否还有下一批;仅为结果分页标志,不表示任务已经完成。 |
data.results.next_cursor | string | null | 下一次查询的 result_cursor;没有更多已保存记录时为 null。 |
评论记录字段
除 id、type、parent_comment_id 外,业务字段可能缺失、为 null 或为空,按实际返回保留;下表类型为通常的数据形式。
| 字段 | 类型 | 说明 |
|---|---|---|
data.items[].id | string | 评论或回复 ID。 |
data.items[].type | string | comment 表示主评论;reply 表示回复。 |
data.items[].parent_comment_id | string | null | 回复所属的主评论 ID;主评论为 null。 |
data.items[].userAvatar | string | null | 用户头像 URL。 |
data.items[].userName | string | null | 用户名。 |
data.items[].content | string | null | 评论正文。 |
data.items[].createTime | number | null | 评论创建时间,通常为 Unix 秒时间戳。 |
data.items[].likeCount | number | null | 点赞数。 |
data.items[].replyCount | number | null | 该记录返回的回复数量,不等于当前结果页已包含的回复条数。 |
响应示例(HTTP 200)
以下为一条主评论的结构示例,不代表真实任务;省略了 created_at、expires_at 和 billing。完整字段以上表为准,计费信息由真实任务返回。
{ "code": "ok", "message": "ok", "data": { "task_id": "ttc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "succeeded", "counts": { "comments": 1, "replies": 0, "total": 1 }, "collection": { "complete": true, "has_more": false, "next_cursor": null, "stop_reason": null }, "items": [ { "id": "7702501823814419213", "type": "comment", "parent_comment_id": null, "userName": "ilikemusicabit", "content": "What if I want them to watch", "createTime": 1793378501, "likeCount": 340012, "replyCount": 709 } ], "results": { "has_more": false, "next_cursor": null } }}任务状态与两个游标
| 状态 | 含义 | 后续操作 |
|---|---|---|
queued | 等待执行 | 每 5 秒继续查询 |
running | 正在采集,可能已有部分结果 | 每 5 秒继续查询 |
succeeded | 所选范围采集完成 | 停止轮询;按结果游标读取剩余已保存记录 |
partial | 部分完成,已保存结果保留 | 停止轮询,查看停止原因;需要时继续原任务 |
failed | 本次采集执行失败 | 停止轮询,查看停止原因;需要时重试继续原任务 |
collection.next_cursor 用于按页模式生成另一页采集任务;results.next_cursor 用于查询同一任务的下一批已保存结果,不应混用。results.has_more=false 不等于任务已完成:queued 或 running 时后续仍可能保存更多记录。
继续任务
Catalog 标识:tiktok-comments-resume;MCP 工具:goanyapi_tiktok_comments_resume。
POST https://api.goanyapi.com/api/v1/tiktok-comments/tasks/{task_id}/resumePOST /api/v1/tiktok-comments/tasks/{task_id}/resume
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{}继续未过期的 partial 或 failed 任务,沿用原计数和费率,已保存记录不重复收费。继续操作本身免费。过期返回 410,其他用户的任务返回 404。
路径参数 task_id 与查询接口相同,请求体为 {},返回 HTTP 202。输出字段与生成任务相同,但保留原任务 ID、已有计数、已扣积分和结果,状态重新排队;此后继续使用查询接口。
HTTP 错误
400:JSON、视频地址、模式、游标、分页或任务 ID 不合法;401:未提供有效 API Key;402:余额不足以生成任务;404:任务不存在或不属于当前账户;409:当前任务不可继续;410:任务已过期;429:请求过于频繁。运行中的余额不足或采集失败通过查询响应的任务状态与 collection.stop_reason 表达,已保存结果保留。
500 表示服务内部错误。错误正文包含 code(字符串错误码)、message(字符串说明),可选 details(附加信息),不包含成功结果的 data。
{
"code": "invalid_params",
"message": "Provide valid TikTok comment parameters"
}上例对应生成任务参数不合法时的 HTTP 400。查询请求返回 HTTP 200 时,即使任务为 partial 或 failed,也应读取 data.collection.stop_reason,不能仅凭 HTTP 状态判断采集成功。
计费与保留期限
1 积分 / 100 条记录(向上取整)
主评论与回复合并计数,每百条向上取整,保存过程中逐档扣除。保存结果与扣费原子提交,零结果免费,任务内部重试和重复记录不重复计费。余额不足停止采集并保留已有结果;部分失败仅按已保存可交付数量计费。结果保留到 expires_at,即提交后 30 天,到期不再允许续跑。可获取数量不保证等于视频页面显示的评论总数。