API 1.0

Clipcat API Reference

Clipcat is a video rendering service.

  1. Your designer creates a video template in Clipcat
  2. We turn it into an API
  3. You use this API to generate renders of the video template
Base URL
https://api.clipcat.com

Authentication

Clipcat uses API keys to allow access to the API.

Clipcat expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer API_KEY

You can find your workspace API Keys in API Keys ↗.

All API requests on Clipcat are scoped to a Workspace.

Endpoint
get/v1/auth
Sample Response
{
  "message": "Authorized",
  "workspace": "My Workspace"
}

Account

To check your account status at any time you can use this endpoint. It will respond with your quota levels and current usage levels. Usage resets at the start of every month.

Endpoint
get/v1/account
Sample Response
{
  "created_at": "2022-12-01T03:48:23.228Z",
  "uid": "x4p71qmnY1nD5obLdG",
  "plan_name": "Clipcat Scale",
  "quota": {
    "max": 10000,
    "current": 20
  }
}

Errors

The Clipcat API uses the following status / error codes. The Clipcat API rate limit is 30 requests per 10 seconds.

202Accepted -- Your request is has been accepted for processing
200OK
400Bad Request -- Your request is invalid.
401Unauthorized -- Your API key is wrong.
402Payment Required -- Your have run out of quota.
404Not Found -- The specified request could not be found.
429Too Many Requests -- Slow down!
500Internal Server Error -- We had a problem with our server. Try again later.
503Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Async

The Clipcat API is asynchronous. When creating a new run, you POST a request, the API responds immediately with 202 Accepted and you either receive the generated result via webhook or via polling.

You can send as many render requests as you want within the Rate Limit.

Render requests will be held in a queue depending on your plan's concurrency level.

Renders

Renders are the main resource on Clipcat.

You generate videos by sending a POST request with a template uid and a list of template modifications you want to apply. These modifications can be things like: changing the text, changing the images or changing the colors.

Clipcat will render the video in MP4 format.

Endpoints
post/v1/renders
get/v1/renders/:uid
get/v1/renders

The render object

Attributes

  • uid stringThe unique ID for this object.
  • self stringThe permalink to this object.
  • status stringThe current status of the render; queued, rendering, completed or failed.
  • url integerThe final, rendered video url. This will be null to begin with and populates when the render has the status completed
  • webhook_response_code integerThe HTTP response code received by the webhook_url.
Sample Object
{
  "created_at": "2024-12-12T12:21:55.936Z",
  "uid": "mQqK6lZJw9XVrN0a7G",
  "self": "https://api.clipcat.com/v1/renders/mQqK6lZJw9XVrN0a7G"
  "status": "completed",
  "template": "rZYyExAwA2KzW42bVG"
  "url": "https://clipcat-media-local.s3.us-east-1.amazonaws.com/renders/xOv902dD4mVwPWjZGN/final/9600249b11153f703ce969029e486dd830c73d66.mp4",
  "modifications": [
    {
      "scene": "Scene 1",
      "background-image": "https://cdn.clipcat.com/assets/test_data/photography/barcelona-345efddb03cb628590e0e3a180b9b61d264a6e7756e5a11264da9112482207a9.jpg",
      "object": "_md3ma3"
    },
    {
      "scene": "Scene 1",
      "text": "Hello World",
      "object": "_ej2891"
    },
    {
      "scene": "Scene 2",
      "media_url": "https://www.bannerbear.com/video/portrait_short.mov"
    }
  ],
  "metadata": null,
  "webhook_url": null,
  "credits": 12,
  "progress": 100
}

Create a render

