デベロッパー向けドキュメント

TokCaption APIドキュメント

公開TikTok動画を文字起こしするREST APIです。AIによるフック分析や台本リライト、文字起こしの大量エクスポートにも対応。APIキーで認証し、URLを送信して結果をポーリングするだけで利用できます。API機能はProプランでご利用いただけます。

REST API · v2.1.0

TokCaption API

公開TikTok動画の文字起こし、AIによるフック分析、大量エクスポートまで、すべてシンプルなJSON REST APIで行えます。APIキーで認証すれば、2回のAPI呼び出しですぐに始められます。AIアシスタントを使いたい方には、同じツールをMCPサーバーとしてClaudeやChatGPTからご利用いただけます。

ベースURL

https://www.tokcaption.com/api/v1

認証

X-API-Key

エンドポイント

6グループにわたる27件

認証

設定 → APIキー（Proプラン）からAPIキーを作成してください。すべてのリクエストで X-API-Key ヘッダーに含めて送信します。ダッシュボードやモバイルクライアントでは、代わりに Supabase JWT を Authorization: Bearer <jwt> として送信することもできます。キーはサーバー側で保管し、ブラウザのバンドルには絶対に含めないでください。

curl "https://www.tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

クイックスタート

URL を送信してから、ジョブが完了するまでポーリングします。単一の URL はインラインで完了することが多いため、ポーリングの前にレスポンスのステータスを確認してください。

ステップ1 — 送信

URLを指定して POST /api/v1/jobs を呼び出します。返された job_id を保存してください。

ステップ2 — ポーリング

ステータスが終了状態になるまで1〜2秒ごとに GET /api/v1/jobs/{jobId} を呼び出し、その後 items[].transcript_text を読み取ります。

URLが1件だけで、ポーリングを避けたい場合は、GET /api/v1/quick を使うと同期的に結果を取得できます。

エラーとレート制限

すべてのエラーは同じJSONエンベロープで返されます。HTTPステータスやメッセージではなく、code で分岐してください。429 の場合は、Retry-After ヘッダーに従ってください。

エラーのエンベロープ

{
  "success": false,
  "error": "Free plan allows 5 transcripts per day.",
  "code": "QUOTA_EXCEEDED",
  "message": "Free plan allows 5 transcripts per day.",
  "error_info": {
    "code": "QUOTA_EXCEEDED",
    "message": "Free plan allows 5 transcripts per day.",
    "details": {
      "limit_type": "daily",
      "daily_limit": 5,
      "retry_after_seconds": 43200
    }
  },
  "details": {
    "limit_type": "daily",
    "daily_limit": 5,
    "retry_after_seconds": 43200
  }
}

すべてのエラーコード

コード	HTTP	意味
AUTH_REQUIRED	401	認証情報が見つからないか無効です。有効な X-API-Key、または Authorization: Bearer <jwt> ヘッダーを送信してください。
VALIDATION_ERROR	400	リクエストボディ、クエリパラメータ、またはパスが無効です。messageとdetailsに修正方法が記載されています。
PLAN_REQUIRED	403	この機能またはオプションには Pro プランが必要です。アップグレードするとご利用いただけます。
NOT_FOUND	404	ジョブ、文字起こし、またはリソースが見つからないか、あなたの所有ではありません。
QUOTA_EXCEEDED	429	文字起こし、エージェント、ダウンロード、または翻訳の上限に達しました。無料プランは毎日、Proは請求サイクルごとにリセットされます。details.reset_atをご確認ください。
RATE_LIMIT_EXCEEDED	429	短時間にサブミット、ポーリング、またはエージェントのリクエストが多すぎます。Retry-Afterヘッダー／details.retry_after_secondsに従ってください。
DUPLICATE_REQUEST	409	idempotency_key が再利用されました。元のリクエストはすでに実行されています。
TRANSLATION_LIMIT_EXCEEDED	429	今月の翻訳利用枠に達しました。請求サイクルごとにリセットされます。
UPSTREAM_TEMPORARY_ERROR	503	TikTokがリクエストを一時的にブロックまたは制限しました。時間をおいて再試行してください。
SEGMENTS_UNAVAILABLE	400	この書き出し形式（srt/vtt）にはタイムスタンプ付きセグメントが必要ですが、文字起こしにはセグメントがありません。
INTERNAL_ERROR	500	予期しないサーバーエラーが発生しました。再試行していただき、解決しない場合はサポートにお問い合わせください。

