Caption Cat API Reference

The Caption Cat API allows you to upload videos, generate transcripts, edit subtitles, and render captioned videos programmatically.

Base URL: https://api.captioncat.net/v1

Contents

Authentication

This API uses Bearer Token authentication via the `Authorization` header.

Include your token with every request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Tokens can be generated and rotated in the settings menu

Endpoints

GET /balance

Retrieves current balance

Successful Response


{
  "status": "success",
  "balance": 6012
}

Example


curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.captioncat.net/v1/balance

GET /balance/history

Retrieves balance history

Successful Response


{
  "status": "success",
  "balance_history": [
    {
      "Id": 1,
      "Transaction": 2400,
      "Balance": 2400,
      "Description": "Deposit 2400 credits",
      "DateTime": "2026-03-07 10:04:58 CET"
    },
    {
      "Id": 2,
      "Transaction": -59,
      "Balance": 2341,
      "Description": "Transcribe Video",
      "DateTime": "2026-03-07 10:22:15 CET"
    },
    {
      "Id": 3,
      "Transaction": -59,
      "Balance": 2282,
      "Description": "Render Video",
      "DateTime": "2026-03-07 10:34:23 CET"
    }
  ]
}

Example


curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.captioncat.net/v1/balance/history

POST /upload

Uploads a video

Request Body (Multipart Form)

Name Type Required Description
video file Yes Video file to upload (mp4, mkv, avi, mov, wmv, flv, webm, mpeg, qt)

Successful Response (200 OK)

Returns a video id


{
  "status": "success",
  "id": "cb6dc793fa1ceadb55744ba0a7b0af56",
}

Unsuccessful Response (415 Unsupported Media Type)


{
  "status": "error",
  "msg": "uploaded file is not a video"
}

Example


curl -X POST https://api.captioncat.net/v1/upload \
	-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
	-F "video=@video.mp4"

POST /transcribe/{id}

Starts transcription of video

Path Parameters

Name Type Description
id string Video identifier returned by the upload endpoint

Successful Response (200 OK)


{
  "status": "success",
}

Example


curl -X POST https://api.captioncat.net/v1/transcribe/cb6dc793fa1ceadb55744ba0a7b0af56 \
	 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET /transcribe/{id}/poll

Retrieves status of transcription

Possible values:

Successful Response (200 OK)


{
  "status": "success",
  "transcription": "finished",
}

Example


curl https://api.captioncat.net/v1/transcribe/cb6dc793fa1ceadb55744ba0a7b0af56/poll \
	 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET /transcript/{id}/srt

Retrieves the transcription in srt format

Successful Response (200 OK)


{
  "status": "success",
  "srt": "1\n00:00:01,000 --> 00:00:12,720\nWelcome to Caption Cat!\n\n"
}

Example


curl https://api.captioncat.net/v1/transcript/cb6dc793fa1ceadb55744ba0a7b0af56/srt \
	 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET /transcript/{id}/text

Retrieves the transcription

Successful Response (200 OK)


{
  "status": "success",
  "text": "Welcome to Caption Cat!"
}

Example


curl https://api.captioncat.net/v1/transcript/cb6dc793fa1ceadb55744ba0a7b0af56/text \
	 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

PATCH /transcript/{id}/srt

Updates the srt transcript

Request Body (Form URL Encoded)

Name Type Required Description
srt string Yes Srt Transcript

Successful Response (200 OK)

Returns the status of changed fields


{
  "status": "success",
}

POST /render/{id}

Starts rendering of video

Successful Response (200 OK)


{
  "status": "success",
}

Example


curl -X POST https://api.captioncat.net/v1/render/cb6dc793fa1ceadb55744ba0a7b0af56 \
	 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET /render/{id}/poll

Retrieves rendering progress of video in percent

Successful Response (200 OK)


{
  "status": "success",
  "progress": 75
}

Example


curl https://api.captioncat.net/v1/render/cb6dc793fa1ceadb55744ba0a7b0af56/poll \
	 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Error Responses

The API uses standard HTTP status codes for errors.

Status Code Description Error Body Example
401 Unauthorized The request lacks valid authentication credentials. {"error": "Invalid or missing token"}
404 Not Found The requested resource could not be found. {"error": "Id Not Found"}
400 Bad Request The request was improperly formed (e.g., missing required fields). {"error": "Missing required field: name"}