Documentation de l'API Describe Picture

Table des matières

• 1. Aperçu de l’API
• 2. Autorisations d’accès à l’API
• 3. Guide d’intégration
  • 3.1 Format de la requête
  • 3.2 URL de la requête
  • 3.3 Exemple de requête
  • 3.4 Format de la réponse
  • 3.5 Exemple de réponse
• 4. Authentification
• 5. Gestion des erreurs
• 6. Quotas et limites d’utilisation
• 7. Support client

1. Aperçu de l’API

L’API DescribePicture permet aux utilisateurs de soumettre des URL d’images et de générer des descriptions basées sur les invites fournies. Cette API est particulièrement adaptée aux applications nécessitant une analyse d’images et une génération de descriptions, comme la modération de contenu, les fonctionnalités d’accessibilité ou la gestion automatisée de catalogues.

2. Autorisations d’accès à l’API

Avant d’utiliser l’API DescribePicture, vous devez obtenir un ID d’application valide.

2.1 Processus de demande d’ID d’application

Dans le tableau de bord de l’API, fournissez simplement votre courriel et le nom du produit pour générer un ID d’application.

3. Guide d’intégration

3.1 Format de la requête

Les requêtes doivent être envoyées au format JSON et doivent inclure les champs suivants. Remarque : Si imageUrl et imageBase64 sont tous deux fournis, le système donnera la priorité à imageUrl.

Champ	Type	Description
imageUrl	String	URL de l’image à décrire
imageBase64	String	Chaîne encodée en Base64 de l’image à décrire
prompt	PromptInfo[]	Liste d’invites pour guider la description de l’image, chacune contenant role et text
mimeType	String	Type MIME de l’image (ex: image/jpeg, image/png)
appId	String	Identifiant d’application obtenu du tableau de bord de l’API

Objet PromptInfo

Chaque objet dans le tableau PromptInfo doit contenir les champs suivants :

Champ	Type	Description
role	String	Rôle de l’invite, peut être user ou model
text	String	Texte d’invite pour guider la description d’image

3.2 URL de la requête

L’URL de base pour les requêtes de l’API DescribePicture :

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

3.3 Exemple de requête

Voici un exemple complet d’envoi d’une requête POST en utilisant la bibliothèque Python requests.

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

# URL de la requête API
url = "https://us-central1-describepicture.cloudfunctions.net/describe_picture_api"

# Clé d'encryption (au format hexadécimal)
hex_key = "690c9d8f65f0d8a8572f1c29e9a30b1d67326281f395b3b649f3bb0afbf19d4b"

# URL de l'image et type MIME
image_url = "https://blog.hootsuite.com/wp-content/uploads/2023/06/ai-art-prompt-4.png"
mime_type = "image/png"

# ID d'application obtenu du tableau de bord de l'API
app_id = "your-app-id"

# Données d'image encodées en Base64 (si fournies)
image_base64 = ""  # Optionnel, si des données d'image encodées en Base64 sont disponibles

# Liste d'invites pour guider la description de l'image
prompt = [
    {"role": "user", "text": "Décrivez cette image"},
    {"role": "model", "text": "Décrivez cette image"},
    {"role": "user", "text": "Décrivez cette image"}
]

# Fonction pour crypter les données de la requête
def encrypt_data(data, key):
    # Convertir la clé hexadécimale en octets
    key_bytes = bytes.fromhex(key)

    # Générer un vecteur d'initialisation aléatoire de 12 octets
    iv = get_random_bytes(12)

    # Créer un objet de chiffrement AES en mode GCM avec la clé et l'IV
    cipher = AES.new(key_bytes, AES.MODE_GCM, nonce=iv)

    # Chiffrer les données et calculer le tag d'authentification pour l'intégrité
    encrypted_data = cipher.encrypt(data.encode())

    # Convertir l'IV et les données chiffrées en Base64 pour la transmission
    return base64.b64encode(iv).decode(), base64.b64encode(encrypted_data + cipher.digest()).decode()

