视频描述 API 文档

目录

• 1. API 概述
• 2. API 访问权限
• 3. 集成指南
  • 3.1 请求格式
  • 3.2 请求 URL
  • 3.3 请求示例
  • 3.4 响应格式
  • 3.5 响应示例
• 4. 错误处理
• 5. 配额和使用限制
• 6. 客户支持

1. API 概述

视频描述 API 允许用户提交视频 URL 并生成详细的内容描述。该 API 特别适用于：

• 内容编目和索引
• 视障用户的无障碍功能
• 视频内容审核
• 教育内容分析

2. API 访问权限

在使用视频描述 API 之前，您需要获取有效的 App ID。

2.1 App ID 申请流程

在 API 仪表板中，只需提供邮箱和产品名称即可生成 App ID。

3. 集成指南

3.1 请求格式

请求必须以 JSON 格式发送，并包含以下字段：

支持的视频格式

API 支持以下视频格式：

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

3.2 请求 URL

视频描述 API 的基础 URL：

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

3.3 请求示例

这是一个使用 requests 库的完整 Python 示例：

import requests

def describe_video(base_url, app_id, video_url, mime_type, prompt=None):
    # 验证视频格式
    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"不支持的视频格式。支持的格式：{', '.join(supported_types)}")

    # 准备请求数据
    url = f"{base_url}/describe_file_api"
    data = {
        'appId': app_id,
        'fileUrl': video_url,
        'mimeType': mime_type
    }

    # 添加可选的提示
    if prompt:
        data['prompt'] = [{'role': 'user', 'text': prompt}]

    # 发送请求
    response = requests.post(url, json=data)
    response.raise_for_status()

    return response.json()

# 使用示例
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 = "描述这个视频中发生了什么"

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

3.4 响应格式

API 响应以 JSON 格式返回，包含以下字段：

3.5 响应示例

{
  "description": "视频展示了一个烹饪演示，厨师正在准备意大利面。首先烧开水，然后加入面条，同时准备含有大蒜和香草的番茄酱。最后用新鲜罗勒叶和帕尔马干酪装饰。",
  "remainingDuration": 3600
}

4. 错误处理

API 使用标准的 HTTP 状态码并提供详细的错误消息：

• 400：请求错误 - 参数无效或不支持的视频格式
• 401：未授权 - App ID 无效或缺失
• 403：禁止访问 - 超出配额或账户限制
• 404：未找到 - 视频 URL 无法访问
• 500：服务器内部错误 - 服务器端处理错误

错误响应包含描述性消息：

{
  "error": "不支持的视频格式。支持的格式：video/mp4, video/mov, ..."
}

5. 配额和使用限制

使用量以视频时长（秒）计算。您的账户有一个配额，决定了您可以处理的视频秒数。您可以在 API 仪表板中查看剩余时长。

速率限制

• 最大视频大小：20GB
• 最大视频时长：30 分钟
• 最大并发请求数：每个账户 5 个

6. 客户支持

如需技术支持或有关于 API 的问题，请发送邮件至 aidescribepicture@gmail.com。请在支持请求中包含您的 App ID 和相关的错误消息。