tiktok

curl + jq を使って TikTok API v2 を呼び出します。ユーザーの OAuth ベアラートークンは $TIKTOK_TOKEN にあります。すべての呼び出しで Authorization: Bearer $TIKTOK_TOKEN が必要です。ベース URL：https://open.tiktokapis.com/v2。

T="https://open.tiktokapis.com/v2"; AUTH="Authorization: Bearer $TIKTOK_TOKEN"

レスポンスの内容はすべて {"data":…,"error":{"code","message","log_id"}} でラップされています。 HTTP ステータスだけでなく、error.code を確認してください。実際に発生するいくつかのエラー （spam_risk_too_many_posts、spam_risk_user_banned_from_posting、 reached_active_user_cap）は、非 ok コードとともに HTTP 200 で返されます。error.message は そのまま表示してください。401／access_token_invalid の場合は、TikTok に再接続してください。

アカウントの読み取り

# 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'

フォロワー数／いいね数、プロフィール文、ユーザーの動画一覧には Display API スコープ （user.info.stats、user.info.profile、video.list）が必要ですが、このアプリには付与されていません。 /v2/video/list/ を呼び出したり、これらのフィールドを要求したりしないでください。 scope_not_authorized で失敗します。

クリエイターのプロフィールへの直接投稿

本番アプリは TikTok の Content Posting API 監査に合格しています。直接投稿すると、処理後に クリエイターのプロフィールに公開されます。下書きではありません。クリエイターに代わってプライバシー レベル、インタラクション設定、または開示項目を選択してはいけません。publish_id が処理中の間は、 init リクエストを再試行してはいけません。

必須の手順：

1. 対象の動画とそのソースを特定します。動画の長さを測定し、プレビューします。サーバーにホストされた 動画には、検証済みの acedata.cloud ドメイン配下にある、リダイレクトしない公開 HTTPS URL （PULL_FROM_URL）を使用する必要があります。クリエイターが選択した端末内の MP4 は FILE_UPLOAD を使用できますが、サイズは 64 MB 以下でなければなりません。

2. python3 skills/tiktok/scripts/tiktok.py creator-info を使って、選択した接続の情報を照会します。 creator_username が、クリエイターの指定したアカウントと一致することを確認します。現在の ニックネーム、アバター、privacy_level_options、インタラクション制限、最大動画時間を、実際の動画 プレビューとともに kind: "tiktok.publish" を指定した request_action_confirmation にコピーします。 プライバシー設定を捏造したり、事前選択したりしてはいけません。

3. キャンセルされた場合は停止します。確認された場合は、カードから返された title、 privacy_level、disable_comment、disable_duet、disable_stitch、 brand_organic_toggle、brand_content_toggle をそのまま使用します。AI 生成コンテンツには is_aigc: true を、それ以外には false を追加します。Ace Data Cloud のブランドプロモーションでは、 クリエイターが自社ブランドのプロモーション開示を選択する必要があります。これらの値はリポジトリ外の 一時 JSON ファイルに保存します。

4. 確認後、選択した正確なアカウントを使って 1 回だけ 送信します。

   # 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
   

   どちらのコマンドもクリエイター情報を再照会し、別のアカウント、利用できないプライバシーレベル、 無効なインタラクション設定、または動画の長さ超過を検出した場合は拒否します。この確認後に、 確認済みのフィールドを置き換えてはいけません。

5. 返された publish_id を status でポーリングし、PUBLISH_COMPLETE または最終的な失敗状態に なるまで確認します。実際の結果を報告します。init が受理されたことやファイル転送が成功したことは、 投稿が公開されたことを意味しません。

動画をユーザーの下書きにアップロードする

クリエイターが下書きとして保存するよう明示的に依頼した場合に使用します。動画は TikTok の 受信トレイ／下書き に保存されます。投稿するには、クリエイターが TikTok アプリを開き、キャプション、サウンド、公開範囲を追加します。

必須の順序：

1. 対象の動画とそのソースを特定します。ソースは、クリエイターのデバイス上にあるローカルファイル、または検証済みの acedata.cloud ドメイン上でホストされた URL です。動画をプレビューします。
2. 実際の動画プレビューと、公開ではなく下書きにアップロードすることを明記した概要を指定して、kind: "generic" で request_action_confirmation を呼び出します。
3. キャンセルされた場合は停止します。確認された場合は、アップロードを1回だけ実行します。デバイス上のローカルファイルには python3 skills/tiktok/scripts/tiktok.py upload video.mp4 を使用します。サーバー上でホストされた動画には python3 skills/tiktok/scripts/tiktok.py upload-url "$VIDEO_URL" を使用します。
4. python3 skills/tiktok/scripts/tiktok.py status PUBLISH_ID で終端状態になるまでポーリングします。ポーリング中に upload を再度呼び出してはいけません。

利用可能なソースモードは2種類です。デベロッパーポータルでは、2026-10-03 に acedata.cloud が検証されており、そのサブドメインも対象です。そのドメイン上でホストされた動画には PULL_FROM_URL を使用する必要があります。クリエイターのデバイス上にあるローカルファイルにのみ FILE_UPLOAD を使用してください。URL が正確にパブリック HTTPS であり、リダイレクトしないことを確認します。

FILE_UPLOAD（クリエイターのデバイス上にあるローカルファイル）

クリエイターが自身のデバイスから選択したファイルにのみ使用します。64 MB 未満のファイルは、1つのチャンクでアップロードされます。

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'

ファイル全体のアップロードが完了すると、PUT は 201 を返します（中間チャンクでは206）。upload_url の有効期限は 1時間 です。

PULL_FROM_URL（検証済みドメインからのみ）

python3 skills/tiktok/scripts/tiktok.py upload-url "$VIDEO_URL"

このヘルパーでは、検証済みの acedata.cloud ドメイン上にあるパブリック HTTPS、video/mp4、およびリダイレクトがないことが必要です。ドメインの検証範囲には、そのサブドメインが含まれます。

ステータスをポーリングする

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 = 完了です。動画はクリエイターの TikTok 受信トレイで待機しています。投稿を完了するために TikTok アプリを開くよう伝え、処理には数分かかることも伝えてください。

auth_removed、spam_risk_text、spam_risk、spam_risk_user_banned_from_posting の場合は再試行しないでください。これらは終端状態です。internal は再試行できます。

注意点

• 確認カードで privacy_level を事前選択してはいけません。ヘルパーは、Direct Post の呼び出しを1回行う前に、クリエイターの選択内容を最新の privacy_level_options と照合します。ブランドコンテンツを SELF_ONLY に設定することはできません。
• 以前の Sandbox アプリで接続したアカウントは、Production アプリに再接続する必要があります。TikTok が unaudited_client_can_only_post_to_private_accounts を返した場合は停止し、クリエイターに再接続を依頼してください。同じ投稿を再試行したり、公開範囲を変更したりしないでください。
• ユーザートークンごとのレート制限：creator_info/query は20回／分、video/init/ は 6回／分、status/fetch/ は30回／分です。TikTok ではさらに、クリエイターあたりの投稿数が約15件／日に制限されています。すべてのアプリで共有されるため、別のアプリで上限に達することがあります。
• このワークフローでは SEND_TO_USER_INBOX が成功を意味し、中間状態ではありません。ユーザーがアプリから投稿したときにのみ発生する PUBLISH_COMPLETE を待たないでください。