Describe Picture API 文档

目录

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

1. API 概述

DescribePicture API 允许用户提交图像 URL 并根据提供的提示生成描述。该 API 特别适用于需要图像分析和描述生成的应用程序，如内容审核、无障碍功能或自动目录管理。

2. API 访问权限

在使用 DescribePicture API 之前，您需要获取有效的 App ID。

2.1 App ID 申请流程

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

3. 集成指南

3.1 请求格式

请求必须以 JSON 格式发送，并应包含以下字段。注意：如果同时提供了 imageUrl 和 imageBase64，系统将优先使用 imageUrl。

PromptInfo 对象

PromptInfo 数组中的每个对象应包含以下字段：

3.2 请求 URL

DescribePicture API 请求的基本 URL：

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

3.3 请求示例

以下是使用 Python requests 库发送 POST 请求的完整示例。

import requests
import json
import base64
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad
from Crypto.Random import get_random_bytes

# API 请求 URL
url = "https://us-central1-describepicture.cloudfunctions.net/describe_picture_api"

# 用于请求加密的密钥（十六进制格式）
hex_key = "690c9d8f65f0d8a8572f1c29e9a30b1d67326281f395b3b649f3bb0afbf19d4b"

# 图像 URL 和 MIME 类型
image_url = "https://blog.hootsuite.com/wp-content/uploads/2023/06/ai-art-prompt-4.png"
mime_type = "image/png"

# 从 API 仪表板获取的 appId
app_id = "your-app-id"

# Base64 编码的图像数据（如果提供）
image_base64 = ""  # 可选，如果有 Base64 编码的图像数据

# 用于指导图像描述内容的提示列表
prompt = [
    {"role": "user", "text": "描述这张图片"},
    {"role": "model", "text": "描述这张图片"},
    {"role": "user", "text": "描述这张图片"}
]

# 加密请求数据的函数
def encrypt_data(data, key):
    # 将密钥从十六进制转换为字节
    key_bytes = bytes.fromhex(key)

    # 生成随机初始化向量（IV）
    iv = get_random_bytes(12)

    # 创建 AES GCM 密码对象
    cipher = AES.new(key_bytes, AES.MODE_GCM, nonce=iv)

    # 加密数据并计算用于完整性的认证标签
    encrypted_data = cipher.encrypt(data.encode())

    # 将 IV 和加密数据（附加标签）都转换为 Base64 以便传输
    return base64.b64encode(iv).decode(), base64.b64encode(encrypted_data + cipher.digest()).decode()

# 将请求数据转换为 JSON 格式
data = json.dumps({
    "imageUrl": image_url,
    "prompt": prompt,
    "mimeType": mime_type,
    "appId": app_id,
    "imageBase64": image_base64
})

# 调用加密函数加密数据
iv_base64, encrypted_data_base64 = encrypt_data(data, hex_key)

# 准备 API 请求的负载
payload = {
    "iv": iv_base64,              # 加密使用的初始化向量（IV）
    "encryptedData": encrypted_data_base64  # 加密的数据
}

# 发送 POST 请求到 API
response = requests.post(url, json=payload)

# 打印响应状态码和内容
print("状态码:", response.status_code)
print("响应:", response.json())

3.4 响应格式

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

3.5 响应示例

{
  "answer": "图片显示了一个阳光明媚的海滩，有三棵棕榈树和清澈的蓝天。有一个写着'欢迎来到天堂'的标志。",
  "lastCredits": 987
}

4. 身份认证

为确保 API 的安全性，每个请求都必须使用提供的密钥进行加密：

密钥: 690c9d8f65f0d8a8572f1c29e9a30b1d67326281f395b3b649f3bb0afbf19d4b

4.1 数据加密示例

以下代码展示了使用 AES-GCM 加密请求数据的示例。这确保了请求中的敏感信息保持安全。

• 加密密钥：我们使用十六进制加密密钥来编码数据。
• 初始化向量（IV）：AES-GCM 需要一个 IV，我们生成一个随机的 12 字节序列。解密数据时需要 IV。
• 加密过程：数据被加密，并附加一个唯一的认证标签以确保完整性。

from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad
from Crypto.Random import get_random_bytes
import base64
import json

def encrypt_data(data, key):
    # 将十六进制加密密钥转换为字节
    key_bytes = bytes.fromhex(key)

    # 为 AES-GCM 生成 12 字节的初始化向量（IV）
    iv = get_random_bytes(12)

    # 使用密钥和 IV 在 GCM 模式下创建 AES 密码对象
    cipher = AES.new(key_bytes, AES.MODE_GCM, nonce=iv)

    # 加密数据并计算用于完整性的认证标签
    encrypted_data = cipher.encrypt(data.encode())

    # 将 IV 和加密数据（附加标签）都转换为 Base64 以便传输
    iv_base64 = base64.b64encode(iv).decode()
    encrypted_data_base64 = base64.b64encode(encrypted_data + cipher.digest()).decode()

    return iv_base64, encrypted_data_base64

# 要加密的 JSON 格式数据（转换为字符串格式）
data = json.dumps({
    "imageUrl": "https://blog.hootsuite.com/wp-content/uploads/2023/06/ai-art-prompt-4.png",
    "prompt": [{"role": "user", "text": "描述这张图片"}],
    "mimeType": "image/png",
    "appId": "your-app-id",
    "imageBase64": ""
})

# 使用提供的十六进制密钥加密数据
iv_base64, encrypted_data_base64 = encrypt_data(data, hex_key)

# 加密的数据和 IV 现在可以在请求中发送

5. 错误处理

如果请求失败，API 将返回一个带有 error 字段的 JSON 对象，描述问题的性质。常见错误包括：

• 无效的图像 URL
• 超出使用限制
• 不支持的 MIME 类型

错误响应示例：

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "请求参数无效：imageUrl 是必需的",
    "details": {
      "field": "imageUrl",
      "reason": "FIELD_REQUIRED"
    }
  }
}

6. 配额和使用限制

6.1 配额限制

每个 appId 每小时最多可发送 100 个请求。如果超过此限制，API 将返回一个错误消息，指示已达到请求限制。

6.2 购买额度

DescribePicture API 采用按使用量付费模式，最低购买金额为 60 美元。每个请求消耗 0.01 美元的配额。按照以下步骤购买额外额度：

1. 进入 API 仪表板的额度信息部分查看当前配额。
2. 使用滑块选择所需的额度数量；相应的费用会自动更新。
3. 点击添加更多额度以跳转到支付页面。

6.3 批量请求定制

对于大规模图像处理需求，请通过 aidescribepicture@gmail.com 联系我们，讨论定制价格方案。

6.4 支付方式

我们接受以下支付方式：

• 信用卡（Visa、MasterCard、American Express）
• PayPal
• 银行转账

7. 客户支持

如果您有任何问题或需要帮助，请通过 aidescribepicture@gmail.com 联系我们。我们随时为您提供帮助，确保您能够充分利用 DescribePicture API。