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

POST /upload

Uploads a video and creates a new project.
Projects are limited to 10 videos. Once the limit is reached, the oldest videos are deleted as new ones are added.

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",
  "message": "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"

GET /transcribe/{id}/cost

Retrieves cost of transcription in credits

Successful Response (200 OK)


{
  "status": "success",
  "transcription_cost": 87,
}

Example


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

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"

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

Example


curl -X PATCH https://api.captioncat.net/v1/transcript/cb6dc793fa1ceadb55744ba0a7b0af56/srt \
	 -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
	 -d "srt=your+corrected+srt+content"

GET /render/{id}/cost

Retrieves cost of rendering in credits

Successful Response (200 OK)


{
  "status": "success",
  "rendering_cost": 1252,
  "resolution": "3840x2160",
  "message": "4K"
}

Example


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

POST /render/{id}

Starts rendering of video

JSON Body (Raw)

If no body is sent, then the style options shown below are used as default.

Name Type Required Description
fontFamily string Yes One of: "DejaVu Sans", "Roboto", "Orbitron", "Pacifico", "UnifrakturMaguntia", "Noto Sans Japanese", "Noto Sans Korean"
fontSize integer Yes Value between 10 and 50
fontColor string Yes RGB Color in Hex
outlineColor string Yes RGB Color in Hex or none for transparent color
bgColor string Yes RGB Color in Hex or none for transparent color
bgOpacity integer Yes Background color opacity in percent. 100 = fully visible. 0 = fully transparent 

{
  "style": {
    "fontFamily": "DejaVu Sans",
    "fontSize": 12,
    "fontColor": "#ffffff",
    "outlineColor": "none",
    "bgColor": "#000000",
    "bgOpacity": 75
  }
}

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"

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

GET /project

Retrieves the list of projects

Successful Response


{
  "status": "success",
  "projects": [
    {
      "id": "09023cf9ac65815563707b006c3046a8",
      "created": "2026-06-14 14:44:14 UTC"
    },
    {
      "id": "0ec5e711547756c12d1129c7f63a24a3",
      "created": "2026-06-14 19:13:32 UTC"
    },
    {
      "id": "47c71b4e19aeb9a5fc78bc91939c43f3",
      "created": "2026-06-14 20:03:28 UTC"
    }
  ]
}

Example


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

GET /project/{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/project/cb6dc793fa1ceadb55744ba0a7b0af56/srt \
	 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET /project/{id}/text

Retrieves the transcription as plain text

Successful Response (200 OK)


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

Example


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

GET /project/{id}/video

Retrieves the download link of the rendered video

Successful Response (200 OK)


{
  "status": "success",
  "video": "https://captioncat.net/download/cb6dc793fa1ceadb55744ba0a7b0af56.mp4"
}

Example


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

DELETE /project/{id}

Deletes the project and all associated files

Successful Response (200 OK)


{
  "status": "success",
  "message": "project cb6dc793fa1ceadb55744ba0a7b0af56 has been deleted"
}

Example


curl -X DELETE https://api.captioncat.net/v1/project/cb6dc793fa1ceadb55744ba0a7b0af56/video \
	 -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"}