tiktok — Claude Code skill: what it does, how to install
Posts finished videos to TikTok profiles or saves them as drafts using TikTok API v2. It requires explicit confirmation for all privacy and duet settings.
Apache-2.0 178 installs ★ 17 updated 2026-10-25
npx skills add AceDataCloud/Skills --skill tiktok -a claude-codeWhat tiktok does
The skill connects to TikTok Content Posting API v2 via curl, jq, and Python scripts. Every request requires an active bearer token in $TIKTOK_TOKEN. It checks basic profile data like open_id and creator name, skipping endpoints that need unapproved scopes such as follower counts or video listings.
Two posting modes are available: immediate profile publishing and uploading to drafts. Local MP4 files upload as a single chunk if they stay under 64 MB. Remote video URLs must use direct HTTPS links on the verified domain acedata.cloud without redirects.
Direct posts require manual approval through request_action_confirmation. Without $TIKTOK_TOKEN configured, API calls fail with status 401. The skill will not guess or preselect privacy levels, duet rules, or stitch permissions on your behalf.
What it helps with
- publish local MP4 files directly to a TikTok creator profile
- upload videos to TikTok drafts for mobile app sound and caption editing
- confirm interaction toggles and privacy levels before posting
- track video processing status using its
publish_id
Example prompts for the agent
- Upload
clip.mp4to my TikTok drafts - Post
teaser.mp4directly to TikTok with comments disabled - Check the publishing progress for my
publish_id
How to install tiktok
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill tiktok -a claude-code2Manually: put the files in place
~/.claude/skills/tiktok/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tiktok/
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill tiktok -a codex2Manually: put the files in place
.agents/skills/tiktok/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill tiktok -a cursor2Manually: put the files in place
.cursor/skills/tiktok/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install AceDataCloud/Skills skills/tiktok2Manually: put the files in place
.github/skills/tiktok/SKILL.md1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill tiktok -a gemini-cli2Platform CLI
gemini skills install https://github.com/AceDataCloud/Skills --path skills/tiktokManually: put the files in place
.devin/skills/tiktok/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill tiktok -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tiktok
How to install tiktok in Claude Code?
Run npx skills add AceDataCloud/Skills --skill tiktok -a claude-code. The file will be placed in ~/.claude/skills/tiktok/SKILL.md.
What does the tiktok skill do?
It handles posting video content to TikTok using API v2. It supports direct profile posting after user confirmation as well as uploading to account drafts.
What video file restrictions apply?
Local MP4 uploads cannot exceed 64 MB. For remote files, the skill only accepts public HTTPS URLs under the acedata.cloud domain.
Source text
SKILL.md · Apache-2.0
---
name: tiktok
description: Publish a creator's video directly to TikTok after their review and confirmation, or upload it to drafts when requested.
when_to_use: |
Trigger when the user wants to post a video to their own TikTok account
or send it to TikTok drafts. For a direct post, show the TikTok publish
card and use the creator's selected privacy and interaction settings.
Use the inbox flow only when the user asks for a draft.
connections: [tiktok]
allowed_tools: [Bash, request_action_confirmation]
license: Apache-2.0
metadata:
author: acedatacloud
version: "2.4"
---
Call the **TikTok API v2** with `curl + jq`. The user's OAuth bearer token is in
`$TIKTOK_TOKEN`; every call needs `Authorization: Bearer $TIKTOK_TOKEN`. Base
URL: `https://open.tiktokapis.com/v2`.
```bash
T="https://open.tiktokapis.com/v2"; AUTH="Authorization: Bearer $TIKTOK_TOKEN"
```
Responses wrap everything in `{"data":…,"error":{"code","message","log_id"}}`.
**Check `error.code`, not just the HTTP status** — several real failures
(`spam_risk_too_many_posts`, `spam_risk_user_banned_from_posting`,
`reached_active_user_cap`) come back as **HTTP 200** with a non-`ok` code. Show
`error.message` verbatim. `401` / `access_token_invalid` = re-connect TikTok.
## Read the account
```bash
# Basic profile — open_id identifies the user for every posting call
curl -sS -H "$AUTH" "$T/user/info/?fields=open_id,display_name,avatar_url" \
| jq '.data.user'
```
Follower / like counts, bio, and the user's video list need the **Display API**
scopes (`user.info.stats`, `user.info.profile`, `video.list`), which this app
has not been granted — don't call `/v2/video/list/` or request those fields,
they will fail with `scope_not_authorized`.
## Direct Post to the creator's profile
The production app has passed TikTok's Content Posting API audit. A direct post
publishes to the creator's profile after processing; it is not a draft. Never
choose a privacy level, interaction setting, or disclosure on the creator's
behalf. Never retry an init request while its `publish_id` is processing.
Required sequence:
1. Identify the exact video and its source. Measure its duration and preview
it. A server-hosted video must use a public, non-redirecting HTTPS URL under
the verified `acedata.cloud` domain (`PULL_FROM_URL`). A creator-selected
device-local MP4 may use `FILE_UPLOAD` and must be no larger than 64 MB.
2. Query the selected connection with
`python3 skills/tiktok/scripts/tiktok.py creator-info`. Check
`creator_username` against the account the creator named. Copy the current
nickname, avatar, `privacy_level_options`, interaction restrictions, and
maximum duration into `request_action_confirmation` with
`kind: "tiktok.publish"` and the real video preview. Do not invent or
preselect a privacy option.
3. If cancelled, stop. If confirmed, use exactly the card's returned `title`,
`privacy_level`, `disable_comment`, `disable_duet`, `disable_stitch`,
`brand_organic_toggle`, and `brand_content_toggle`. Add `is_aigc: true`
for AI-generated content and `false` otherwise. For an Ace Data Cloud brand
promotion, the creator must select the own-brand promotional disclosure.
Store these values in a temporary JSON file outside the repository.
4. Submit **once** after confirmation, with the exact selected account:
```bash
# Server-hosted video on the verified domain:
python3 skills/tiktok/scripts/tiktok.py post-url "$VIDEO_URL" \
--duration-sec "$DURATION" \
--expected-creator-username "$CONFIRMED_CREATOR_USERNAME" \
--values-file "$VALUES_JSON" --confirmed
# Creator-selected device-local MP4:
python3 skills/tiktok/scripts/tiktok.py post-file video.mp4 \
--duration-sec "$DURATION" \
--expected-creator-username "$CONFIRMED_CREATOR_USERNAME" \
--values-file "$VALUES_JSON" --confirmed
```
Both commands re-query creator info and reject a different account, an
unavailable privacy level, disabled interactions, or an overlong video.
Never substitute confirmed fields after this check.
5. Poll the returned `publish_id` with `status` until `PUBLISH_COMPLETE` or a
terminal failure. Report the actual outcome. An accepted init or successful
file transfer is not a published post.
## Upload the video to the user's drafts
Use this when the creator explicitly asks for a draft. The video lands in their TikTok **inbox /
drafts**; they open the TikTok app to add caption, sound and privacy, then post.
Required order:
1. Identify the exact video and its source: a creator's device-local file or a
server-hosted URL under the verified `acedata.cloud` domain. Preview it.
2. Call `request_action_confirmation` with `kind: "generic"`, the real video
preview, and a summary that says this uploads to drafts rather than publishing.
3. If cancelled, stop. If confirmed, run exactly one upload. For a device-local
file use `python3 skills/tiktok/scripts/tiktok.py upload video.mp4`. For a
server-hosted video use
`python3 skills/tiktok/scripts/tiktok.py upload-url "$VIDEO_URL"`.
4. Poll with `python3 skills/tiktok/scripts/tiktok.py status PUBLISH_ID` until
terminal. Never call `upload` again while polling.
Two source modes are available. The developer portal verified `acedata.cloud`
on 2026-10-03, covering its subdomains. Server-hosted videos on that domain
must use `PULL_FROM_URL`; use `FILE_UPLOAD` only for a creator's device-local
file. Verify that the exact URL is public HTTPS and does not redirect.
### FILE_UPLOAD (creator device-local file)
Use this only for a file the creator selected from their own device. Files
under 64 MB go up as a single chunk.
```bash
SIZE=$(stat -f%z video.mp4 2>/dev/null || stat -c%s video.mp4)
INIT=$(curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json" \
-d "$(jq -n --argjson s "$SIZE" \
'{source_info:{source:"FILE_UPLOAD", video_size:$s, chunk_size:$s, total_chunk_count:1}}')" \
"$T/post/publish/inbox/video/init/")
echo "$INIT" | jq '{publish_id:.data.publish_id, error:.error.code}'
UPLOAD_URL=$(echo "$INIT" | jq -r '.data.upload_url')
curl -sS -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
-H "Content-Length: $SIZE" \
-H "Content-Range: bytes 0-$((SIZE-1))/$SIZE" \
--data-binary @video.mp4 -o /dev/null -w '%{http_code}\n'
```
The `PUT` returns **201** when the whole file landed (206 for intermediate
chunks). `upload_url` expires in **1 hour**.
### PULL_FROM_URL (only from a verified domain)
```bash
python3 skills/tiktok/scripts/tiktok.py upload-url "$VIDEO_URL"
```
The helper requires public HTTPS under the verified `acedata.cloud` domain,
`video/mp4`, and no redirects. Domain verification covers subdomains downward.
## Poll status
```bash
curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json" \
-d "$(jq -n --arg id "$PUBLISH_ID" '{publish_id:$id}')" \
"$T/post/publish/status/fetch/" | jq '.data | {status, fail_reason}'
```
`PROCESSING_UPLOAD` / `PROCESSING_DOWNLOAD` → **`SEND_TO_USER_INBOX`** = done,
the video is waiting in the creator's TikTok inbox. Tell them to open the
TikTok app to finish posting, and that processing takes a few minutes.
Don't retry on `auth_removed`, `spam_risk_text`, `spam_risk`, or
`spam_risk_user_banned_from_posting` — those are terminal. `internal` is
retryable.
## Gotchas
- **Never preselect `privacy_level`** in the confirmation card. The helper
checks the creator's selection against fresh `privacy_level_options` before
making the one Direct Post call. Branded content cannot be `SELF_ONLY`.
- Connections made with the former Sandbox app must be reconnected to the
Production app. If TikTok returns
`unaudited_client_can_only_post_to_private_accounts`, stop and ask the
creator to reconnect; do not retry the same post or change its privacy.
- Rate limits per user token: `creator_info/query` 20/min, `video/init/`
**6/min**, `status/fetch/` 30/min. TikTok also caps posts at roughly 15/day
per creator, **shared across all apps** — another app can exhaust it.
- `SEND_TO_USER_INBOX` is success for this flow, not an intermediate state.
Don't wait for `PUBLISH_COMPLETE` — that only happens once the user posts
from the app.
© acedatacloud · Apache-2.0 · AceDataCloud/Skills