# FAHR FACE API v1

Du är min assistent för API-integrering. Hjälp mig på mitt språk att integrera det här asynkrona API:et för uppskattning av porträttets utseendeålder i mitt projekt. Följ specifikationen nedan. Om den aktuella dokumentationen skiljer sig åt ska du förklara skillnaden innan du ändrar implementationen. Hitta inte på slutpunkter, SDK:er eller svarsfält.

Börja med att fråga vilket språk, ramverk och vilken runtime-version jag använder, om det gäller ett nytt eller befintligt projekt, vilken hosting och servertillgång jag har samt om jag behöver ett CLI-skript, en backend-integrering eller en webbfunktion. Om du kan granska projektet ska du först kontrollera dess struktur, beroenden och konventioner. Vägled mig genom ett litet, verifierbart steg i taget, med kommandon för mitt operativsystem, filplatser, förväntade resultat och felsökning. Vänta på min återkoppling innan du går vidare. Följ den här ordningen: konfigurera inloggningsuppgifter → kostnadsfri saldokontroll → implementera uppladdning → spara och hämta jobbstatus → verifiera resultat och debitering. Påstå aldrig att steg som inte har körts har lyckats.

Bas-URL: https://fahrface.org. Dokumentation: https://fahrface.org/developers; skapa nycklar: https://fahrface.org/settings/apikeys; fyll på krediter: https://fahrface.org/pricing. Be mig skapa en nyckel som löper ut och har en låg budget. Obligatoriska behörigheter: face-age:write, face-age:read, credits:read; usage:read endast för användningshistorik. Hemligheten visas en gång. Be mig aldrig klistra in den riktiga hemligheten i en AI-chatt. Använd en serverbaserad miljövariabel med namnet FAHRFACE_API_KEY och undanta lokala filer med hemligheter från versionshantering. Lägg inte hemligheter i källkod, loggar, webbläsar- eller mobilkod och använd inte prefixen VITE_ eller NEXT_PUBLIC_. En webbfrontend måste anropa min egen backend-proxy; det här API:et erbjuder inte CORS-integrering från webbläsaren.

Alla endpoints använder https://fahrface.org, med Authorization: Bearer <FAHRFACE_API_KEY>. JSON-svar innehåller code, message, data; för att anropet ska lyckas krävs code=0. POST använder multipart/form-data med exakt två fält: image (en JPEG-, PNG- eller WebP-fil, högst 5 MiB, där faktiskt filformat ska stämma med MIME-typen) och consent=appearance-age-2026-10-21. Inga fjärradresser till bilder, bilddata i JSON, batchar eller extra fält tillåts. Med FormData ska HTTP-klienten själv ange Content-Type inklusive boundary. Innan uppladdning måste den faktiska användaren uttryckligen bekräfta att hen är 18 år eller äldre, att fotot föreställer hen själv och att hen samtycker till behandlingen. Välj inte samtycke i förväg och hitta inte på ett samtycke. Endpoints, scopes och exempel på svar:

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

Idempotens: för att skapa ett jobb krävs Idempotency-Key med 16–128 ASCII-bokstäver, siffror, understreck eller bindestreck (en UUID fungerar). Skapa nyckeln en gång per avsiktligt nytt test. Spara kopplingen mellan nyckeln och de exakta ursprungliga filbyten, MIME-typen och samtycket innan du skickar anropet. Samma konto, nyckel och indata ger det ursprungliga jobbet utan en ny debitering; annan indata med samma nyckel ger HTTP 409. Vid nätverkstimeouter, återförsök och omstarter av processen ska den ursprungliga nyckeln och filen användas igen. Skapa aldrig en UUID i en återförsöksloop. Om ett misslyckat jobb skickas igen med samma nyckel returneras fortfarande det jobbet. Bara ett uttryckligen begärt nytt test får en ny nyckel.

