The 5iveHead API
Add portrait optimisation to your product with a single request.
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
Create a portrait
| 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.
// 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.