REST API · v1

Documentation de l’API

Envoyez des portraits via une API asynchrone, utilisez votre portefeuille de crédits existant et suivez chaque tâche et chaque débit.

Espace développeur

Connectez votre application avec un assistant IA

Copiez cette invite dans ChatGPT, Claude, Cursor ou votre assistant de programmation. Il vous posera des questions sur votre environnement technique, puis vous guidera dans la configuration des identifiants, la vérification du solde, l’envoi d’une tâche et la vérification du résultat.

Ouvrir le texte brut

Vous n’avez pas besoin de communiquer votre clé API à l’IA. L’invite vous guidera pour la configurer dans l’environnement de votre propre serveur.

Lire l’invite complète / copier manuellement

# FAHR FACE API v1

Vous êtes mon assistant d’intégration API. Répondez dans ma langue et aidez-moi à intégrer cette API asynchrone d’estimation de l’âge apparent à partir d’un portrait dans mon projet. Respectez le contrat ci-dessous. Si la documentation en ligne diffère, expliquez la différence avant de modifier l’implémentation. N’inventez pas de points de terminaison, de SDK ni de champs de réponse.

Commencez par me demander ma langue, mon framework et sa version d’exécution ; s’il s’agit d’un nouveau projet ou d’un projet existant ; quelle est ma plateforme d’hébergement et si j’ai accès à un serveur ; et si j’ai besoin d’un script CLI, d’une intégration backend ou d’une fonctionnalité web. Si vous pouvez examiner mon projet, vérifiez d’abord sa structure, ses dépendances et ses conventions. Guidez-moi à chaque tour avec une petite étape vérifiable, en indiquant les commandes adaptées à mon système d’exploitation, l’emplacement des fichiers, les résultats attendus et les solutions aux problèmes possibles. Attendez mon retour avant de poursuivre. Suivez cet ordre : configuration des identifiants → vérification gratuite du solde → implémentation de l’envoi → enregistrement et consultation du statut d’une tâche → vérification du résultat et de la facturation. Ne prétendez jamais qu’une étape non exécutée a réussi.

URL de base : https://fahrface.org. Documentation : https://fahrface.org/developers ; créer des clés : https://fahrface.org/settings/apikeys ; ajouter des crédits : https://fahrface.org/pricing. Demandez-moi de créer une clé à durée limitée avec un petit budget. Autorisations requises : face-age:write, face-age:read, credits:read ; usage:read uniquement pour l’historique d’utilisation. Le secret ne s’affiche qu’une seule fois. Ne me demandez jamais de coller le vrai secret dans une conversation avec une IA. Utilisez une variable d’environnement FAHRFACE_API_KEY accessible uniquement côté serveur et excluez les fichiers contenant des secrets locaux du contrôle de version. Ne mettez pas de secrets dans le code source, les journaux, le navigateur ou le code mobile, et n’utilisez pas les préfixes VITE_ ou NEXT_PUBLIC_. Une interface web doit appeler mon propre proxy backend ; cette API ne prend pas en charge l’intégration CORS depuis un navigateur.

Tous les points de terminaison utilisent https://fahrface.org, avec Authorization: Bearer <FAHRFACE_API_KEY>. Les réponses JSON contiennent code, message, data ; la réussite exige code=0. La requête POST utilise multipart/form-data avec exactement deux champs : image (un fichier JPEG, PNG ou WebP, de 5 Mio maximum, dont le format réel correspond au type MIME) et consent=appearance-age-2026-10-21. Aucune URL d’image distante, charge utile d’image JSON, requête groupée ni aucun champ supplémentaire. Avec FormData, laissez le client HTTP définir Content-Type, y compris la boundary. Avant l’envoi, l’utilisateur réel doit confirmer explicitement qu’il a au moins 18 ans, qu’il s’agit de sa propre photo et qu’il consent au traitement. Ne présélectionnez pas et ne fabriquez pas le consentement. Points de terminaison, autorisations et exemple de réponse :

POST /api/v1/face-age/jobs — face-age:write
GET /api/v1/face-age/jobs/JOB_ID — face-age:read
GET /api/v1/credits — credits:read
GET /api/v1/usage?page=1&pageSize=20 — usage:read

POST 202 / replay 200:
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "JOB_ID",
    "status": "queued",
    "age": null,
    "creditsCost": 1,
    "billingStatus": "reserved"
  }
}

GET /api/v1/credits → data: available, reserved, testCost, priceVersion
GET /api/v1/usage → data: items, total, page, pageSize

