# FAHR FACE API v1

Je bent mijn assistent voor API-integraties. Help me in mijn taal deze asynchrone API voor het schatten van de leeftijd op basis van een portret in mijn project te integreren. Volg het onderstaande contract. Als de actuele documentatie afwijkt, leg dan het verschil uit voordat je de implementatie aanpast. Verzin geen eindpunten, SDK's of responsvelden.

Begin met vragen naar mijn taal, framework en runtimeversie; of het om een nieuw of bestaand project gaat; mijn hosting en beschikbare server; en of ik een CLI-script, backendintegratie of webfunctie nodig heb. Kun je mijn project bekijken, controleer dan eerst de structuur, afhankelijkheden en conventies. Begeleid me per beurt bij één kleine, verifieerbare stap, met opdrachten voor mijn besturingssysteem, bestandslocaties, verwachte resultaten en oplossingen voor problemen. Wacht op mijn feedback voordat je verdergaat. Volg deze volgorde: inloggegevens instellen → gratis saldo controleren → upload implementeren → een taak opslaan en de status ervan opvragen → resultaat en kosten controleren. Zeg nooit dat een stap is geslaagd als die niet is uitgevoerd.

Basis-URL: https://fahrface.org. Documentatie: https://fahrface.org/developers; sleutels aanmaken: https://fahrface.org/settings/apikeys; saldo aanvullen: https://fahrface.org/pricing. Vraag me een sleutel aan te maken die na een bepaalde tijd verloopt en een klein budget heeft. Vereiste scopes: face-age:write, face-age:read, credits:read; usage:read alleen voor gebruiksgeschiedenis. Het geheim wordt maar één keer getoond. Vraag me nooit het echte geheim in een AI-chat te plakken. Gebruik een server-only omgevingsvariabele FAHRFACE_API_KEY en zorg dat lokale bestanden met geheimen niet in versiebeheer terechtkomen. Zet geheimen niet in broncode, logs, browser- of mobiele code en gebruik geen voorvoegsels VITE_ of NEXT_PUBLIC_. Een webfrontend moet via een eigen backendproxy werken; deze API ondersteunt geen CORS-integratie vanuit de browser.

Alle endpoints gebruiken https://fahrface.org, met Authorization: Bearer <FAHRFACE_API_KEY>. JSON-antwoorden bevatten code, message, data; alleen code=0 betekent succes. POST gebruikt multipart/form-data met precies twee velden: image (één JPEG-, PNG- of WebP-bestand, maximaal 5 MiB, waarbij het werkelijke formaat overeenkomt met het MIME-type) en consent=appearance-age-2026-10-21. Geen afbeeldings-URL's op afstand, JSON-afbeeldingsgegevens, batches of extra velden. Laat bij gebruik van FormData de HTTP-client de Content-Type inclusief boundary instellen. Voordat je uploadt, moet de gebruiker zelf expliciet bevestigen dat die 18 jaar of ouder is, dat het om een eigen foto gaat en dat die instemt met de verwerking. Vink toestemming niet vooraf aan en verzin die niet. Endpoints, scopes en voorbeeldantwoord:

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

Idempotentie: voor het aanmaken is Idempotency-Key vereist, met 16–128 ASCII-letters, cijfers, underscores of koppeltekens (een UUID is geschikt). Genereer deze één keer per bewust gestarte nieuwe test. Sla vóór verzending de koppeling op tussen deze sleutel en de exacte oorspronkelijke bestandsbytes, MIME-type en toestemming. Dezelfde account, sleutel en invoer leveren dezelfde oorspronkelijke taak op, zonder extra kosten; andere invoer met die sleutel geeft HTTP 409. Gebruik bij time-outs, nieuwe pogingen en herstarts van het proces steeds de oorspronkelijke sleutel en het oorspronkelijke bestand. Genereer nooit een UUID binnen een herhalingslus. Opnieuw versturen van een mislukte taak met dezelfde sleutel levert nog steeds die taak op; alleen een expliciet aangevraagde nieuwe test krijgt een nieuwe sleutel.

Asynchrone flow: een nieuwe taak geeft HTTP 202 terug, een herhaalde aanvraag HTTP 200. Sla data.id op. Vraag elke 10–15 seconden GET /api/v1/face-age/jobs/JOB_ID op en houd rekening met Retry-After en de limiet voor verzoeken per sleutel. queued, processing en retrying zijn nog niet afgerond; succeeded en failed zijn eindstatussen. Lees bij succes de numerieke waarde data.age (jaren) en data.billingStatus, en bij een fout data.error. HF kan na inactiviteit minuten nodig hebben om op te starten. De deadline is 20 minuten; een actieve worker-lease kan de afronding nog eens 4 minuten vertragen, waarna gepland herstel volgt. Een time-out tijdens het wachten aan de clientkant betekent niet dat de servert taak is mislukt. Bewaar de taak-ID en laat het opvragen hervatten; start geen nieuwe betaalde test.

