API documentation | Profile Generator

Profile Generator APIRealistic profiles of people who do not exist: full name, gender, age, country and a natural phone photo. JSON over HTTPS. Within one account a full name and a photo are never repeated.Base URL: https://randomizer.beydemir.devAuthenticationSend the API key on every request: Authorization: Bearer rk_.... Create keys at https://randomizer.beydemir.dev/portal (shown once). Keys belong on servers: a key in the URL is refused (key_in_url) and there is no CORS.GET /v1/profilesReturns up to 10 profiles per call and charges 1 credit per profile returned.Query parameters (unknown, repeated or overlong parameters are refused with 400):

count: 1 to 10, default 1

country: two-letter code (see countries), random when omitted

gender: male or female, random when omitted

minAge, maxAge: 18 to 80, default 20 and 60

style: candid (natural phone photo) or portrait (headshot)

fallback: false never switches style; by default a candid request falls back to a portrait when no candid photo matches

Example:curl -H "Authorization: Bearer $RANDOMIZER_KEY" "https://randomizer.beydemir.dev/v1/profiles?country=DE&gender=female&count=3"Response:{ "data": [ { "id": "643b2e8c-d04b-432a-b167-b39d004ec1e7", "firstName": "Rania", "lastName": "Erhardt", "fullName": "Rania Erhardt", "gender": "female", "country": "DE", "age": 40, "photo": { "url": "https://randomizer.beydemir.dev/photos/643b2e8c-d04b-432a-b167-b39d004ec1e7", "style": "candid", "width": 640, "height": 800, "focus": { "x": 0.524, "y": 0.451 } } } ], "meta": { "requested": 1, "returned": 1 } }meta.returned is lower than count when the account already has every matching photo; meta.incomplete gives the reason and only returned profiles are charged. photo.focus is the face centre (0 to 1) for cropping.GET /photos/{id}Public, no key. AVIF, 640x800 (candid) or 640x640 (portrait), cached for a year. ?w=160|320|480 gives a smaller WebP, ?format=jpg a JPEG.GET /v1/countriesSupported countries: DE Germany, AT Austria, CH Switzerland, FR France, NL Netherlands, BE Belgium, GB United Kingdom, IE Ireland, PL Poland, CZ Czechia, SK Slovakia, HU Hungary, RO Romania, RS Serbia, HR Croatia, RU Russia, UA Ukraine, SE Sweden, NO Norway, DK Denmark, FI Finland, IT Italy, ES Spain, PT Portugal, GR Greece, US United States, CA Canada, AU Australia, IL Israel, BR Brazil, MX Mexico, TR Türkiye, AZ Azerbaijan, IR Iran, SA Saudi Arabia, AE United Arab Emirates, EG Egypt, IN India, CN China, TW Taiwan, JP Japan, KR South Korea, VN Vietnam, TH Thailand, ID Indonesia, NG Nigeria, ZA South Africa.GET /v1/usageBalance, limits and profiles per day for the last 30 days. Free of charge.{ "account": { "id": "acc_...", "plan": "free" }, "credits": 2840, "unlimited": false, "limits": { "perMinute": 60, "perDay": 1000 }, "today": { "used": 160, "remaining": 840, "resetsIn": 30512 }, "last30Days": [{ "day": "2026-10-14", "n": 160 }] }Credits and limits1 credit = 1 profile; credits are shared with the browser generator and never expire. Buy them at https://randomizer.beydemir.dev/portal. A request the balance cannot fully cover is refused with 402 and charges nothing. Accounts may request 60 profiles a minute and 1,000 a day (UTC).Response headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds), X-Daily-Limit, X-Daily-Remaining, X-Credits-Remaining, X-Request-Id. On 429, wait Retry-After seconds.Errors{ "error": { "code": "...", "message": "..." }, "requestId": "..." }. Branch on code; messages may change.

400 invalid_parameter, unknown_parameter, key_in_url: fix the request

401 missing_key, invalid_key, revoked_key: send a valid key

402 insufficient_credits: buy credits or ask for fewer profiles

403 account_suspended

404 no_photo_left: the account has every photo matching the filters; widen the age range or change style

409 names_exhausted: almost every name for this country and gender went to the account

429 rate_limited, daily_quota_exceeded: wait for Retry-After

503 photo_unavailable, busy: temporary, retry shortly