Public API

TokCaption API Documentation

Use the TokCaption API to submit TikTok transcription jobs, poll their status, and build creator workflows around transcript extraction, AI analysis, and exports. API access is available on paid plans. This page exposes the public reference content in server-rendered HTML and keeps the interactive explorer below for implementation details.

Authentication

Authenticate with a Supabase JWT in the Authorization header or with a live API key in X-API-Key.

Base Path

/api/v1

The public reference currently covers the transcription submit and job polling flows.

Available endpoints

POST/api/v1/jobs

Transcribe Submit

Submit 1..N TikTok video URLs for transcription. Batch size depends on plan, and single submits may return a terminal result immediately.

GET/api/v1/jobs/{jobId}

Polling Job Status

Poll a submitted transcription job until terminal state.

API v2.1

TokCaption Public API

Submit TikTok video URLs for transcription with JWT or API key auth. Single requests can finish inline; multi-item jobs are polled through the same clean JSON contract.

Base URL

/api/v1

Auth

Bearer JWT | X-API-Key

Endpoints

2 public

Rate limits

Submit and polling endpoints are rate-limited per minute in addition to plan quotas. If you exceed the request rate, the API returnsHTTP 429witherror.code = RATE_LIMIT_EXCEEDEDandretry_after_seconds.

Integration Flow

Step 1

Submit transcription job

Call POST /api/v1/jobs. If the response is already terminal, you can use it immediately; otherwise store the returned job_id.

Step 2

Poll job status

Call GET /api/v1/jobs/{jobId} until terminal status.

Error Contract

All errors return a JSON envelope. Use error.code for programmatic handling.

Error Response Envelope

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Free plan allows 5 transcripts/day.",
    "details": {
      "daily_limit": 5
    }
  }
}

All Error Codes

Code	HTTP	Meaning
AUTH_REQUIRED	401	Missing or invalid JWT/API key. Include Authorization header or X-API-Key.
VALIDATION_ERROR	400	Invalid request body, query params, or path. Check the message for details.
NOT_FOUND	404	Job, transcript, or resource not found or not accessible.
QUOTA_EXCEEDED	429	Transcript or agent quota limit reached. Resets daily (free) or monthly (Pro).
RATE_LIMIT_EXCEEDED	429	Too many submit, poll, or agent requests in a short window. Respect retry_after_seconds before retrying.
PLAN_REQUIRED	403	Feature requires a Pro plan. Upgrade to unlock.
DUPLICATE_REQUEST	409	Duplicate idempotency key. Request already processed.
INTERNAL_ERROR	500	Unexpected server error. Retry or contact support.

Endpoints

POST/api/v1/jobs

Transcribe Submit

Summary: Submit 1..N TikTok video URLs for transcription. Batch size depends on plan, and single submits may return a terminal result immediately.

Auth: JWT or API Key

Request: application/json

Response: application/json

Response Behavior

Single-video requests can return HTTP 200 with a terminal completed or failed payload when processing finishes inline.

Multi-item requests return HTTP 202 with job_id, overall status, and per-item statuses inside items.

The items array is where you inspect per-video status such as queued, processing, completed, failed, or no-captions failures.

Submit requests are also rate-limited per minute. On throttle, the API returns HTTP 429 with error.code = RATE_LIMIT_EXCEEDED and retry_after_seconds.

Request Example

{
  "urls": [
    "https://www.tiktok.com/@creator/video/1234567890",
    "https://www.tiktok.com/@creator/video/0987654321"
  ],
  "output_language": "en",
  "also_translate_to": [
    "es"
  ],
  "include_download_assets": false,
  "idempotency_key": "client-req-001"
}

Success Example

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

Example Responses

Accepted batch response

HTTP 202

Accepted batch response payload

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "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"
    },
    {
      "id": "tx_2",
      "transcript_id": "2448b6b8-7e07-46ef-96be-1f339abdb71f",
      "item_index": 1,
      "input_url": "https://www.tiktok.com/@creator/video/0987654321",
      "status": "processing"
    }
  ]
}

Immediate single success

HTTP 200

Immediate single success payload

