Developers

The 5iveHead API

Add portrait optimisation to your product with a single request.

API access is included with the Enterprise plan. Sandbox keys are free. Contact sales

Overview

The 5iveHead API optimises a portrait and returns the result with its 5iveHead Score. Requests are made over HTTPS and return JSON. The API is versioned, and the current version is v1.

https://api.5ivehead.com/v1

Authentication

Authenticate with a secret key in the Authorization header. Keys beginning fh_test_ use the sandbox. Keys beginning fh_live_ are available on Enterprise plans.

Authorization: Bearer fh_test_sk_7Qx2Lm9aVd4Rr1tW

Get a sandbox key

Create a portrait

POST/v1/portraits

Parameter	Type	Description
`image`	file	The portrait to optimise. JPEG or PNG, up to 12 MB.
`level`	string	`standard`, `professional` or `executive`. Defaults to `standard`.
`preset`	string	Optional. `passport`, `licence`, `profile` or `speaker`.
`certificate`	boolean	Return a verifiable certificate. Executive and Enterprise only.

Try it

Send a test request against the sandbox. If you have optimised a portrait on this device, it will be used.

Level Preset

// The response will appear here.

Response

A successful request returns 201 Created with the optimised portrait.

{
  "id": "por_8Hq3Zt",
  "status": "optimised",
  "level": "professional",
  "score": { "before": 62, "after": 93 },
  "uplift_pct": 41,
  "image_url": "https://cdn.5ivehead.com/p/por_8Hq3Zt.jpg",
  "processing_ms": 1420
}

score.before and score.after are the 5iveHead Score of the portrait before and after optimisation, from 1 to 100. Image URLs expire after 24 hours.

Errors

Code	Meaning
`400`	The request was malformed, or no portrait was found in the image.
`401`	The API key is missing or invalid.
`402`	The requested level is not included in your plan.
`422`	The portrait does not meet the minimum requirements. Please use a front-facing portrait.
`429`	Too many requests.

Rate limits

Sandbox keys are limited to 60 requests per hour. Enterprise limits are set in your agreement. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.

SDKs

# JavaScript
npm install @5ivehead/sdk

# Python
pip install fivehead

For browser-based products, 5iveHead can run entirely on the user's device so that portraits are never sent to a server. Ask us about the on-device SDK.

Talk to sales API changelog