Describe Video API Documentation

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:

• Content cataloging and indexing
• Accessibility features for visually impaired users
• Video content moderation
• Educational content analysis

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.

3. Integration Guide

3.1 Request Format

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

Supported Video Formats

The API supports the following video formats:

• video/mov
• video/mp4
• video/mpg
• video/mpeg
• video/avi
• video/wmv
• video/mpegps
• video/flv

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:

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:

• 400: Bad Request - Invalid parameters or unsupported video format
• 401: Unauthorized - Invalid or missing App ID
• 403: Forbidden - Quota exceeded or account restrictions
• 404: Not Found - Video URL not accessible
• 500: Internal Server Error - Server-side processing error

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

• Maximum video size: 20GB
• Maximum video duration: 30 minutes
• Maximum concurrent requests: 5 per account

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.