{
  "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": 299
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

Immediate single failure

HTTP 200

Immediate single failure payload

{
  "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."
    }
  ]
}

Error Codes

AUTH_REQUIREDHTTP 401VALIDATION_ERRORHTTP 400QUOTA_EXCEEDEDHTTP 429RATE_LIMIT_EXCEEDEDHTTP 429DUPLICATE_REQUESTHTTP 409INTERNAL_ERRORHTTP 500

GET/api/v1/jobs/{jobId}

Polling Job Status

Summary: Poll a submitted transcription job until terminal state.

Auth: JWT or API Key

Request: none

Response: application/json

Response Behavior

Use the job_id returned by POST /api/v1/jobs.

Polling returns the current aggregate job status plus per-item statuses in items.

Terminal job states are completed or failed; item statuses may still be mixed inside the same job.

Polling is rate-limited too. Use a sensible interval such as every 1-2 seconds and honor retry_after_seconds on HTTP 429.

Params

Name	Type	Required	Description
jobId(path)	string	yes	Job ID returned by POST /api/v1/jobs.

Success Example

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "total_items": 2,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_1",
      "item_index": 0,
      "status": "completed"
    },
    {
      "id": "tx_2",
      "item_index": 1,
      "status": "processing"
    }
  ]
}

Example Responses

Polling while still processing

HTTP 200

Polling while still processing payload

{
  "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",
      "completed_at": "2026-03-14T08:33:14.000Z"
    },
    {
      "id": "tx_2",
      "transcript_id": "2448b6b8-7e07-46ef-96be-1f339abdb71f",
      "item_index": 1,
      "status": "processing"
    }
  ]
}

Polling after mixed completion

HTTP 200

Polling after mixed completion payload

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "partial",
  "total_items": 2,
  "completed": 1,
  "failed": 1,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "completed_at": "2026-03-14T08:33:14.000Z"
    },
    {
      "id": "tx_2",
      "transcript_id": "2448b6b8-7e07-46ef-96be-1f339abdb71f",
      "item_index": 1,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

Error Codes

AUTH_REQUIREDHTTP 401VALIDATION_ERRORHTTP 400NOT_FOUNDHTTP 404RATE_LIMIT_EXCEEDEDHTTP 429INTERNAL_ERRORHTTP 500

Loading API documentation…

POST/api/v1/jobs

Transcribe Submit

Summary: Submit 1..N TikTok video URLs for transcription. Batch size depends on plan, and single submits may return a terminal result immediately.

Auth: JWT or API Key

Request: application/json

Response: application/json

Response Behavior

Single-video requests can return HTTP 200 with a terminal completed or failed payload when processing finishes inline.

Multi-item requests return HTTP 202 with job_id, overall status, and per-item statuses inside items.

The items array is where you inspect per-video status such as queued, processing, completed, failed, or no-captions failures.

Submit requests are also rate-limited per minute. On throttle, the API returns HTTP 429 with error.code = RATE_LIMIT_EXCEEDED and retry_after_seconds.

Request Example

{
  "urls": [
    "https://www.tiktok.com/@creator/video/1234567890",
    "https://www.tiktok.com/@creator/video/0987654321"
  ],
  "output_language": "en",
  "also_translate_to": [
    "es"
  ],
  "include_download_assets": false,
  "idempotency_key": "client-req-001"
}

Success Example

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

Example Responses

Accepted batch response

HTTP 202

Accepted batch response payload

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "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"
    },
    {
      "id": "tx_2",
      "transcript_id": "2448b6b8-7e07-46ef-96be-1f339abdb71f",
      "item_index": 1,
      "input_url": "https://www.tiktok.com/@creator/video/0987654321",
      "status": "processing"
    }
  ]
}

Immediate single success

HTTP 200

Immediate single success payload

{
  "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": 299
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

Immediate single failure

HTTP 200

Immediate single failure payload

{
  "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."
    }
  ]
}

Error Codes

AUTH_REQUIREDHTTP 401VALIDATION_ERRORHTTP 400QUOTA_EXCEEDEDHTTP 429RATE_LIMIT_EXCEEDEDHTTP 429DUPLICATE_REQUESTHTTP 409INTERNAL_ERRORHTTP 500