API REFERENCE

Analyze Video

On this page

POST/api/content/analyze

Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, "Describe what happens" or "Rate the visual quality 1-10." Returns the generated text.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/content/analyze' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "video_url": "string",
  "prompt": "string"
}'

Request body required

Video analysis parameters

application/json

video_urlstringrequired

Publicly accessible URL of the video to analyze. Supported formats: MP4, MOV, AVI, and other FFmpeg-compatible formats. Maximum duration: 1 hour.

format: uri

promptstringrequired

A text prompt that guides the analysis. Can be instructive, descriptive, or phrased as a question. Examples: "Describe the key moments in this video", "Generate 5 SEO keywords for this video".

maxLength: 2000

temperaturenumber

Controls the randomness of the text output. Lower values produce more focused results. Defaults to 0.2.

Default: 0.2

minimum: 0 · maximum: 1

max_tokensinteger

Maximum number of tokens to generate. If omitted, uses the model default.

minimum: 1 · maximum: 4096

Responses

200Video analyzed successfully

application/json

textstringrequired

The generated analysis text based on the video and prompt.

finish_reasonstring · enumnullable

stop if the generation completed normally. length if truncated at the token limit.

Values: "stop", "length"

usageobjectnullable

Properties

output_tokensinteger

Number of tokens in the generated text.

400Validation failed — invalid or missing request body fields

application/json

errorstringrequired

Error message describing what went wrong

401Unauthorized — invalid or missing API key

application/json

errorstringrequired

Error message describing what went wrong

502Video analysis failed upstream

application/json

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "description": "Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, \"Describe what happens\" or \"Rate the visual quality 1-10.\" Returns the generated text.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Video analysis parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContentCreateAnalyzeRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Video analyzed successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentCreateAnalyzeResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation failed — invalid or missing request body fields",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentErrorResponse"
          }
        }
      }
    },
    "502": {
      "description": "Video analysis failed upstream",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentErrorResponse"
          }
        }
      }
    }
  }
}