{ "openapi": "3.0.3", "info": { "title": "TikTokAPI.io API", "version": "1.0.0", "description": "High-speed, no-watermark TikTok Data & Creative Center Ads API.\n\n**Authentication** — pass your API key in the `x-api-key` request header (`Authorization: Bearer tk_...` is also supported). Never pass your API key in the URL query string.\n\n**Unified Credit System** — `$1 = 10,000 Credits` (`1 Credit = $0.0001`). Minimum charge per billable call is `10 Credits` (`$0.001`).\n- **Video feeds & search** (`/v1/video/search`, `/v1/user/posts`, `/v1/challenge/posts`, `/v1/music/posts`, `/v1/feed/list`): **2 Credits / video** (`$0.20 / 1K videos`, min 10 Credits).\n- **Comments & replies** (`/v1/comment/list`, `/v1/comment/reply`): **1 Credit / comment** (`$0.10 / 1K comments`, min 10 Credits).\n- **Followers, following & user search** (`/v1/user/followers`, `/v1/user/following`, `/v1/user/search`): **1 Credit / user** (`$0.10 / 1K users`, min 10 Credits).\n- **Single lookups & 1080p video parser** (`/v1/video/detail`, `/v1/user/info`, `/v1/challenge/info`, `/v1/music/info`, `/v1/ads/top/ads/detail`): **10 Credits / request** (`$1.00 / 1K requests`).\n- **Commercial Ads Library** (`/v1/ads/top/ads`): **10 Credits / ad** (`$1.00 / 1K ads`, min 10 Credits).\n\nEvery charged response includes `x-credits-cost`, `x-credits-remaining`, `x-balance-remaining`, and `x-request-id`. Failed upstream calls (`code != 0`), rate-limited calls (`429`), and gateway errors (`5xx`) are **never charged**.\n\n**Response Envelope** — all data endpoints return JSON with `{\"code\": 0, \"msg\": \"success\", \"processed_time\": 0.18, \"data\": ...}`. Always check `code === 0`.\n", "contact": { "email": "contact@tiktokapi.io", "url": "https://tiktokapi.io" } }, "servers": [ { "url": "https://api.tiktokapi.io" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Videos", "description": "Single video 1080p no-watermark parser & keyword video search." }, { "name": "Users", "description": "Creator profile info, public video posts, and creator search." }, { "name": "Followers", "description": "Creator followers and following lists (up to 200 per call)." }, { "name": "Comments", "description": "Top-level video comments and nested second-level replies." }, { "name": "Hashtags", "description": "Hashtag challenge metrics and tagged video feeds." }, { "name": "Music", "description": "Sound/music track details and videos using a sound." }, { "name": "Trending", "description": "Regional trending video feeds by country code." }, { "name": "Commercial Ads", "description": "TikTok Creative Center top ads library and 1080p ad creative details." } ], "paths": { "/v1/video/detail": { "get": { "operationId": "v1_video_detail", "tags": [ "Videos" ], "summary": "Get video or photo carousel detail & 1080p no-watermark URL", "description": "Fetch full metadata, engagement metrics, creator profile, music track, image carousel slides, and direct 1080p HD no-watermark download links (`data.play`, `data.hdplay`) for any public TikTok video.", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "TikTok video URL, short link (`vm.tiktok.com`), or numeric video ID.", "example": "https://www.tiktok.com/@tiktok/video/7106594312292453675" }, { "name": "hd", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 1 }, "description": "Set to `1` to include the 1080p HD no-watermark stream URL in `data.hdplay`.", "example": 1 } ], "x-price-per-request": "$1.00 / 1K requests", "x-credits-per-request": "10 Credits / request", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/video/search": { "get": { "operationId": "v1_video_search", "tags": [ "Videos" ], "summary": "Search videos by keyword", "description": "Search public TikTok videos by keyword with filters for region, sort order, and publish time window. Every video item includes direct no-watermark playback links and full engagement statistics. Paginated via `cursor` and `hasMore`.", "parameters": [ { "name": "keywords", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search keywords, e.g. `ai tools` or `skincare routine`.", "example": "ai tools" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 20 }, "description": "Number of videos to return per page (max 30).", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset cursor (`0` for first page, then pass `data.cursor` from the previous response).", "example": 0 }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "default": "US" }, "description": "Two-letter ISO country code (`US`, `GB`, `JP`, `DE`, `BR`, etc.).", "example": "US" }, { "name": "sort_type", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1, 3 ], "default": 0 }, "description": "Sort order: `0` = Relevance, `1` = Most Liked, `3` = Newest.", "example": 0 }, { "name": "publish_time", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1, 7, 30, 90, 180 ], "default": 0 }, "description": "Publish window filter: `0` = All time, `1` = Yesterday, `7` = Past 7 days, `30` = Past 30 days, `90` = Past 3 months, `180` = Past 6 months.", "example": 0 } ], "x-price-per-request": "$0.20 / 1K videos", "x-credits-per-request": "2 Credits / video (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/user/info": { "get": { "operationId": "v1_user_info", "tags": [ "Users" ], "summary": "Get creator profile & account statistics", "description": "Fetch a TikTok creator's public profile (`data.user`: `id`, `uniqueId`, `nickname`, `secUid`, `verified`, `signature`, avatars) and real-time counters (`data.stats`: `followerCount`, `followingCount`, `heartCount`, `videoCount`).", "parameters": [ { "name": "unique_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Creator handle without `@`, e.g. `tiktok` or `khaby.lame`.", "example": "tiktok" } ], "x-price-per-request": "$1.00 / 1K requests", "x-credits-per-request": "10 Credits / request", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/user/posts": { "get": { "operationId": "v1_user_posts", "tags": [ "Users" ], "summary": "Get creator's public video posts", "description": "Paginated list of public videos posted by a creator (`data.videos`), newest first, including no-watermark video streams and engagement statistics. Pass `unique_id`, `user_id`, or `sec_uid`.", "parameters": [ { "name": "unique_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Creator handle without `@`, e.g. `tiktok`.", "example": "tiktok" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 35, "default": 20 }, "description": "Number of videos per page (max 35).", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "default": "0" }, "description": "Pagination cursor (`0` for the first page, then pass `data.cursor`).", "example": "0" } ], "x-price-per-request": "$0.20 / 1K videos", "x-credits-per-request": "2 Credits / video (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/user/search": { "get": { "operationId": "v1_user_search", "tags": [ "Users" ], "summary": "Search creator accounts", "description": "Discover TikTok creators by keyword with optional filters for follower tier and verification status. Paginated via `cursor` and `has_more`.", "parameters": [ { "name": "keywords", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search keywords or username query.", "example": "ai" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination cursor (`0` for first page, then pass `data.cursor`).", "example": 0 }, { "name": "follower_count", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "default": 0 }, "description": "Follower count tier: `0` = Any, `1` = 0–1K, `2` = 1K–10K, `3` = 10K–100K, `4` = 100K+.", "example": 0 }, { "name": "profile_type", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "Verification filter: `0` = Any, `1` = Verified accounts only.", "example": 0 }, { "name": "search_emphasis", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "Search scope: `0` = General, `1` = Username match only.", "example": 0 } ], "x-price-per-request": "$0.10 / 1K users", "x-credits-per-request": "1 Credit / user (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/user/followers": { "get": { "operationId": "v1_user_followers", "tags": [ "Followers" ], "summary": "Get user followers list", "description": "Paginated list of accounts following a creator (`data.followers`), up to 200 per request. First retrieve `user_id` and `sec_uid` from `/v1/user/info`, then pass `data.min_time` as `time` for subsequent pages.", "parameters": [ { "name": "user_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Numeric TikTok user ID (`data.user.id` from `/v1/user/info`).", "example": "107955" }, { "name": "sec_uid", "in": "query", "required": false, "schema": { "type": "string" }, "description": "SecUID (`data.user.secUid` from `/v1/user/info`). Recommended for reliability.", "example": "MS4wLjABAAAAv7iSuuXDJGDvJkmH_vz1qkDZYo1apxgzaxdBSeIuPiM" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of followers per request (max 200).", "example": 50 }, { "name": "time", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination timestamp cursor (`0` for first page, then pass `data.min_time`).", "example": 0 } ], "x-price-per-request": "$0.10 / 1K followers", "x-credits-per-request": "1 Credit / user (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/user/following": { "get": { "operationId": "v1_user_following", "tags": [ "Followers" ], "summary": "Get user following list", "description": "Paginated list of accounts that a creator follows (`data.followings`), up to 200 per request. Pass `data.min_time` as `time` for subsequent pages.", "parameters": [ { "name": "user_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Numeric TikTok user ID (`data.user.id` from `/v1/user/info`).", "example": "107955" }, { "name": "sec_uid", "in": "query", "required": false, "schema": { "type": "string" }, "description": "SecUID (`data.user.secUid` from `/v1/user/info`).", "example": "MS4wLjABAAAAv7iSuuXDJGDvJkmH_vz1qkDZYo1apxgzaxdBSeIuPiM" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of accounts per request (max 200).", "example": 50 }, { "name": "time", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination timestamp cursor (`0` for first page, then pass `data.min_time`).", "example": 0 } ], "x-price-per-request": "$0.10 / 1K followings", "x-credits-per-request": "1 Credit / user (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/comment/list": { "get": { "operationId": "v1_comment_list", "tags": [ "Comments" ], "summary": "Get top-level video comments", "description": "Paginated top-level comments on a TikTok video (`data.comments`), up to 50 per page, including commenter profile, like count, and reply count.", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "TikTok video URL or numeric video ID.", "example": "https://www.tiktok.com/@tiktok/video/7106594312292453675" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "Number of comments per page (max 50).", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination cursor (`0` for first page, then pass `data.cursor`).", "example": 0 } ], "x-price-per-request": "$0.10 / 1K comments", "x-credits-per-request": "1 Credit / comment (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/comment/reply": { "get": { "operationId": "v1_comment_reply", "tags": [ "Comments" ], "summary": "Get second-level comment replies", "description": "Paginated nested replies (`data.comments`) under a top-level comment (`comment_id`). Accepts either `url` or `video_id` to identify the video.", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "TikTok video URL or numeric video ID (`video_id` is also accepted).", "example": "7106594312292453675" }, { "name": "comment_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Top-level comment ID (`id` from `/v1/comment/list`).", "example": "7106598090963878662" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "Number of replies per page (max 50).", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination cursor (`0` for first page, then pass `data.cursor`).", "example": 0 } ], "x-price-per-request": "$0.10 / 1K comments", "x-credits-per-request": "1 Credit / comment (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/challenge/info": { "get": { "operationId": "v1_challenge_info", "tags": [ "Hashtags" ], "summary": "Get hashtag (challenge) detail & total views", "description": "Look up a hashtag by name to retrieve its numeric `cid` (`data.id`), description, video count (`data.userCount`), and total view count (`data.viewCount`).", "parameters": [ { "name": "challenge_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Hashtag name without `#`, e.g. `fyp` or `tiktokmademebuyit`.", "example": "fyp" } ], "x-price-per-request": "$1.00 / 1K requests", "x-credits-per-request": "10 Credits / request", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/challenge/posts": { "get": { "operationId": "v1_challenge_posts", "tags": [ "Hashtags" ], "summary": "Get videos under a hashtag", "description": "Paginated list of videos tagged with a hashtag (`data.videos`), including no-watermark video URLs and engagement stats. Pass `cid` (or `challenge_id`) obtained from `/v1/challenge/info`.", "parameters": [ { "name": "cid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Numeric hashtag ID (`data.id` from `/v1/challenge/info`; `challenge_id` is also accepted).", "example": "42164" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 20 }, "description": "Number of videos per page (max 30).", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination cursor (`0` for first page, then pass `data.cursor`).", "example": 0 } ], "x-price-per-request": "$0.20 / 1K videos", "x-credits-per-request": "2 Credits / video (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/music/info": { "get": { "operationId": "v1_music_info", "tags": [ "Music" ], "summary": "Get sound / music track detail", "description": "Retrieve metadata for a TikTok sound or original audio track (`data.id`, `data.title`, `data.author`, `data.play` MP3 URL, `data.video_count`).", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "TikTok music URL or numeric music ID.", "example": "7106594322274962182" } ], "x-price-per-request": "$1.00 / 1K requests", "x-credits-per-request": "10 Credits / request", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/music/posts": { "get": { "operationId": "v1_music_posts", "tags": [ "Music" ], "summary": "Get videos using a sound / music track", "description": "Paginated list of videos that use a specific sound (`data.videos`), including no-watermark playback streams and stats.", "parameters": [ { "name": "music_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Numeric music ID (`data.id` from `/v1/music/info`).", "example": "7106594322274962182" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 20 }, "description": "Number of videos per page (max 30).", "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination cursor (`0` for first page, then pass `data.cursor`).", "example": 0 } ], "x-price-per-request": "$0.20 / 1K videos", "x-credits-per-request": "2 Credits / video (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/feed/list": { "get": { "operationId": "v1_feed_list", "tags": [ "Trending" ], "summary": "Get regional trending video feed", "description": "Fetch currently trending TikTok videos for a specific country/region (`data`: array of video objects with direct no-watermark URLs and full engagement statistics).", "parameters": [ { "name": "region", "in": "query", "required": true, "schema": { "type": "string", "default": "US" }, "description": "Two-letter ISO country code (`US`, `GB`, `DE`, `BR`, `JP`, `KR`, etc.).", "example": "US" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 20 }, "description": "Number of trending videos to return.", "example": 20 } ], "x-price-per-request": "$0.20 / 1K videos", "x-credits-per-request": "2 Credits / video (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/ads/top/ads": { "get": { "operationId": "v1_ads_top_ads", "tags": [ "Commercial Ads" ], "summary": "Search top-performing TikTok Creative Center ads", "description": "Query top-performing commercial ads from TikTok Creative Center (`data.materials`), filtered by country, time window, and ranking metric (`impression`, `ctr`, `like`).", "parameters": [ { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string", "default": "US" }, "description": "Two-letter country code (`US`, `GB`, `CA`, `DE`, `JP`, etc.).", "example": "US" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 7, 30, 180 ], "default": 7 }, "description": "Time range in days (`7`, `30`, or `180`).", "example": 7 }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "impression", "ctr", "like" ], "default": "impression" }, "description": "Ranking metric: `impression`, `ctr`, or `like`.", "example": "impression" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number (starts at `1`).", "example": 1 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 }, "description": "Ads per page (max 20).", "example": 20 } ], "x-price-per-request": "$1.00 / 1K ads", "x-credits-per-request": "10 Credits / ad (min 10 Credits)", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/ads/top/ads/detail": { "get": { "operationId": "v1_ads_top_ads_detail", "tags": [ "Commercial Ads" ], "summary": "Get commercial ad detail & 1080p video source", "description": "Fetch full creative performance metrics, ad objective, landing page link, brand name, and direct 720p/1080p video source (`data.video_info.video_url`) for a Creative Center ad (`ads_id` or `material_id`).", "parameters": [ { "name": "ads_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Creative Center ad material ID (`id` from `/v1/ads/top/ads`; `material_id` is also accepted).", "example": "7206035139393372162" } ], "x-price-per-request": "$1.00 / 1K requests", "x-credits-per-request": "10 Credits / request", "responses": { "200": { "description": "Success (`code === 0`). Charged according to the endpoint credit rate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "success" }, "processed_time": { "type": "number", "example": 0.15 }, "data": { "type": "object", "properties": {} } } }, "example": { "code": 0, "msg": "success", "processed_time": 0.15, "data": {} } } } }, "400": { "description": "Invalid parameters, or API key placed in the URL query string (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid `x-api-key` header (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or disabled unstable endpoint (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed — all `/v1/*` data endpoints use `GET` (not charged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (not charged). Respect the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary upstream or gateway error (not charged). Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key starting with `tk_`. Get 2,000 free credits at https://tiktokapi.io/dashboard" } }, "schemas": { "Error": { "type": "object", "required": [ "code", "status", "msg" ], "properties": { "code": { "type": "integer", "example": -1 }, "status": { "type": "string", "enum": [ "error" ] }, "msg": { "type": "string", "example": "Invalid API key." } } } } } }