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:
- 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:
| Field | Type | Required | Description |
|---|---|---|---|
| appId | String | Yes | Your application identifier from the API Dashboard |
| fileUrl | String | Yes | The URL of the video file to be described |
| mimeType | String | Yes | The MIME type of the video |
| prompt | Array | No | Optional array of prompts to guide the video description |
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:
| Field | Type | Description |
|---|---|---|
| description | String | The generated description of the video content |
| remainingDuration | Number | Remaining 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:
- 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.