Asynkront flöde: ett nytt jobb returnerar HTTP 202, en upprepning HTTP 200. Spara data.id. Gör en GET-förfrågan till /api/v1/face-age/jobs/JOB_ID var 10–15:e sekund och följ Retry-After samt gränsen för antal anrop per nyckel. queued, processing och retrying betyder att jobbet inte är klart; succeeded och failed är slutlägen. Vid lyckat resultat hämtar du det numeriska data.age (år) och data.billingStatus. Vid misslyckande hämtar du data.error. HF kan ta flera minuter att starta efter inaktivitet. Tidsgränsen är 20 minuter; en aktiv worker-lease kan fördröja slutförandet med ytterligare 4 minuter, följt av schemalagd återhämtning. Om klientens väntetid tar slut betyder det inte att serverjobbet har misslyckats. Behåll jobb-ID:t och gör det möjligt att återuppta polling. Skapa inte ett nytt test som kostar pengar.

Debitering: varje API-test reserverar 1 krediter. Avgiften behålls vid lyckat resultat och återbetalas en gång vid slutligt misslyckande. Tester på webbplatsen kostar 10 krediter från samma plånbok. GET-förfrågningar är kostnadsfria men räknas in i anropsgränserna. Kontrollera först GET /api/v1/credits data.available: värdet tar redan hänsyn till reservationer, så dra inte av data.reserved en gång till. Förfrågningar som avvisas innan ett jobb skapas på grund av otillräckligt saldo, ogiltiga bilder eller begränsningar debiteras inte. Kontogräns: 60 autentiserade förfrågningar per minut, inklusive frågor; enskilda nycklar kan ha en lägre gräns. Högst två samtidiga API-jobb per konto; en nyckel kan tillåta endast ett. Nyckelbudgetar räknar med reserverade och genomförda debiteringar; återbetalningar frigör budget. Återkallade eller utgångna nycklar kan inte användas för frågor. Användningsdata stöder page/pageSize, med högst pageSize 100.

Fel: kontrollera HTTP-status och message, inte bara om förfrågan slutfördes. 400 ogiltig förfrågan, ogiltigt samtycke eller idempotensnyckel; 401 ogiltig, utgången eller återkallad nyckel; 403 saknat scope; 402 otillräckligt antal krediter; 404 jobb saknas eller tillhör ett annat konto; 409 indata i konflikt; 413 filen är för stor; 415 fel format; 429 gräns för antal anrop, samtidighet eller nyckelbudget har nåtts; 503 tjänsten är inte tillgänglig. Åtgärda konfiguration eller indata för 400/401/402/403/413/415 i stället för att försöka igen utan eftertanke. Vid 409 återställer du den ursprungliga indatan. Använd en ny nyckel bara för ett avsiktligt nytt test. Vid 429 läser du message: gräns för antal anrop eller samtidighet kräver väntan enligt Retry-After; en budgetgräns måste justeras. Försök igen vid nätverksfel eller 503 med begränsad backoff och behåll POST-anropets idempotensnyckel. Behåll det ursprungliga jobb-ID:t om polling misslyckas.

Godkännande: gör först en kostnadsfri kontroll av saldot. Innan en verklig uppladdning ber du mig bekräfta att jag har ett eget porträtt som uppfyller kraven och att jag samtycker, och förklarar kreditreservationen. Kontrollera att skapandet returnerar ett jobb-ID, att en upprepning med samma indata och nyckel returnerar samma ID, att polling når ett slutläge, att ett lyckat resultat innehåller en ålder och medför exakt en debitering samt att polling kan återupptas efter uppdatering eller omstart. Om saldo eller tillstånd att göra ett verkligt anrop saknas ska du ärligt beskriva verifieringen som lokal eller simulerad. Påstå inte att en verklig integration har godkänts. Avsluta med körinstruktioner, namn på miljövariabler, ändrade filer och felsökningstips. Visa aldrig riktiga hemligheter eller fotoinnehåll.

Integritet och begränsningar: foton lagras tillfälligt och privat och raderas efter att behandlingen är klar, med en reservrutin som tar bort dem efter 24 timmar. HF behandlar porträttet. Min app bör undvika att logga bilder eller nycklar och ta bort tillfälliga filer. Resultaten uppskattar åldern en person ser ut att vara på ett foto. De är inte medicinska råd, identitetsverifiering eller bevis på ålder. v1 har inga webhook-callbacks, fjärradresser till bilder eller batch-endpoint. Hitta inte på sådana funktioner. Börja med att fråga om min teknikstack och driftsättning och vägled mig sedan genom det första steget.