メインコンテンツまでスキップ

ローカル API 概要

TikMatrix は、プログラム的にタスクを管理できるローカル RESTful API を提供します。これは、TikMatrix を独自の自動化システムと統合したり、カスタムワークフローを構築したり、バッチ操作を作成したりするのに便利です。

要件​

ライセンス要件

ローカル API は Pro、Team、Business プランのサブスクライバーのみが利用できます。 Starter プランには API へのアクセスがありません。

ベース URL​

API はローカルマシン上で実行されます：

http://localhost:50809/api/v1/
注記

ポート 50809 はデフォルトポートです。API リクエストを行う前に TikMatrix が実行されていることを確認してください。

レスポンス形式​

すべての API レスポンスは次の形式に従います：

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

レスポンスコード​

コード説明
0成功
40001不正なリクエスト - 無効なパラメータ（検証に通らない script_config を含む）
40002不正なリクエスト - script_name が不足
40003不正なリクエスト - このビルドまたはプラットフォームで未対応のスクリプト、実装が存在しない、あるいはタスク状態が不正
40004不正なリクエスト - 実行中のタスクのみ停止できます
40005不正なリクエスト - task_ids は空にできません
40301禁止 - API アクセスには Pro+ プランが必要
40401見つかりません - リソースが見つかりません
50001内部サーバーエラー

クイックスタート​

1. API アクセスの確認​

まず、ライセンスが API アクセスをサポートしているか確認します：

curl http://localhost:50809/api/v1/license/check

レスポンス：

{
  "code": 0,
  "message": "success",
  "data": {
    "plan_name": "Pro",
    "api_enabled": true,
    "device_limit": 20,
    "message": "API access enabled"
  }
}

2. スクリプトとパラメータを調べる​

GET /api/v1/schema は、このビルドで実行できるすべてのスクリプトと、それぞれが受け取る script_config のフィールドを正確に返します。名前、型、既定値、許可される値、必須かどうかまで含みます。サーバーが検証に使うのと同じカタログから生成されるため、タスク作成が実際に受け付ける内容とずれることはありません。

curl http://localhost:50809/api/v1/schema

任意のクエリパラメータが 2 つあります:

パラメータ効果
platform一覧を tiktok または instagram に限定します。このビルドに含まれないプラットフォームは 40001 で拒否されます。既定ではビルドが備えるすべてを返します。
include_unavailabletrue にすると、API は受け付けるが実装のないスクリプト名も一覧に含めます。各項目に unavailable_reason が付きます。

レスポンス（抜粋）:

{
  "code": 0,
  "message": "success",
  "data": {
    "build": { "platforms": ["tiktok"] },
    "scripts": [
      {
        "name": "follow",
        "internal_name": "follow",
        "summary": "Follow the given users. One task per target.",
        "platforms": ["tiktok", "instagram"],
        "available": true,
        "fan_out": { "kind": "per_item", "key": "target_users", "alt_key": "target_user" },
        "any_of": [["target_users", "target_user"]],
        "fields": [
          {
            "key": "access_method",
            "type": "string",
            "required": false,
            "default": "direct",
            "choices": ["direct", "search"],
            "description": "How to reach the profile: direct (via URL) or search."
          }
        ]
      }
    ]
  }
}

fan_out は 1 回のリクエストが生成するタスク数を示します。per_device はデバイスごとに 1 件（マルチアカウントモードではアカウントごとに 1 件）、per_item は指定フィールドの各項目につきデバイスごとに 1 件を作成します。

3. タスクの作成​

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1", "device_serial_2"],
    "script_name": "post",
    "script_config": {
      "content_type": 1,
      "captions": "新しい動画をチェック！#バイラル"
    },
    "enable_multi_account": false,
    "start_time": "14:30"
  }'

4. タスクのリスト​

curl http://localhost:50809/api/v1/task?status=0&page=1&page_size=20

利用可能なスクリプト​

script_name パラメータは次の値を受け入れます：

スクリプト名説明API サポート
postコンテンツを公開✅ サポート済み
followユーザーをフォロー✅ サポート済み
unfollowユーザーをアンフォロー✅ サポート済み
account_warmupアカウントをウォームアップ✅ サポート済み
comment投稿に新規コメント✅ サポート済み
boost_comment既存コメントにいいね/返信✅ サポート済み
loginアカウントにログイン✅ サポート済み
profileプロフィールを更新✅ サポート済み
match_accountデバイス上のアカウントを照合✅ サポート済み
like投稿にいいね✅ サポート済み
view投稿を一定時間視聴✅ サポート済み
favorite投稿をお気に入りに保存✅ サポート済み
repostTikTok動画をリポスト✅ 対応 — TikTok のみ
messageダイレクトメッセージを送信❌ 利用不可 §
follow_suggestedおすすめアカウントをフォロー✅ 対応 — TikTok のみ
super_marketingスーパーマーケティングキャンペーン✅ サポート済み †
scrape_userユーザーデータをスクレイピング🔜 近日公開
† スーパーマーケティングは専用エンドポイントを使用

スーパーマーケティングキャンペーンは POST /api/v1/task では作成しません。再利用可能なターゲットデータセットを基に動作し、専用のエンドポイントが用意されています — スーパーマーケティングスクリプト設定を参照してください。

§ message には実装がありません

message はタスク作成では受け付けられていましたが、スクリプトバイナリ側にどちらのプラットフォーム用のハンドラも存在せず、この種のタスクはすべてデバイス上で "Unknown script" として失敗していました。現在は作成時点でその理由とともに拒否されます。ダイレクトメッセージを送るには、ターゲットデータセットを介して DM を実行する super_marketing を使ってください。

プラットフォーム固有のスクリプト

repost と follow_suggested は TikTok 向けにのみ実装されています。Instagram を対象に作成するとキューに入らず拒否されます。以前はタスクが作成され、その後デバイス上で失敗していました。

script_config の検証​

タスク作成は、何かを書き込む前に上記スキーマに対して script_config を検証します。そのため不正なパラメータは、後で端末上で失敗するタスクではなく、フィールド名を示す 400 として返ります。拒否されるのは次の 3 つです:

  • 必須フィールドが欠けている、または空である
  • いずれか一方が必要なグループでどれも指定されていない（例: follow には target_users / target_user のいずれかが必要）
  • フィールドに記載された choices の範囲外の値

スキーマに載っていないキーは 拒否ではなく無視 されます。デスクトップアプリ自身が同じオブジェクトに独自のキーを通しており、未知のキーを拒否すると既存の連携が壊れるためです。サーバー側のログには記録されるので、アプリのログで打ち間違いに気づけます。

数値は文字列としても送信できます（20 に加えて "20" も可）。スクリプト側がすでに受け付けている形式に合わせています。

タスクステータス​

ステータスコードステータステキスト説明
0pendingタスクは実行待ち
1runningタスクは現在実行中
2completedタスクは正常に完了
3failedタスクは失敗

次のステップ​