DescribePicture API

Overview

The DescribePicture API allows users to submit an image URL and receive a description of the image based on provided prompts. This API is particularly useful for applications requiring image analysis and description generation, such as content moderation, accessibility features, or automated cataloging.

Request Format

The request should be sent in JSON format with the following fields:

Field	Type	Description
imageUrl	String	The URL of the image to be described.
prompt	PromptInfo[]	A list of prompts that guide the description of the image. Each prompt should contain a role (user or assistant) and the text of the prompt.
mimeType	String	The MIME type of the image (e.g., image/jpeg, image/png).
appId	String	The application identifier for using this API. It must be obtained by sending an email to aidescribepicture@gmail.com

PromptInfo Object

Each PromptInfo object in the prompt array should contain:

Field	Type	Description
role	String	The role of the prompt, which can be either "user" or "assistant".
prompt	String	The text of the prompt that will guide the description of the image.

Response Format

The response will be returned in JSON format with the following fields:

Field	Type	Description
answer	String	The description of the image based on the provided prompts.
lastCredits	int	The number of API credits remaining after the request.

Authentication

To ensure the security of the API, each request needs to be encrypted using a secret key. The secret key for this API is

        
          690c9d8f65f0d8a8572f1c29e9a30b1d67326281f395b3b649f3bb0afbf19d4b

Below is an example code snippet demonstrating how to encrypt the data:

        
          {
            import base64
            from Crypto.Cipher import AES
            from Crypto.Random import get_random_bytes

            def encrypt_data(data, key):
                key_bytes = bytes.fromhex(key)
                iv = get_random_bytes(12)  
                cipher = AES.new(key_bytes, AES.MODE_GCM, nonce=iv)
                encrypted_data = cipher.encrypt(data.encode())
                return base64.b64encode(iv).decode(), base64.b64encode(encrypted_data + cipher.digest()).decode()

            # Example data
            data = json.dumps({
                "imageUrl": "https://example.com/image.jpg",
                "prompt": [
                    {"role": "user", "text": "Describe this picture"}
                ],
                "mimeType": "image/jpeg",
                "appId": "your-app-id"
            })

            # Encrypting the data using the key
            hex_key = "690c9d8f65f0d8a8572f1c29e9a30b1d67326281f395b3b649f3bb0afbf19d4b"
            iv_base64, encrypted_data_base64 = encrypt_data(data, hex_key)

            # Encrypted data
            payload = {
                "iv": iv_base64,
                "encryptedData": encrypted_data_base64
            }
          }

Request Url

The base URL for the DescribePicture API is:

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

Usage Example

Request Example

        
          {
            "imageUrl": "https://example.com/image.jpg",
            "prompt": [
              {
                "role": "user",
                "prompt": "Describe the main elements in the image."
              },
              {
                "role": "model",
                "prompt": "Highlight any text present in the image."
              }
            ],
            "mimeType": "image/jpeg",
            "appId": "your-app-id"
          }

Response Example

        
          {
            "answer": "The image shows a sunny beach with three palm trees and a clear blue sky. There is a sign that reads 'Welcome to Paradise'.",
            "lastCredits": 987
          }

Error Handling

In case of an error, the API will return a JSON object with an error field describing the nature of the error. Common errors include invalid image URLs, exceeded credit limits, or unsupported MIME types.

Rate Limits

The API has a rate limit of 100 requests per hour per appId. If the limit is exceeded, the API will return an error message indicating that the rate limit has been reached.

AppId Application Process

To use the DescribePicture API, you need a valid appId. Please apply by sending an email to aidescribepicture@gmail.com. In your email, provide the name and a brief description of your application, and how you plan to use this API. The review and approval process may take several working days.

Pricing and Payment

Price Plans

Payment Link: After your appId application is approved, a payment link will be sent to you. Through this link, you can select and pay for the default plan.

Custom Large Volume Requests

If you have a requirement for processing a large volume of images, please contact us at aidescribepicture@gmail.com with your specific needs.
We offer customized pricing based on the volume and specific requirements of your project.

Payment Methods

We accept various payment methods including credit card (Visa, MasterCard, American Express), PayPal, and bank transfer.

Getting Started

Once your appId is approved and your payment is processed, you will receive an email with your appId and secret key. You can then start using the API as per the request format described in this document.

Customer Support

For any queries or assistance, feel free to contact our customer support team at aidescribepicture@gmail.com We are here to help you integrate and make the most out of the DescribePicture API.