文字起こし

公開TikTok動画のURLを送信して文字起こしを実行し、ジョブの進捗を追跡できます。

POST/api/v1/jobs

文字起こしジョブを送信

submit の上限

公開TikTok動画のURLを1〜N件送信して文字起こしできます。一括処理の件数はプランによって上限があります。単一のURLの場合は、完了した結果をそのままレスポンスで受け取れることもあります。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en","also_translate_to":["es"],"allow_asr_fallback":false,"include_download_assets":false,"idempotency_key":"client-req-001"}'

単一のURLでも、処理がインラインで完了した場合はHTTP 200で completed または failed の終了ペイロードが返されることがあります。
バッチはHTTP 202を返し、job_id、全体のステータス、itemsの中に各項目のステータスを含みます。
items配列で各動画のステータス（queued、processing、completed、failed）を確認してください。
無料プランで include_download_assets: true を設定すると、PLAN_REQUIRED（403）が返されます。

ボディのフィールド

`urls`必須 string[]	TikTokの動画URL。無料プランの一括上限は5件です。
`output_language` string	対象の文字起こし言語（ISO コード）。デフォルトは en です。
`also_translate_to` string[]	文字起こしを翻訳する追加の言語。
`allow_asr_fallback` boolean	字幕トラックがない場合に音声を文字起こしします。デフォルトはfalseです。
`include_download_assets` boolean	ダウンロード用に動画・カバー画像のアセットを保存します。Proプラン限定。
`idempotency_key` string	重複排除キー。同じキーを再利用すると元のジョブが返されます。

成功時のレスポンス · HTTP 202

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "queued",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

即時の単一成功

