개발자 문서

TokCaption API 문서

공개 틱톡 영상을 텍스트로 추출하고, AI 후킹 분석과 대본 리라이트를 실행하며, 대규모로 텍스트 추출본을 내보낼 수 있는 REST API입니다. API 키로 인증하고, URL을 제출한 뒤 결과를 폴링하세요. API 액세스는 Pro 플랜에서 이용할 수 있습니다.

REST API · v2.1.0

TokCaption API

공개 틱톡 영상을 텍스트로 추출하고, AI 후킹 분석을 실행하고, 대규모로 내보내기까지—모두 깔끔한 JSON REST API로 가능합니다. API 키로 인증하면 단 두 번의 호출로 바로 시작할 수 있습니다. AI 어시스턴트를 선호하시나요? 같은 도구를 Claude와 ChatGPT용 MCP 서버로도 이용할 수 있습니다.

기본 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 하나만 처리하고 상태를 반복 확인하고 싶지 않다면 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	요청 본문, 쿼리 매개변수 또는 경로가 잘못되었습니다. 메시지와 세부 정보에서 수정 방법을 확인하세요.
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	틱톡에서 요청을 일시적으로 차단했거나 속도를 제한했습니다. 잠시 후 다시 시도하세요.
SEGMENTS_UNAVAILABLE	400	이 내보내기 형식(srt/vtt)에는 타임스탬프가 있는 세그먼트가 필요하지만, 이 텍스트 추출본에는 세그먼트가 없습니다.
INTERNAL_ERROR	500	예기치 않은 서버 오류가 발생했습니다. 다시 시도하고, 문제가 계속되면 고객 지원팀에 문의하세요.

텍스트 추출

공개 틱톡 URL을 텍스트 추출용으로 제출하고 작업 진행 상황을 확인하세요.

POST/api/v1/jobs

텍스트 추출 작업 제출

submit 한도

공개 틱톡 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 배열에서 영상별 상태(대기 중, 처리 중, 완료, 실패)를 확인하세요.
무료 플랜에서 include_download_assets: true를 설정하면 PLAN_REQUIRED(403)가 반환됩니다.

본문 필드

`urls`필수 string[]	틱톡 영상 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~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초간 기다리세요. 작업 기반 방식의 동기식 단축 방법입니다.

인증: 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

틱톡 영상 URL 하나입니다.

성공 응답

{
  "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	자유 텍스트입니다. 틱톡 링크는 자동으로 추출됩니다.
`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~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로 단일 텍스트 추출본을 가져옵니다. 전체 텍스트, 세그먼트, 번역본, 메타데이터, 에셋이 포함됩니다.

인증: 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

텍스트 추출본 내보내기

텍스트 추출본 하나를 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

원본 틱톡 영상을 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~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}

에이전트 실행 가져오기

AI 에이전트 실행 한 건을 가져옵니다. 완료되면 구조화된 출력도 포함됩니다.

인증: 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

메타데이터 스크레이핑

작업을 생성하지 않고 틱톡 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	틱톡 영상 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

텍스트 번역

텍스트 추출본의 텍스트 및/또는 타임스탬프 세그먼트를 하나 이상의 언어로 번역합니다.

인증: 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 배열에서 영상별 상태(대기 중, 처리 중, 완료, 실패)를 확인하세요.
무료 플랜에서 include_download_assets: true를 설정하면 PLAN_REQUIRED(403)가 반환됩니다.

본문 필드

`urls`필수 string[]	틱톡 영상 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