Professional headshots with 1 API call

Integrate headshot generation into your app or workflow. POST one selfie, get four identity-preserved professional variants back — metered by credits, perfect for HR platforms, recruiting tools and team pages.

Get API Key

Not a developer? Use the web app instead — no code required.

Easy to integrate

A simple HTTP interface with sensible options:

Source images: Direct upload (image_file), a URL (image_url), or a base64 string (image_base64).
Result images: Always JSON: one entry per variant with base64 PNG data, dimensions and per-variant status — a batch is multiple images, so there is no binary mode.
Batch semantics: Four variants per style by default; request specific slots with variants. Only variants that actually succeeded are charged.

Get started

Create an API key in your dashboard, top up credits, then send your first request. A full 4-variant batch costs 10 credits — failed variants are never charged. Authenticate with X-Api-Key: hs_live_… (or Authorization: Bearer hs_live_…).

Sample code

The only request you need:

curl -H "X-Api-Key: hs_live_..." \
  -F "image_file=@/path/to/selfie.jpg" \
  -F "style=corporate" \
  -f https://usely.tools/api/v1/headshot \
  -o headshots.json

Styles

Pass one of four curated styles via the style parameter. Each style is a tuned wardrobe + backdrop + lighting recipe; the person is never changed.

Style	Look
`corporate`	Charcoal suit, neutral grey studio backdrop, three-point light — the classic LinkedIn look.
`business-casual`	Smart-casual outfit, bright office in soft bokeh, window daylight, approachable.
`bewerbung`	German application photo: blazer, plain light background, centered frontal framing, formal.
`creative`	Warm earth tones, relaxed editorial look for portfolios and social profiles.

Variants & retries

Every batch produces up to four variants (slots 0–3): the exact style template, a warmer three-quarter angle, an alternate outfit color, and a tighter neutral-expression crop. The four predictions run in parallel — one failed variant never kills the batch, it is simply reported as failed and not charged.

To regenerate a failed (or unloved) slot, request just that slot:

# Variant 2 failed? Re-request just that slot — you were
# never charged for it, and the retry costs only its share.
curl -H "X-Api-Key: hs_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.com/selfie.jpg",
        "style": "corporate", "variants": [2] }' \
  https://usely.tools/api/v1/headshot

API Reference

POST /api/v1/headshot

Generates professional headshot variants from a JPG / PNG / WebP selfie. File size up to 12 MB; the face should be front-facing, evenly lit, with head and shoulders visible. Image source: file upload (binary or base64) or download from URL. Requires an API key in the X-Api-Key header (or a Bearer token in Authorization).

Request body — `multipart/form-data` or `application/json`

Parameter	Type	Description
`image_file`	binary	Source selfie file (binary). If present, the other image source parameters must be empty.
`image_base64`	string	Source selfie as a base64-encoded string. Mutually exclusive with the other sources.
`image_url`	string	Source selfie URL to fetch. Mutually exclusive with the other sources.
`style`	string	`corporate` (default) · `business-casual` · `bewerbung` · `creative`.
`variants`	array	Variant slots to generate, e.g. `[0,1,2,3]` (default) or `[2]` to retry one slot. In multipart requests, send a comma-separated string like `0,2`.

Request headers

Header	Description
`X-Api-Key`	Your API key (`hs_live_…`). Also accepted as `Authorization: Bearer …`.
`Idempotency-Key`	Optional. Retries with the same key return the original response and are never double-charged.

Responses

Code	Description
`200`	Batch finished. JSON body with one entry per requested variant (`succeeded` entries carry base64 PNG + dimensions, `failed` entries carry an error). Headers include `X-Credits-Charged` and `X-Credits-Remaining`.
`400`	Invalid parameters or unprocessable input (no credits charged). Envelope: `{ "error": { "code", "message" } }`.
`401`	Authentication failed — missing or invalid API key (no credits charged).
`402`	Insufficient credits (no credits charged).
`429`	Rate limit exceeded (no credits charged). Includes a `Retry-After` header.
`500`	`provider_error` — every variant failed upstream (no credits charged).

Example response

{
  "data": {
    "style": "corporate",
    "variants": [
      { "variant": 0, "status": "succeeded",
        "image_base64": "iVBORw0KGgo…", "content_type": "image/png",
        "width": 1024, "height": 1024 },
      { "variant": 1, "status": "succeeded", "…": "…" },
      { "variant": 2, "status": "failed",
        "error": "This variant could not be generated. Retry it — failed variants are never charged." },
      { "variant": 3, "status": "succeeded", "…": "…" }
    ]
  },
  "credits_charged": 7,
  "credits_remaining": 143
}

Account endpoint

GET /api/v1/account

Fetch the current credit balance for the authenticated key. Balance changes may lag a few seconds; to track locally, read this once and then adjust using the X-Credits-Charged header returned by each batch.

{
  "data": {
    "credits": { "balance": 200 }
  }
}