API Documentation | TokCaption

API v2.1

TokCaption Public API

Submit TikTok URLs for transcription and poll job status. JWT or API key auth. Two endpoints, clean JSON.

Base URL/api/v1

AuthBearer JWT | X-API-Key

Endpoints2 public

Integration Flow

Step 1

Submit transcription job

Call POST /api/v1/jobs and 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).
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..50 TikTok URLs for transcription.

Auth: JWT or API Key

Request: application/json

Response: application/json

Request Example

{
  "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": true,
  "include_download_assets": false,
  "idempotency_key": "client-req-001"
}

Success Example

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

Error Codes

AUTH_REQUIREDHTTP 401VALIDATION_ERRORHTTP 400QUOTA_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

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

Error Codes

AUTH_REQUIREDHTTP 401VALIDATION_ERRORHTTP 400NOT_FOUNDHTTP 404INTERNAL_ERRORHTTP 500

Loading API documentation…

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).

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.

{ "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": true, "include_download_assets": false, "idempotency_key": "client-req-001" }

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

Name

Type

Required

Description

jobId(path)

string

yes

Job ID returned by POST /api/v1/jobs.

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