Référence technique

Documentation API

Authentification

Toutes les requêtes à l'API VisionLabs doivent inclure votre clé API dans l'en-tête X-API-Key. Vous pouvez générer et révoquer vos clés depuis le tableau de bord de votre compte.

X-API-Key: vl_live_votre_cle

Ne partagez jamais votre clé côté client. En cas de fuite, révoquez-la immédiatement et générez-en une nouvelle.

Endpoint POST /v1/classify

Classifiez une image en envoyant une URL publique ou une image encodée en base64.

URL

POST https://api.visionlabs.ai/v1/classify

Corps de la requête (JSON)

Champ	Type	Obligatoire	Description
`image_url`	string	Oui*	URL publique de l'image à classifier.
`image_base64`	string	Oui*	Image encodée en base64 (JPEG/PNG/WebP).
`model`	string	Non	Modèle à utiliser : `general-v2` (défaut), `retail-v1`, `industrial-v1`.
`top_k`	integer	Non	Nombre de prédictions renvoyées (défaut : 1, max : 10).

* Au moins un des champs image_url ou image_base64 doit être fourni.

Exemple de requête

curl -X POST https://api.visionlabs.ai/v1/classify \
  -H "X-API-Key: vl_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://exemple.com/image.jpg",
    "model": "general-v2",
    "top_k": 3
  }'

Exemple de réponse JSON

{
  "status": "success",
  "predictions": [
    {
      "label": "chat",
      "confidence": 0.9834,
      "bounding_box": {
        "x": 120,
        "y": 80,
        "width": 240,
        "height": 200
      }
    },
    {
      "label": "animal",
      "confidence": 0.9941
    }
  ],
  "model": "general-v2",
  "inference_time_ms": 87
}

Le champ bounding_box est fourni lorsque le modèle supporte la localisation et que le paramètre correspondant est activé.

Codes d'erreur

Code HTTP	Signification	Cause courante
`400`	Bad Request	Corps JSON invalide, image manquante ou format non supporté.
`401`	Unauthorized	Clé API absente, invalide ou révoquée.
`429`	Too Many Requests	Quota mensuel dépassé ou limite de débit atteinte.
`500`	Internal Server Error	Erreur interne temporaire. Réessayez dans quelques secondes.

Chaque réponse d'erreur inclut un champ error avec un message explicite et un code interne pour faciliter le diagnostic.

SDK et intégrations

Python

import visionlabs

client = visionlabs.Client(api_key="vl_live_votre_cle")
result = client.classify(image_url="https://exemple.com/image.jpg")
print(result.predictions[0].label)

Node.js

const VisionLabs = require('visionlabs');

const client = new VisionLabs({ apiKey: 'vl_live_votre_cle' });
const result = await client.classify({ imageUrl: 'https://exemple.com/image.jpg' });
console.log(result.predictions[0].label);

cURL

curl -X POST https://api.visionlabs.ai/v1/classify \
  -H "X-API-Key: vl_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://exemple.com/image.jpg"}'

Limites et bonnes pratiques

Taille maximale d'image : 10 Mo par requête.
Formats supportés : JPEG, PNG, WebP, GIF (première image).
Résolution recommandée : entre 224×224 et 2048×2048 pixels.
Compressiez vos images avant l'envoi pour réduire la latence.
Mettez en cache les résultats d'inférence lorsque c'est pertinent.
Utilisez le paramètre model pour cibler un modèle spécialisé et améliorer la précision.
Respectez la vie privée : n'envoyez pas d'images contenant des données personnelles sensibles sans consentement.