# Convertir les données de la requête au format JSON
data = json.dumps({
    "imageUrl": image_url,
    "prompt": prompt,
    "mimeType": mime_type,
    "appId": app_id,
    "imageBase64": image_base64
})

# Appeler la fonction de chiffrement pour chiffrer les données
iv_base64, encrypted_data_base64 = encrypt_data(data, hex_key)

# Préparer la charge utile de la requête API
payload = {
    "iv": iv_base64,              # Vecteur d'initialisation (IV) utilisé pour le chiffrement
    "encryptedData": encrypted_data_base64  # Données chiffrées
}

# Envoyer la requête POST à l'API
response = requests.post(url, json=payload)

# Afficher le code d'état et le contenu de la réponse
print("Code d'état:", response.status_code)
print("Réponse:", response.json())

3.4 Format de la réponse

La réponse est renvoyée au format JSON et contient les champs suivants :

Champ	Type	Description
answer	String	Description de l’image générée basée sur les invites fournies
lastCredits	int	Crédits API restants après la requête

3.5 Exemple de réponse

{
  "answer": "L'image montre une plage ensoleillée avec trois palmiers et un ciel bleu clair. Il y a un panneau qui indique 'Bienvenue au Paradis'.",
  "lastCredits": 987
}

4. Authentification

Pour assurer la sécurité de l’API, chaque requête doit être chiffrée à l’aide de la clé fournie :

Clé : 690c9d8f65f0d8a8572f1c29e9a30b1d67326281f395b3b649f3bb0afbf19d4b

4.1 Exemple de chiffrement des données

Le code suivant montre un exemple de chiffrement des données de requête en utilisant AES-GCM. Cela garantit que les informations sensibles de la requête restent sécurisées.

• Clé de chiffrement : Nous utilisons une clé de chiffrement hexadécimale pour encoder les données.
• Vecteur d’initialisation (IV) : AES-GCM nécessite un IV, que nous générons comme une séquence aléatoire de 12 octets. L’IV est nécessaire pour déchiffrer les données.
• Processus de chiffrement : Les données sont chiffrées, et un tag d’authentification unique est ajouté pour assurer l’intégrité.

5. Gestion des erreurs

Si une requête échoue, l’API renverra un objet JSON avec un champ error décrivant la nature du problème. Les erreurs courantes incluent :

• URL d’image invalide
• Limites d’utilisation dépassées
• Type MIME non pris en charge

6. Quotas et limites d’utilisation

6.1 Limites de quota

Chaque appId peut envoyer jusqu’à 100 requêtes par heure. Si cette limite est dépassée, l’API renverra un message d’erreur indiquant que la limite de requêtes a été atteinte.

6.2 Achat de crédits

L’API DescribePicture utilise un modèle de paiement à l’utilisation avec un montant minimum d’achat de 60 $. Chaque requête consomme un coût de quota de 0,01 $. Suivez ces étapes pour acheter des crédits supplémentaires :

1. Accédez à la section Informations sur les crédits dans le Tableau de bord de l’API pour vérifier votre quota actuel.
2. Utilisez le curseur pour sélectionner le nombre de crédits souhaité ; le coût correspondant sera automatiquement mis à jour.
3. Cliquez sur Ajouter plus de crédits pour être redirigé vers la page de paiement.

6.3 Personnalisation des requêtes en masse

Pour les besoins de traitement d’images à grande échelle, veuillez nous contacter à aidescribepicture@gmail.com pour discuter d’un plan tarifaire personnalisé.

6.4 Modes de paiement

Nous acceptons les modes de paiement suivants :

• Cartes de crédit (Visa, MasterCard, American Express)
• PayPal
• Virements bancaires

7. Support client

Si vous avez des questions ou besoin d’aide, veuillez nous contacter à aidescribepicture@gmail.com. Nous sommes là pour vous aider à tirer le meilleur parti de l’API DescribePicture.