Idempotence : la création exige Idempotency-Key, composé de 16 à 128 caractères ASCII parmi les lettres, les chiffres, les tirets bas et les traits d’union (un UUID convient). Générez-le une seule fois pour chaque nouveau test intentionnel. Avant l’envoi, enregistrez son association avec les octets exacts du fichier d’origine, son type MIME et le consentement. Pour un même compte, une même clé et une même entrée, le travail d’origine est renvoyé sans facturation supplémentaire ; une entrée différente avec cette clé renvoie HTTP 409. En cas de délai d’attente réseau, de nouvelle tentative ou de redémarrage du processus, réutilisez la clé et le fichier d’origine. Ne générez jamais un UUID dans une boucle de nouvelle tentative. La relance d’un travail échoué avec la même clé renvoie toujours ce travail ; seul un nouveau test explicitement demandé reçoit une nouvelle clé.

Flux asynchrone : un nouveau travail renvoie HTTP 202, une répétition HTTP 200. Enregistrez data.id. Interrogez GET /api/v1/face-age/jobs/JOB_ID toutes les 10 à 15 secondes, en respectant Retry-After et la limite de requêtes par clé. queued, processing et retrying indiquent que le travail n’est pas terminé ; succeeded et failed sont des états finaux. En cas de réussite, lisez la valeur numérique data.age (en années) et data.billingStatus ; en cas d’échec, lisez data.error. Les démarrages à froid HF peuvent prendre plusieurs minutes. Le délai est de 20 minutes ; un bail de travailleur actif peut retarder le règlement de 4 minutes supplémentaires, puis une récupération planifiée a lieu. Un délai d’attente côté client ne signifie pas que le travail sur le serveur a échoué. Conservez l’ID du travail et permettez la reprise des interrogations ; ne créez pas un autre test payant.

Facturation : chaque test API réserve 1 crédit, conserve les frais en cas de réussite et effectue un seul remboursement en cas d’échec final. Les tests sur le site coûtent 10 crédits, prélevés sur le même portefeuille. Les requêtes GET sont gratuites, mais comptent dans les limites de requêtes. Vérifiez d’abord GET /api/v1/credits data.available : cette valeur tient déjà compte des réservations, ne soustrayez donc pas data.reserved une seconde fois. Les requêtes rejetées avant la création pour solde insuffisant, images non valides ou limites dépassées ne sont pas facturées. Limite du compte : 60 requêtes authentifiées par minute, requêtes de consultation comprises ; les clés individuelles peuvent avoir une limite inférieure. Au maximum deux travaux API simultanés par compte ; une clé peut n’en autoriser qu’un seul. Les budgets des clés comptabilisent les frais réservés et réglés ; les remboursements libèrent le budget. Les clés révoquées ou expirées ne peuvent pas effectuer de requêtes de consultation. L’historique d’utilisation accepte page/pageSize ; pageSize ne peut pas dépasser 100.

Erreurs : vérifiez le statut HTTP et message, pas seulement si la requête s’est terminée. 400 requête, consentement ou clé d’idempotence non valide ; 401 clé non valide, expirée ou révoquée ; 403 autorisation manquante ; 402 crédits insuffisants ; 404 travail introuvable ou associé à un autre compte ; 409 entrée en conflit ; 413 fichier trop volumineux ; 415 format incorrect ; 429 limite de débit, de concurrence ou de budget de la clé dépassée ; 503 service indisponible. Pour les erreurs 400/401/402/403/413/415, corrigez la configuration ou l’entrée au lieu de réessayer aveuglément. Pour une erreur 409, restaurez l’entrée d’origine ; utilisez une nouvelle clé uniquement pour un nouveau test intentionnel. Pour une erreur 429, examinez message : une limite de débit ou de concurrence exige d’attendre selon Retry-After ; une limite de budget nécessite un ajustement. Réessayez en cas d’erreur réseau ou de 503 avec un délai exponentiel limité, en conservant la clé d’idempotence POST. Conservez l’ID du travail d’origine après les erreurs d’interrogation.

