--- title: "Posts" description: "列出 TikTok 视频：某创作者的、某话题标签下的、某音乐的、某播放列表的，或探索信息流。" --- ```http GET | POST /v1/tiktok/posts ``` 参数可以用 `GET` 的查询字符串发送，也可以用 `POST` 的 JSON 请求体发送，两者等价。 ## 传入内容 | 传入 | 读取内容 | 说明 | |---|---|---| | `username` 或 `userId` | 某创作者的视频 | `type`：`posts`（默认）、`reposts`、`likes`（公开时） | | `hashtag` | 某话题标签下的视频 | 名称，或其数字 id（可省去一次查询） | | `sound` | 使用某音乐的视频 | | | `playlist` | 某播放列表中的视频 | | | 不传 | 探索信息流 | `category`（默认 120） | 每次调用只传一个来源。所有标识符也都接受页面 URL。 ## 参数 | Parameter | Type | Required | Notes | |---|---|---|---| | `category` | string | | Default feed only: explore category id (default 120). | | `cursor` | string | | Opaque cursor from the previous page's `cursor`. Pass it alone for the next page. | | `hashtag` | string | | Videos under a hashtag: its name, or its numeric id (saves the lookup). A hashtag that is itself a number takes its # (#2024). | | `limit` | integer 1–30 | | Items per page, 1–30. | | `playlist` | string | | Videos in a playlist: id or URL (…/playlist/-). | | `sound` | string | | Videos using a sound: sound id or URL (…/music/-). | | `type` | enum | | username/userId: the creator's posts (default), reposts or likes. `posts` `reposts` `likes` | | `userId` | string | | Creator secUid. Pass it instead of a username to save the lookup (1 unit instead of 2). | | `username` | string | | Creator @handle (with or without @), or the profile URL. | ## 请求 ```bash tab="cURL" curl "https://gateway.apinoa.com/v1/tiktok/posts?username=tiktok&limit=3" \ -H "x-api-key: $APINOA_API_KEY" ``` ```js tab="JavaScript" const params = new URLSearchParams({ username: "tiktok", limit: "3" }); const res = await fetch(`https://gateway.apinoa.com/v1/tiktok/posts?${params}`, { headers: { "x-api-key": process.env.APINOA_API_KEY }, }); const { success, data, error } = await res.json(); ``` ```python tab="Python" import os import requests res = requests.get( "https://gateway.apinoa.com/v1/tiktok/posts", params={"username": "tiktok", "limit": "3"}, headers={"x-api-key": os.environ["APINOA_API_KEY"]}, ) body = res.json() ``` ## 响应 在 `data` 中返回 [`Post`](/docs/api-reference/sns/response-schema#post) [`Page`](/docs/api-reference/sns/response-schema#page)。 真实响应的节选：数组只保留前几项，长文本已截断。 ```json { "success": true, "data": { "platform": "tiktok", "items": [ { "platform": "tiktok", "id": "7700009319382650142", "url": "https://www.tiktok.com/@tiktok/video/770000931938…", "author": { "platform": "tiktok", "id": "107955", "handle": "tiktok", "displayName": "TikTok", "url": "https://www.tiktok.com/@tiktok", "avatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-usea…", "verified": true, "counts": { "followers": 96400000, "following": 1, "posts": 1512 }, "ext": { "secUid": "MS4wLjABAAAAv7iSuuXDJGDvJkmH_vz1qkDZYo1apxgzaxdBS…", "signature": "Your next discovery is waiting on TikTok.", "totalLikes": 466000000, "likesGiven": 4377 } }, "text": "The best part of searching a new city on TikTok?…", "createdAt": "2026-10-23T23:29:02.000Z", "lang": "en", "media": [ { "type": "video", "url": "https://www.tiktok.com/aweme/v1/play/?faid=1988&f…", "width": 720, "height": 1280, "thumbnailUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-usea…", "durationSec": 107, "variants": [ { "url": "https://www.tiktok.com/aweme/v1/play/?faid=1988&f…", "width": 720, "height": 1280, "bitrate": 740138, "contentType": "video/mp4" } ], "ext": { "playAddr": "https://v16-webapp-prime.us.tiktok.com/video/tos/…", "downloadAddr": "https://v16-webapp-prime.us.tiktok.com/video/tos/…", "dynamicCover": "https://p19-common-sign.tiktokcdn-us.com/tos-usea…", "definition": "720p", "videoQuality": "normal", "ratio": "720p", "codec": "h264", "format": "mp4", "bitrate": 740138, "sizeBytes": 9949494, "loudness": -19.9, "peak": 1, "hasOriginalAudio": true, "autoCaption": true, "bitrateVariants": [ { "gearName": "normal_720_0", "fps": 23, "codec": "h264", "sizeBytes": 9949494 } ], "subtitles": [ { "lang": "eng-US", "langId": "2", "url": "https://v16m-webapp.tiktokcdn-us.com/be8291ee2919…", "format": "webvtt", "source": "ASR" } ] } } ], "metrics": { "likes": 2235, "comments": 553, "shares": 144, "views": 122800, "reposts": 0, "saves": 132 }, "entities": { "mentions": [ { "handle": "morimatcha__", "id": "7547085538516485175" } ] }, "audio": { "id": "7700009421400869662", "title": "original sound", "artist": "TikTok", "url": "https://v16m.tiktokcdn-us.com/b9eda378f913298c1de…" }, "ext": { "music": { "original": true, "coverUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-usea…", "durationSec": 107, "isCommerceMusic": true, "appleMusicId": "1543888610", "spotifyId": "5Cf5U4MLpSJQb29IqY8bWA" }, "duetEnabled": true, "stitchEnabled": true } } ], "cursor": "z3_ejXLXnHrW_fwkl8jd8OBVtLZI0s7eC6UysxOBxhQMNFiYF…" } } ``` ## 错误 | 状态 | 代码 | 含义 | |---|---|---| | 400 | `INVALID_CURSOR` | 该 `cursor` 不是本操作返回的。请不带它重新开始。 | | 400 | `INVALID_PARAMS` | 参数缺失、未知或超出范围。消息中会指出是哪一个。 | | 401 | `UNAUTHORIZED` | 缺少 `x-api-key` 请求头，或密钥已吊销或未知。 | | 402 | `INSUFFICIENT_BALANCE` | 余额不足以支付本次调用。请在控制台充值。 | | 404 | `NOT_FOUND` | 账号、帖子或分组不存在，或为私密、已删除、有年龄限制。 | | 429 | `MARKETPLACE_SATURATED` | 并发调用过多。请等待 `Retry-After` 秒后重试。 | | 502 | `UPSTREAM_ERROR` | 平台返回了无法使用的内容。请退避后重试。 | 全部错误代码见 [Errors](/docs/errors)。失败的调用不计费。 ## 价格 **Price** $0.001 per call, plus $0.001 for each extra call it makes — at most 1 more, so $0.002 in total. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day. ## 说明 - `userId` 是创作者的 `secUid`。用它代替 `username` 可省去一次查询：计 1 个单位而不是 2 个。