Parameters

  • modifications listrequiredA list of modifications you want to make.
    • Child Parameters
    • scene string requiredThe scene name or id you want to change.
    • object string The name or id of the object you want to change.
    • media_url string Background video url for video scenes.
    • Object Attributes
    • text stringReplacement text you want to use.
    • color stringChange the text color in hex format e.g. "#FF0000".
    • font-family stringChange the font.
    • background-image stringChange the object background image.
    • background-color stringBackground color in hex format e.g. "#FF0000".
    • border-color stringBorder color in hex format e.g. "#FF0000".
    • border-width integerBorder thickness in pixels.
  • webhook_url stringA url to POST the full Render object to upon finishing.
  • metadata stringAny metadata you need to store e.g. ID of a record in your DB.
post/v1/renders
Sample Request
//change the text
var data = {
  "modifications": [
    {
      "scene": "Scene 1",
      "object": "_ej2891",
      "text": "This is some different text"
    }
  ]
}
fetch('https://api.clipcat.com/v1/renders', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'Authorization' : `Bearer ${API_KEY}`
  }
})

Retrieve a render

Parameters

  • uid stringrequiredThe render uid that you want to retrieve.
get/v1/renders/:uid
Sample Request
fetch(`https://api.clipcat.com/v1/renders/${UID}`, {
  method: 'GET',
  headers: {
    'Authorization' : `Bearer ${API_KEY}`
  }
})

List all renders

Parameters

  • page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get/v1/renders
Sample Request
fetch(`https://api.clipcat.com/v1/renders`, {
  method: 'GET',
  headers: {
    'Authorization' : `Bearer ${API_KEY}`
  }
})

Templates

Templates are the reusable video designs that you create in the Clipcat editor. You can list templates via the API.

You can design a template using the Clipcat template editor, or you can add one from the template library (and modify it as needed).

Every template has a list of modifications available, for example text boxes that you can populate with different text, or image placeholders that you can replace with different images.

Endpoints
get/v1/templates/:uid
get/v1/templates

The template object

Attributes

  • uid stringThe unique ID for this object.
  • self stringThe permalink to this object.
  • frame_rate integerThe FPS / frame rate setting of the template.
  • scenes arrayA list of the template's scenes with their available modifications.
  • type stringThe template type, either video or graphic.
Sample Object
{
  "created_at": "2024-11-27T04:42:34.488Z",
  "uid": "JYd3MWVoBXnwbAnjOE",
  "self": "http://api.clipcat.com/v1/templates/JYd3MWVoBXnwbAnjOE",
  "title": "My Template",
  "width": 800,
  "height": 800,
  "frame_rate": 60,
  "scenes": [
    {
      "title": "Intro",
      "uid": "2LGoRa1wr2WwvlJAmq",
      "available_modifications": [
        {
          "object": "Big Red Text",
          "text": null,
          "color": null,
          "font-family": null,
          "font-size": null
        },
        {
          "object": "_9kxtg5",
          "background-image": null,
          "background-color": null,
          "border-color": null,
          "border-width": null
        },
        {
          "object": "_ehsyxl",
          "background-color": null,
          "border-color": null,
          "border-width": null
        }
      ],
      "type": "graphic"
    },
    {
      "title": "Main Scene",
      "uid": "gay3rl09Gkk9Ab4xMG",
      "media_url": "https://www.bannerbear.com/video/portrait_short.mov",
      "available_modifications": [
        {
          "object": "Square 2",
          "background-color": null,
          "border-color": null,
          "border-width": null
        },
        {
          "object": "Square 1",
          "background-color": null,
          "border-color": null,
          "border-width": null
        }
      ],
      "type": "video"
    }
  ]
}

Retrieve a template

Parameters

  • uid stringrequiredThe template uid.
get/v1/templates/:uid
Sample Request
fetch(`https://api.clipcat.com/v1/templates/${UID}`, {
  method: 'GET',
  headers: {
    'Authorization' : `Bearer ${API_KEY}`
  }
})

List all templates

Parameters

  • page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get/v1/templates
Sample Request
fetch(`https://api.clipcat.com/v1/templates`, {
  method: 'GET',
  headers: {
    'Authorization' : `Bearer ${API_KEY}`
  }
})