Navigation Menu
Language Selection

Describe Video API Documentation

Updated: at 04:00 PM

Table of Contents

Open Table of Contents

1. API Overview

The Describe Video API allows users to submit a video URL and generate a comprehensive description of its content. This API is particularly useful for:

2. API Access Permissions

Before using the Describe Video API, you need to obtain a valid App ID.

2.1 App ID Application Process

In the API Dashboard, simply provide an email and product name to generate an App ID. input_product_info

3. Integration Guide

3.1 Request Format

Requests must be sent in JSON format and should include the following fields:

FieldTypeRequiredDescription
appIdStringYesYour application identifier from the API Dashboard
fileUrlStringYesThe URL of the video file to be described
mimeTypeStringYesThe MIME type of the video
promptArrayNoOptional array of prompts to guide the video description

Supported Video Formats

The API supports the following video formats:

3.2 Request URL

The base URL for Describe Video API requests:

https://us-central1-describepicture.cloudfunctions.net/describe_file_api

3.3 Request Example

Here is a complete Python example using the requests library:

import requests

def describe_video(base_url, app_id, video_url, mime_type, prompt=None):
    # Validate video format
    supported_types = [
        'video/mov', 'video/mp4', 'video/mpg', 'video/mpeg',
        'video/avi', 'video/wmv', 'video/mpegps', 'video/flv'
    ]

    if mime_type not in supported_types:
        raise ValueError(f"Unsupported video format. Supported formats: {', '.join(supported_types)}")

    # Prepare request data
    url = f"{base_url}/describe_file_api"
    data = {
        'appId': app_id,
        'fileUrl': video_url,
        'mimeType': mime_type
    }

    # Add optional prompt
    if prompt:
        data['prompt'] = [{'role': 'user', 'text': prompt}]

    # Send request
    response = requests.post(url, json=data)
    response.raise_for_status()

    return response.json()

# Example usage
base_url = "https://us-central1-describepicture.cloudfunctions.net"
app_id = "your-app-id"
video_url = "https://example.com/video.mp4"
mime_type = "video/mp4"
prompt = "Describe what happens in this video"

result = describe_video(base_url, app_id, video_url, mime_type, prompt)
print(result)

3.4 Response Format

The API response is returned in JSON format with the following fields:

FieldTypeDescription
descriptionStringThe generated description of the video content
remainingDurationNumberRemaining available duration (in seconds) for your account

3.5 Response Example

{
  "description": "The video shows a cooking demonstration where a chef prepares a pasta dish. They start by boiling water, then add pasta while preparing a tomato sauce with garlic and herbs. The final dish is garnished with fresh basil and parmesan cheese.",
  "remainingDuration": 3600
}

4. Error Handling

The API uses standard HTTP status codes and provides detailed error messages:

Error responses include a descriptive message:

{
  "error": "Unsupported video format. Supported formats: video/mp4, video/mov, ..."
}

5. Quotas and Usage Limits

Usage is measured in video duration seconds. Your account has a quota that determines how many seconds of video you can process. You can view your remaining duration in the API Dashboard.

Rate Limits

6. Customer Support

For technical support or questions about the API, please contact us at aidescribepicture@gmail.com. Include your App ID and any relevant error messages in your support request.