{
  "openapi": "3.1.0",
  "info": {
    "title": "TallClip API",
    "version": "1.0.0",
    "description": "Make finished vertical short videos (YouTube Shorts, TikTok, Reels) from one topic: script, AI voiceover, matched footage or AI pictures, captions and music. Each video is paid in TallClip credits from the key owner's account. API keys come with the Silver plan and up; make one at https://tallclip.com/developers. Rendering takes a few minutes: POST a video, then poll it until status is \"done\".",
    "contact": {
      "url": "https://tallclip.com/contact"
    },
    "termsOfService": "https://tallclip.com/terms"
  },
  "externalDocs": {
    "description": "Guide with examples",
    "url": "https://tallclip.com/developers"
  },
  "servers": [
    {
      "url": "https://tallclip.com/api/v1"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "paths": {
    "/videos": {
      "post": {
        "operationId": "createVideo",
        "summary": "Make a video from a topic",
        "description": "Charges the video's credits up front (any difference is given back once the script is known) and answers at once with 202. Limits per key: 20 videos an hour, 100 a day; 5 being written at once per account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VideoRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted - poll statusUrl",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Accepted"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request - the message says which field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized - missing or invalid key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits - includes balance and needed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "plan_required, plan_blocked or account_on_hold",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "real_person_not_allowed - the topic asks for something never made about a real person (sexual or degrading, a fake endorsement, a made-up claim told as true); may include `suggestion`, an acceptable version. Nothing was charged",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited or too_many_in_flight",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "try_again - nothing was charged",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listVideos",
        "summary": "The 20 newest API videos, or one with ?id=",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Videos",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "videos": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Video"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/Video"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/videos/{id}": {
      "get": {
        "operationId": "getVideo",
        "summary": "Where a video has got to; videoUrl once it's done",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The video",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Video"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/library": {
      "get": {
        "operationId": "searchLibrary",
        "summary": "Search the public library of AI pictures, moving AI clips and registered creators' uploads",
        "description": "Free - nothing is charged. Only items that may go in anyone's video come back. Each url is a preview link that lasts six days; credits is one use in a TallClip video on the lowest plan.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 80
            },
            "description": "What it shows, e.g. rainy city street at night"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "picture",
                "clip"
              ],
              "default": "all"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 40,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matches",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "pageSize": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "picture",
                              "clip"
                            ]
                          },
                          "upload": {
                            "type": "boolean",
                            "description": "A registered creator's own upload rather than TallClip AI"
                          },
                          "title": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "width": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "height": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "seconds": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "uses": {
                            "type": "integer"
                          },
                          "bucket": {
                            "type": "string",
                            "enum": [
                              "cleared",
                              "registered"
                            ]
                          },
                          "maker": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "link": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "credits": {
                            "type": "integer"
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me": {
      "get": {
        "operationId": "getAccount",
        "summary": "Credits, plan and API limits for the key's account",
        "responses": {
          "200": {
            "description": "The account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "credits": {
                      "type": "integer"
                    },
                    "available": {
                      "type": "integer",
                      "description": "Credits API videos can spend (leaves out what's set aside for scheduled Auto-Pilot posts)"
                    },
                    "plan": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "videosPerDay": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      }
                    },
                    "api": {
                      "type": "object",
                      "properties": {
                        "allowed": {
                          "type": "boolean"
                        },
                        "limits": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer tc_live_..."
      }
    },
    "schemas": {
      "VideoRequest": {
        "type": "object",
        "required": [
          "topic"
        ],
        "properties": {
          "topic": {
            "type": "string",
            "minLength": 3,
            "maxLength": 300,
            "examples": [
              "The deepest hole ever dug"
            ]
          },
          "tone": {
            "type": "string",
            "enum": [
              "Dramatic",
              "Scary",
              "Funny",
              "Motivational",
              "Mysterious",
              "Educational",
              "Commentator",
              "News report",
              "Documentary",
              "Storyteller",
              "Deadpan",
              "Calm",
              "Advert",
              "How-to",
              "Countdown",
              "Review"
            ],
            "default": "Dramatic"
          },
          "length": {
            "type": "string",
            "enum": [
              "Quick",
              "Instagram Reels",
              "Snapchat",
              "YouTube Shorts",
              "TikTok",
              "Facebook Reels",
              "X",
              "LinkedIn",
              "Custom / long-form"
            ],
            "default": "YouTube Shorts"
          },
          "visuals": {
            "type": "string",
            "enum": [
              "stock",
              "photos",
              "stock_photos"
            ],
            "default": "stock",
            "description": "stock: Stock video; photos: AI pictures; stock_photos: Real photos"
          },
          "voice": {
            "type": "string",
            "description": "A voice id from the voice picker at https://tallclip.com/create. Leave out for the default."
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "es",
              "fr",
              "de",
              "it",
              "pt",
              "nl",
              "pl",
              "tr",
              "id",
              "sv",
              "es-us",
              "fr-ca",
              "da",
              "nb",
              "fi",
              "et",
              "lv",
              "lt",
              "cs",
              "sk",
              "sl",
              "hr",
              "sr",
              "bg",
              "ro",
              "hu",
              "el",
              "ru",
              "uk",
              "ar",
              "he",
              "ur",
              "hi",
              "bn",
              "pa",
              "gu",
              "mr",
              "ta",
              "te",
              "kn",
              "ml",
              "sw",
              "vi",
              "ko",
              "ja",
              "zh",
              "yue",
              "th"
            ],
            "default": "en"
          }
        }
      },
      "Accepted": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "rendering",
              "failed"
            ]
          },
          "credits": {
            "type": "integer"
          },
          "statusUrl": {
            "type": "string"
          },
          "warnings": {
            "type": "array",
            "description": "What this plan can't make well as asked (the video is still made as requested) - show these to the person. Codes: language_not_spoken, language_differs, length_differs, moving_needs_plan, little_to_photograph, look_needs_ai_pictures.",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ]
            }
          }
        }
      },
      "Video": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "writing",
              "rendering",
              "done",
              "failed",
              "expired"
            ]
          },
          "progress": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "topic": {
            "type": [
              "string",
              "null"
            ]
          },
          "length": {
            "type": [
              "string",
              "null"
            ]
          },
          "visuals": {
            "type": [
              "string",
              "null"
            ]
          },
          "credits": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "videoUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "A time-limited link to the MP4, once status is done"
          },
          "error": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        }
      }
    }
  }
}