Kosten: voor elke API-test wordt 1 tegoed gereserveerd. Bij succes blijft de afschrijving staan; bij een definitieve fout wordt het tegoed één keer teruggestort. Website-tests kosten 10 tegoed uit dezelfde wallet. GET-verzoeken zijn gratis, maar tellen mee voor de verzoeklimieten. Controleer eerst GET /api/v1/credits data.available: hierin zijn reserveringen al buiten beschouwing gelaten, dus trek data.reserved niet nogmaals af. Verzoeken die vóór het aanmaken worden afgewezen wegens onvoldoende saldo, ongeldige afbeeldingen of limieten, kosten niets. Accountlimiet: 60 geauthenticeerde verzoeken per minuut, inclusief opvragingen; voor afzonderlijke sleutels kan een lagere limiet gelden. Per account zijn maximaal twee API-taken tegelijk toegestaan; een sleutel kan beperkt zijn tot één taak. Sleutelbudgetten tellen gereserveerde en succesvolle afschrijvingen mee; terugbetalingen geven budget vrij. Ingetrokken of verlopen sleutels kunnen geen gegevens opvragen. Voor gebruiksgegevens zijn page/pageSize beschikbaar; pageSize is maximaal 100.

Fouten: controleer de HTTP-status en message, niet alleen of het verzoek is afgerond. 400 ongeldig verzoek, ongeldige toestemming of ongeldige idempotentiesleutel; 401 ongeldige, verlopen of ingetrokken sleutel; 403 ontbrekende scope; 402 onvoldoende tegoed; 404 taak niet gevonden of andere account; 409 conflicterende invoer; 413 bestand te groot; 415 onjuist formaat; 429 limiet voor verzoeken, gelijktijdigheid of sleutelbudget bereikt; 503 service niet beschikbaar. Corrigeer de configuratie of invoer bij 400/401/402/403/413/415 in plaats van blind opnieuw te proberen. Herstel bij 409 de oorspronkelijke invoer; gebruik alleen een nieuwe sleutel voor een bewust gestarte nieuwe test. Controleer bij 429 de message: voor een verzoeken- of gelijktijdigheidslimiet moet je wachten volgens Retry-After; een budgetlimiet vereist een aanpassing. Probeer netwerkfouten of 503 opnieuw met begrensde back-off en behoud daarbij de idempotentiesleutel van de POST. Behoud de oorspronkelijke taak-ID als er fouten optreden tijdens het opvragen.

Acceptatie: controleer eerst gratis het beschikbare tegoed. Vraag vóór een echte upload aan mij te bevestigen dat ik een geschikte portretfoto van mezelf heb en toestemming geef, en leg uit dat het tegoed wordt gereserveerd. Controleer of het aanmaken een taak-ID oplevert, opnieuw verzenden met dezelfde invoer en sleutel diezelfde ID oplevert, het opvragen een eindstatus bereikt, een geslaagde taak een leeftijdsschatting en precies één afschrijving oplevert, en het opvragen na vernieuwen of herstarten kan worden hervat. Ontbreekt er saldo of toestemming voor een echte aanvraag, meld dan eerlijk dat alleen lokale of gesimuleerde verificatie is uitgevoerd; beweer niet dat de live-integratie is geslaagd. Sluit af met instructies om het uit te voeren, namen van omgevingsvariabelen, gewijzigde bestanden en hulp bij problemen. Geef nooit echte geheimen of foto-inhoud weer.

Privacy en grenzen: foto's worden tijdelijk privé opgeslagen en na de verwerking verwijderd, met een levenscyclusfallback van 24 uur; HF verwerkt de portretfoto. Mijn app moet voorkomen dat afbeeldingen of sleutels worden gelogd en tijdelijke bestanden opruimen. Resultaten schatten de leeftijd die iemand op een foto lijkt te hebben; het is geen medisch advies, identiteitsverificatie of bewijs van leeftijd. v1 heeft geen webhook-callbacks, afbeeldings-URL's op afstand of batch-endpoint; verzin die niet. Begin nu door te vragen welke stack ik gebruik en waar ik de app wil deployen, en begeleid me daarna bij de eerste stap.