HTTP 200

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "total_items": 1,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_single_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "selected_track_type": "creator",
      "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
      "metadata": {
        "author_username": "foodnetwork",
        "duration_seconds": 29
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

失敗（字幕なし）

HTTP 200

{
  "job_id": "8a0d6d7a-78f0-4ab0-8a8c-72f8f5184de8",
  "status": "failed",
  "total_items": 1,
  "completed": 0,
  "failed": 1,
  "items": [
    {
      "id": "tx_single_2",
      "transcript_id": "d40b2545-7c62-4bbb-a7e3-020c663f18a0",
      "item_index": 0,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

ジョブの一覧

文字起こしジョブを新しい順に一覧表示します。カーソルによるページネーションに対応しています。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/jobs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

パラメータ

`cursor` string (ISO date) · query	過去方向へページを戻るには、前回の next_cursor を渡してください。
`limit` integer · query	1ページあたりの件数（1〜50）。デフォルトは20です。
`status` string · query	ジョブのステータスで絞り込みます（例: completed、processing、failed）。

成功時のレスポンス

{
  "jobs": [
    {
      "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
      "created_at": "2026-06-23T10:02:11.000Z",
      "updated_at": "2026-06-23T10:02:48.000Z",
      "origin": "api",
      "status": "completed",
      "collection_name": null
    }
  ],
  "next_cursor": "2026-06-23T10:02:11.000Z"
}

エラー

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

ジョブステータスをポーリング

poll の上限

ジョブが終了状態になるまでポーリングします。集計結果と各アイテムの詳細をすべて返します。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

ジョブの終了状態は completed、partial、failed のいずれかです。ジョブ内の個々のアイテムは異なる場合があります。
完了した項目には、transcript_text、segments、translations、metadata、assets が含まれます。
適切な間隔（1〜2秒ごと）でポーリングしてください。HTTP 429 の場合は retry_after_seconds に従ってください。

パラメータ

jobId必須

string · path

POST /api/v1/jobs が返すジョブID。

成功時のレスポンス

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "total_items": 2,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "completed_at": "2026-03-14T08:33:14.000Z"
    },
    {
      "id": "tx_2",
      "transcript_id": "2448b6b8-7e07-46ef-96be-1f339abdb71f",
      "item_index": 1,
      "status": "processing"
    }
  ]
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/jobs/{jobId}/cancel

ジョブをキャンセル

ジョブ内のキュー待ちまたは処理中の項目をキャンセルします。解放された項目のクォータは返却されます。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6/cancel" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

パラメータ

jobId必須

string · path

キャンセルするジョブID。

成功時のレスポンス

{
  "cancelled_count": 3
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

クイック文字起こし（URL 1件）

submit の上限

単一の URL を送信し、最終結果を（最大約55秒）待ちます。jobs を使った同期的な近道です。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/quick?url=https%3A%2F%2Fwww.tiktok.com%2F%40creator%2Fvideo%2F1234567890" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

処理が終了（completed/failed）すると HTTP 200 を返します。待機時間内にまだ処理中の場合は HTTP 202 を返すので、その後 /api/v1/jobs/{jobId} をポーリングしてください。

パラメータ

url必須

string · query

TikTok動画のURLを1件。

成功時のレスポンス

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed"
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

一括インポート

Prosubmit の上限

URL のリストまたはリンクを含む生テキストを送信します。無料プランでは URL 1件まで、一括処理には Pro が必要です。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/import/collection" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en"}'

ボディのフィールド

`urls` string[]	明示的なURLリスト。こちらかテキストのいずれかを指定してください。
`text` string	自由入力テキスト。TikTokのリンクは自動的に抽出されます。
`output_language` string	対象の文字起こし言語。デフォルトは en です。
`allow_asr_fallback` boolean	字幕がない場合に音声を文字起こしします。デフォルトはfalseです。

成功時のレスポンス · HTTP 202

{
  "total_urls_found": 5,
  "valid_urls": 4,
  "jobs_created": 1,
  "job_ids": [
    "b86f89f2-34f6-4b76-88f6-03c13c51b7a6"
  ],
  "invalid_urls": [
    "https://example.com/not-a-video"
  ]
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

文字起こし一覧

完了した文字起こしとそのアセットの読み取り、検索、エクスポート、ダウンロードを行います。

GET/api/v1/history

文字起こしの一覧・検索

poll の上限

ステータス、フォルダー、並び順で絞り込める、ページ分割された検索可能な文字起こし履歴です。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/history?page=1" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

パラメータ

`page` integer · query	1始まりのページ番号。デフォルトは1です。
`limit` integer · query	1ページあたりの件数（1〜100）。デフォルトは15です。
`search` string · query	文字起こしのテキストと元URLを対象に全文検索します。
`status` string · query	completed \| failed \| all。デフォルトはall。
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc。

成功時のレスポンス

{
  "transcripts": [
    {
      "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "tiktok_video_id": "1234567890",
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "created_at": "2026-06-23T10:02:11.000Z",
      "completed_at": "2026-06-23T10:02:48.000Z",
      "folder": null
    }
  ],
  "page": 1,
  "limit": 15,
  "has_more": true,
  "total_count": 42,
  "total_pages": 3
}

エラー

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

文字起こしを取得

poll の上限

IDを指定して1件の文字起こしを取得します。全文、セグメント、翻訳、メタデータ、アセットを含みます。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

パラメータ

id必須

string · path

文字起こしID。

成功時のレスポンス

{
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed",
  "input_url": "https://www.tiktok.com/@creator/video/1234567890",
  "output_language": "en",
  "source_language": "en",
  "selected_track_type": "creator",
  "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  },
  "metadata": {
    "author_username": "foodnetwork",
    "duration_seconds": 29
  },
  "completed_at": "2026-06-23T10:02:48.000Z"
}

エラー

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

GET/api/v1/transcripts/{id}/export

文字起こしをエクスポート

1件の文字起こしを txt、srt、vtt、csv、json、pdf のいずれかでダウンロードします。json と pdf にはProプランが必要です。

認証: APIキーまたはJWTリクエスト: noneレスポンス: file download

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/export?format=srt" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Content-Disposition: attachment 付きでファイルを返します。format=json の場合は { id, text, segments, metadata } を返します。
srt/vttにはタイムスタンプ付きセグメントが必要です。ない場合はSEGMENTS_UNAVAILABLEになります。

パラメータ

`id`必須 string · path	文字起こしID。
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf。デフォルトはtxt。
`language` string · query	原文言語の代わりに翻訳版をエクスポートします。

成功時のレスポンス

{
  "note": "Binary/text download. Example shows the format=json body.",
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "metadata": {
    "author_username": "foodnetwork"
  }
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

一括エクスポート（ZIP）

複数の文字起こしをIDリストまたはフィルターで指定し、ZIPとして一括エクスポートします。JSON/PDFはProプランが必要です。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/zip

curl -X POST "https://www.tokcaption.com/api/v1/transcripts/export-batch" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"srt","filters":{"status":"completed","orderBy":"created_at_desc"}}'

ボディのフィールド

`format` string	txt \| srt \| vtt \| csv \| json \| pdf。デフォルトはtxt。
`ids` string[]	明示的な文字起こしIDのリスト。省略するとフィルターを使用します。
`filters` object	{ search?, status?, folderId?, orderBy?, view? }。完了した文字起こしのみ書き出されます。

成功時のレスポンス

{
  "note": "Returns a ZIP attachment named tokcaption-srt-export-<date>.zip."
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

文字起こしを削除

文字起こし、保存済みのアセット、フォルダのリンクを完全に削除します。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X DELETE "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

パラメータ

id必須

string · path

文字起こしID。

成功時のレスポンス

{
  "deleted": true
}

エラー

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

文字起こしの統計

poll の上限

アカウントの集計値です。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/stats" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

成功時のレスポンス

{
  "total": 944,
  "completed": 702,
  "failed": 212,
  "folders": 5
}

エラー

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}/download/video

元動画をダウンロード

Pro

元のTikTok動画をMP4形式でダウンロードします。Proプラン限定で、月間のダウンロードクォータにカウントされます。

認証: APIキーまたはJWTリクエスト: noneレスポンス: video/mp4

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/download/video" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

video/mp4 を添付ファイルとして返します。クォータは、ストリーミングが成功した場合にのみ消費されます。

パラメータ

id必須

string · path

文字起こしID。

成功時のレスポンス

{
  "note": "Binary video/mp4 attachment."
}

エラー

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

AIエージェント

文字起こしに対してフック分析、台本の書き換え、バズ度スコアリングを実行します。（Pro）

POST/api/v1/agents/{agentType}

AIエージェントを実行

Proagent の上限

完了した文字起こしに対してAI分析をキューに追加します。agentType は hooks、script_rewrite、virality_explain、hook_score のいずれかです。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/agents/hooks" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2","input":{}}'

ボディのフィールド

`transcript_id`必須 string	分析対象となる完了済みの文字起こし。
`input` object	任意。エージェント固有のパラメータ。

パラメータ

agentType必須

string · path

hooks | script_rewrite | virality_explain | hook_score。

成功時のレスポンス · HTTP 202

{
  "run_id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "queued"
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

エージェント実行の一覧

エージェント実行を新しい順に一覧表示します。カーソルによるページネーションに対応しています。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/agents/runs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

パラメータ

`cursor` string (ISO date) · query	前のページに戻るには next_cursor を渡してください。
`limit` integer · query	1ページあたりの件数（1〜50）。デフォルトは20です。

成功時のレスポンス

{
  "runs": [
    {
      "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "status": "completed",
      "agent_type": "hooks",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "created_at": "2026-06-23T10:05:00.000Z"
    }
  ],
  "next_cursor": null
}

エラー

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/agents/runs/{runId}

エージェント実行を取得

1件のエージェント実行を取得します。完了後は構造化された出力も含まれます。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/agents/runs/a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

パラメータ

runId必須

string · path

エージェント実行ID。

成功時のレスポンス

{
  "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "agent_type": "hooks",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "output": {
    "hooks": [
      "The first 3 seconds promise a payoff..."
    ]
  },
  "output_text": "The first 3 seconds promise a payoff...",
  "model": "claude-...",
  "completed_at": "2026-06-23T10:05:09.000Z"
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

抽出 & 翻訳

低レベルのプリミティブ機能です。メタデータの取得、テキストの翻訳、貼り付けた入力の分類を行えます。

POST/api/v1/extract/metadata

メタデータをスクレイピング

ジョブを作成せずに、TikTok URL をメタデータと利用可能な最適な字幕トラックに解決します。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/extract/metadata" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@creator/video/1234567890"}'

ボディのフィールド

`url`必須 string	TikTok動画のURL。
`output_language` string	優先する字幕言語。デフォルトは en です。

成功時のレスポンス

{
  "normalized_url": "https://www.tiktok.com/@creator/video/1234567890",
  "source_language": "en",
  "selected_track_type": "creator",
  "subtitle_format": "webvtt",
  "metadata": {
    "author_username": "creator",
    "duration_seconds": 29
  }
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

テキストを翻訳

文字起こしのテキストやタイムスタンプ付きセグメントを、1つ以上の言語に翻訳します。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/extract/translate" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_text":"Whenever I'm asked to teach a beginner how to cook...","output_language":"es"}'

ボディのフィールド

`full_text` string	翻訳するテキスト。これまたは segments のいずれか（または両方）を指定してください。
`segments` TranscriptSegment[]	タイミングを保持したまま翻訳するタイムスタンプ付きセグメント。
`output_language` string	主要な翻訳先言語。デフォルトは en です。
`additional_languages` string[]	追加の翻訳先言語。

成功時のレスポンス

{
  "fullText": "Cada vez que me piden que enseñe a un principiante a cocinar...",
  "segments": [],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  }
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

貼り付けた入力を解決

貼り付けられたテキスト、@ハンドル、URLを、動画URL、コレクションのプレビュー、またはプロフィールのプレビューに分類します。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/workspace/resolve" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"@foodnetwork"}'

ボディのフィールド

`text` string	貼り付けられた生の入力内容。これか urls のいずれかを指定してください。
`urls` string[]	明示的なURLリスト。

成功時のレスポンス

{
  "kind": "profile",
  "profile": {
    "username": "foodnetwork",
    "video_count": 1200
  }
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

フォルダー

文字起こしをフォルダーで整理します。

GET/api/v1/folders

フォルダーの一覧

フォルダーを項目数とともに一覧表示します。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

成功時のレスポンス

{
  "folders": [
    {
      "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Cooking hooks",
      "created_at": "2026-06-23T10:00:00.000Z",
      "item_count": 12
    }
  ]
}

エラー

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

フォルダを作成

文字起こしをまとめるフォルダを作成します。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cooking hooks"}'

ボディのフィールド

name必須

string

フォルダー名。

成功時のレスポンス · HTTP 201

{
  "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Cooking hooks",
  "created_at": "2026-06-23T10:00:00.000Z"
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

POST/api/v1/folders/{folderId}/items

文字起こしをフォルダに追加

文字起こしをフォルダに追加します（冪等）。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/folders/f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d/items" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2"}'

ボディのフィールド

transcript_id必須

string

追加する文字起こし。

パラメータ

folderId必須

string · path

対象フォルダの ID。

成功時のレスポンス · HTTP 201

{
  "added": true
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

アカウント、キー、請求

APIキーの管理、プランと利用枠の確認、フィードバックの送信を行います。

POST/api/v1/api-keys

APIキーを作成

Pro

ライブAPIキーを生成します。キー全体は一度だけ表示されるので、安全に保管してください。Proプラン限定です。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production server"}'

ボディのフィールド

name必須

string

キーを識別するためのラベル。

成功時のレスポンス · HTTP 201

{
  "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Production server",
  "key_prefix": "tok_live_a1b2c3",
  "key": "tok_live_a1b2c3_d4e5f6g7h8i9j0k1l2m3n4o5",
  "created_at": "2026-06-23T10:00:00.000Z",
  "warning": "Save this key now — it will not be shown again."
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

APIキーの一覧

Pro

有効なキーをプレフィックスで一覧表示します（シークレットは返されません）。Proプラン限定です。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

成功時のレスポンス

{
  "keys": [
    {
      "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Production server",
      "key_prefix": "tok_live_a1b2c3",
      "last_used_at": "2026-06-23T10:30:00.000Z",
      "created_at": "2026-06-23T10:00:00.000Z",
      "revoked_at": null
    }
  ]
}

エラー

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

プランの一覧

有効なプランとその上限の一覧を公開しています。認証は不要です。

認証: 公開（認証不要）リクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/plans"

成功時のレスポンス

{
  "plans": [
    {
      "id": "free",
      "price_cents": 0,
      "billing_interval": "none",
      "free_daily_limit": 5,
      "agents_enabled": false,
      "downloads_enabled": false,
      "features": [
        "5 transcripts per day",
        "TXT & SRT export"
      ]
    },
    {
      "id": "pro_monthly",
      "price_cents": 900,
      "billing_interval": "month",
      "agents_enabled": true,
      "downloads_enabled": true,
      "features": [
        "Unlimited transcripts",
        "30 AI agent runs / month",
        "API access"
      ]
    }
  ]
}

エラー

INTERNAL_ERROR500

GET/api/v1/billing/subscription

サブスクリプションとクォータ

現在のプラン、サブスクリプションの状態、および文字起こし、エージェント、ダウンロード、翻訳にわたるリアルタイムの利用状況と上限。

認証: APIキーまたはJWTリクエスト: noneレスポンス: application/json

curl -X GET "https://www.tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

成功時のレスポンス

{
  "plan": {
    "id": "free",
    "price_cents": 0,
    "billing_interval": "none"
  },
  "subscription_status": null,
  "quota": {
    "transcripts": {
      "window": "daily",
      "limit": 5,
      "used": 2,
      "remaining": 3,
      "is_unlimited": false,
      "reset_at": "2026-06-24T00:00:00.000Z"
    },
    "agents": {
      "enabled": false,
      "limit": 0,
      "used": 0,
      "remaining": 0
    }
  }
}

エラー

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

フィードバックを送信

製品へのフィードバック、バグ報告、機能リクエストを送信します。

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/feedback" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"feature","rating":5,"message":"Add a Zapier integration please!"}'

ボディのフィールド

`category`必須 string	bug \| feature \| improvement \| other。
`message`必須 string	最大2000文字まで。
`rating` integer \| null	任意。1〜5の評価。

成功時のレスポンス

{
  "success": true
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…

POST/api/v1/jobs

文字起こしジョブを送信

submit の上限

認証: APIキーまたはJWTリクエスト: application/jsonレスポンス: application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en","also_translate_to":["es"],"allow_asr_fallback":false,"include_download_assets":false,"idempotency_key":"client-req-001"}'

単一のURLでも、処理がインラインで完了した場合はHTTP 200で completed または failed の終了ペイロードが返されることがあります。
バッチはHTTP 202を返し、job_id、全体のステータス、itemsの中に各項目のステータスを含みます。
items配列で各動画のステータス（queued、processing、completed、failed）を確認してください。
無料プランで include_download_assets: true を設定すると、PLAN_REQUIRED（403）が返されます。

ボディのフィールド

`urls`必須 string[]	TikTokの動画URL。無料プランの一括上限は5件です。
`output_language` string	対象の文字起こし言語（ISO コード）。デフォルトは en です。
`also_translate_to` string[]	文字起こしを翻訳する追加の言語。
`allow_asr_fallback` boolean	字幕トラックがない場合に音声を文字起こしします。デフォルトはfalseです。
`include_download_assets` boolean	ダウンロード用に動画・カバー画像のアセットを保存します。Proプラン限定。
`idempotency_key` string	重複排除キー。同じキーを再利用すると元のジョブが返されます。

成功時のレスポンス · HTTP 202

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "queued",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

即時の単一成功

HTTP 200

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "total_items": 1,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_single_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "selected_track_type": "creator",
      "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
      "metadata": {
        "author_username": "foodnetwork",
        "duration_seconds": 29
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

失敗（字幕なし）

HTTP 200

{
  "job_id": "8a0d6d7a-78f0-4ab0-8a8c-72f8f5184de8",
  "status": "failed",
  "total_items": 1,
  "completed": 0,
  "failed": 1,
  "items": [
    {
      "id": "tx_single_2",
      "transcript_id": "d40b2545-7c62-4bbb-a7e3-020c663f18a0",
      "item_index": 0,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

エラー

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503