API 文档

TikTok 评论 API

异步获取视频评论与回复,支持按页和全部采集。

测试 API

按页或自动翻页获取视频评论,可以包含所选主评论的全部可获取回复。

测试 TikTok 评论 API →

生成异步任务

POST https://api.goanyapi.com/api/v1/tiktok-comments/tasks

使用 Authorization: Bearer YOUR_API_KEY 鉴权,请求体为 JSON。HTTP 202 表示任务已受理,不表示评论已采集完成。保存返回的 data.task_id,然后使用下方查询接口获取进度和结果。

输入参数

参数类型位置必填约束与默认值说明
AuthorizationstringHeader是Bearer YOUR_API_KEY当前账户的 API Key。
Content-TypestringHeader建议application/json发送 JSON 请求体时使用。
video_urlstringJSON body是—完整 HTTPS TikTok 视频地址;允许分享参数、页面片段和末尾斜杠,采集前自动去除。不支持短链接。
modestringJSON body否page / all; 默认: pagepage 获取一页主评论;all 自动翻页获取全部可获取主评论。
cursorstringJSON body否pattern: ^[0-9]+$采集主评论的数字字符串游标;仅 page 模式允许。省略从第一页开始,后续使用 collection.next_cursor。
include_repliesbooleanJSON 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/7686957509826923808

mode 为 page(默认)或 all。cursor 是可选数字字符串,仅 page 模式允许,默认从第一页开始,下一页使用 collection.next_cursor。include_replies 为布尔值,默认 false。主评论与回复均固定每批 40 条,不接受公开 count 参数。按页模式获取一页主评论,勾选回复后继续获取这些主评论的全部可获取回复;全部模式自动翻页,不要求填写数量上限。

提交返回 HTTP 202、data.task_id 与 data.status=queued。提交本身不扣费,但余额须足以支付第一档。每次提交为独立任务。

输出参数

以下字段均位于响应正文中。生成任务返回任务元数据,计数和已扣积分初始为 0,items 初始为空;不要将受理响应当作最终采集结果。

字段类型说明
codestring请求成功为 ok;任务状态见 data.status。
messagestring请求成功时为 ok。
data.task_idstring任务 ID,格式为 ttc_ 加 32 位十六进制字符。
data.statusstringqueued:任务已受理,不代表采集完成。
data.created_atstring (ISO 8601)UTC 创建时间。
data.expires_atstring (ISO 8601)UTC 保留截止时间,提交后 30 天。
data.counts.commentsinteger生成任务时为 0。
data.counts.repliesinteger生成任务时为 0。
data.counts.totalinteger生成任务时为 0。
data.billing.credits_usednumber截至当前已扣积分;生成任务时为 0。
data.billing.records_per_unitinteger每个计费档位的记录数,主评论与回复合并计数。
data.billing.credits_per_unitnumber任务创建时锁定的每档积分费率,后续费率调整不影响已有任务。
data.collection.completeboolean所选采集范围是否完成,succeeded 时为 true。
data.collection.has_moreboolean主评论采集分页是否还有下一页;不表示已保存结果分页。
data.collection.next_cursorstring | nullpage 模式下一页主评论游标;all 模式或无下一页时为 null。
data.collection.stop_reasonstring | null正常执行为 null;停止原因可为 insufficient_credits 或 collection_failed。
data.itemsarray生成任务时为空数组 [];结果通过查询接口获取。
data.results.has_moreboolean已保存结果是否还有下一批;仅为结果分页标志,不表示任务已经完成。
data.results.next_cursorstring | 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 查询参数中。

输入参数

参数类型位置必填约束与默认值说明
AuthorizationstringHeader是Bearer YOUR_API_KEY当前账户的 API Key。
task_idstringPath是pattern: ^ttc_[a-f0-9]{32}$生成任务返回的任务 ID,必须属于当前账户。
result_cursorstringQuery否pattern: ^[0-9]+$读取已保存结果的数字字符串偏移;使用 results.next_cursor,省略从第一批读取。与采集游标 cursor 不同。
limitintegerQuery否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 是整个任务已保存的总数,两者可以不同。

字段类型说明
codestring请求成功为 ok;任务状态见 data.status。
messagestring请求成功时为 ok。
data.task_idstring任务 ID,格式为 ttc_ 加 32 位十六进制字符。
data.statusstringqueued / running / succeeded / partial / failed,见任务状态说明。
data.created_atstring (ISO 8601)UTC 创建时间。
data.expires_atstring (ISO 8601)UTC 保留截止时间,提交后 30 天。
data.counts.commentsinteger已保存的去重主评论数。
data.counts.repliesinteger已保存的去重回复数。
data.counts.totalinteger已保存的总记录数,即主评论加回复。
data.billing.credits_usednumber截至当前已扣积分;生成任务时为 0。
data.billing.records_per_unitinteger每个计费档位的记录数,主评论与回复合并计数。
data.billing.credits_per_unitnumber任务创建时锁定的每档积分费率,后续费率调整不影响已有任务。
data.collection.completeboolean所选采集范围是否完成,succeeded 时为 true。
data.collection.has_moreboolean主评论采集分页是否还有下一页;不表示已保存结果分页。
data.collection.next_cursorstring | nullpage 模式下一页主评论游标;all 模式或无下一页时为 null。
data.collection.stop_reasonstring | null正常执行为 null;停止原因可为 insufficient_credits 或 collection_failed。
data.itemsarray当前结果分页的已保存评论记录,尚无结果时为 []。
data.results.has_moreboolean已保存结果是否还有下一批;仅为结果分页标志,不表示任务已经完成。
data.results.next_cursorstring | null下一次查询的 result_cursor;没有更多已保存记录时为 null。

评论记录字段

除 id、type、parent_comment_id 外,业务字段可能缺失、为 null 或为空,按实际返回保留;下表类型为通常的数据形式。

字段类型说明
data.items[].idstring评论或回复 ID。
data.items[].typestringcomment 表示主评论;reply 表示回复。
data.items[].parent_comment_idstring | null回复所属的主评论 ID;主评论为 null。
data.items[].userAvatarstring | null用户头像 URL。
data.items[].userNamestring | null用户名。
data.items[].contentstring | null评论正文。
data.items[].createTimenumber | null评论创建时间,通常为 Unix 秒时间戳。
data.items[].likeCountnumber | null点赞数。
data.items[].replyCountnumber | 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}/resume
POST /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 天,到期不再允许续跑。可获取数量不保证等于视频页面显示的评论总数。