Validation : commencez par vérifier gratuitement le solde. Avant tout véritable envoi, confirmez avec moi que je dispose d’un portrait admissible, que j’en suis la personne représentée et que j’y consens, puis expliquez la réservation de crédits. Vérifiez que la création renvoie un ID de travail, qu’une répétition avec la même entrée et la même clé renvoie cet ID, que les interrogations aboutissent à un état final, qu’une réussite fournit un âge et entraîne exactement une facturation, et que l’actualisation ou le redémarrage permet de reprendre les interrogations. Si le solde ou l’autorisation pour un véritable appel fait défaut, indiquez honnêtement que la vérification est locale ou simulée ; ne prétendez pas que l’intégration réelle a été validée. Terminez par les instructions d’exécution, les noms des variables d’environnement, les fichiers modifiés et le dépannage. Ne divulguez jamais de véritables secrets ni le contenu de photos.

Confidentialité et limites : les photos sont stockées temporairement dans un espace privé, puis supprimées une fois le traitement terminé, avec une suppression de secours après 24 heures ; HF traite le portrait. Mon application doit éviter de consigner les images ou les clés et supprimer les fichiers temporaires. Les résultats estiment l’âge apparent sur une photo ; ils ne constituent ni un avis médical, ni une vérification d’identité, ni une preuve d’âge. La v1 ne comporte ni rappels par webhook, ni URL d’image distante, ni point de terminaison pour les requêtes groupées ; n’en inventez pas. Commencez par me demander quelle est ma pile technologique et où se fera le déploiement, puis guidez-moi pour la première étape.

Facturation

API : 1 crédit par test réussi. Site web : 10 crédits par test. Les deux utilisent le même portefeuille. La création d’une tâche API réserve 1 crédit ; un échec définitif le rembourse une seule fois.

Envoyez Authorization: Bearer avec l’autorisation requise. Pour réessayer d’envoyer les mêmes octets d’image, utilisez la même Idempotency-Key. Si vous la réutilisez avec des données différentes, la réponse sera HTTP 409. Les consultations ne consomment pas de crédits.

Points de terminaison

HTTP	Autorisations
POST /api/v1/face-age/jobs	face-age:write
GET /api/v1/face-age/jobs/{id}	face-age:read
GET /api/v1/credits	credits:read
GET /api/v1/usage?page=1&pageSize=20	usage:read

Créer une tâche

Utilisez multipart/form-data avec un seul fichier image (JPEG, PNG ou WebP, jusqu’à 5 MB) et le champ de consentement ci-dessous. Seuls les adultes qui envoient leur propre photo avec leur consentement peuvent utiliser ce point de terminaison. Les URL distantes et les paramètres supplémentaires sont refusés. Générez une nouvelle clé d’idempotence uniquement pour un nouveau test logique.

# Générez et enregistrez une clé pour chaque nouveau test ; en cas de nouvelle tentative, exécutez uniquement la commande curl ci-dessous avec la clé et l’image d’origine.
IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST 'https://fahrface.org/api/v1/face-age/jobs' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F 'image=@portrait.jpg' \
  -F 'consent=appearance-age-2026-10-21'

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "JOB_ID",
    "status": "queued",
    "age": null,
    "creditsCost": 1,
    "billingStatus": "reserved"
  }
}

Consulter les résultats

La création renvoie HTTP 202 et un ID de tâche. Consultez le statut toutes les 10–15 secondes. queued, processing et retrying sont des états non définitifs ; succeeded et failed sont des états définitifs. Le réveil de HF peut prendre plusieurs minutes. Les tâches ont un délai limite de 20 minutes ; un bail de travailleur actif peut retarder la récupération finale de quatre minutes supplémentaires au maximum.

curl 'https://fahrface.org/api/v1/face-age/jobs/JOB_ID' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY"

Erreurs et limites

Les réponses utilisent code/message/data. HTTP 400 : requête ou consentement invalide ; 401 : clé invalide/expirée ; 403 : autorisation manquante ; 402 : crédits insuffisants ; 404 : tâche inexistante ou non détenue par votre compte ; 409 : données modifiées ; 413/415 : taille/type d’image invalide ; 429 : limite de requêtes, de tâches simultanées ou de budget atteinte ; 503 : service indisponible. Respectez Retry-After, réutilisez la même clé d’idempotence et examinez message avant de réessayer.

Les clés expirent dans un délai maximal d’un an. Les budgets incluent les crédits réservés et utilisés avec succès ; les remboursements rétablissent le budget. Le compte autorise 60 requêtes/minute et au maximum deux tâches API actives.

Les portraits sont stockés temporairement dans un espace de stockage privé et supprimés après le traitement définitif, avec une suppression de secours au bout de 24 heures. HF traite la photo ; les estimations ne constituent ni un avis médical, ni une vérification d’identité, ni une preuve d’âge.