API docs | Forkcast

Quick start

Sign in, create a key on the API keys page, and send a photo to the API you need, for example POST /v1/food. Every API takes the photo the same way and answers with JSON. Call the API from your server, not from a browser or a mobile app bundle.

curl https://ourapi.keronlabs.com/v1/food \
  -H "Authorization: Bearer $FORKCAST_KEY" \
  -F image=@lunch.jpg \
  -F context="I ate about half"

APIs

Endpoint	What it returns	Price
POST /v1/food	Each food on the plate with its weight in grams, and calories and macros from USDA FoodData Central.	$0.01
POST /v1/skin	Scores for acne, wrinkles, spots, redness, pores and more from one selfie, with skin type and ingredient suggestions.	$0.01
POST /v1/body	A physique score, a body fat range, muscle development by group, V-taper and posture, with training focus.	$0.01
POST /v1/color	Personal color analysis: the 12-season type, undertone and contrast, with a fixed palette to wear and avoid.	$0.01
POST /v1/plant	Species from a photo, checked against GBIF, with health problems, treatment steps, pet toxicity and care.	$0.01
POST /v1/label	Nutrition table, ingredients, Nutri-Score, NOVA group, additives and allergens from a photo of a food or cosmetic label.	$0.01

GET /v1/engines returns the same list as JSON, with every API's parameters. It needs no key.

Authentication

Send your key as Authorization: Bearer fk_live_…. You can also pass it as an api_key query parameter, but the header keeps it out of server logs. Keys are shown once when you create them; revoke a key from the dashboard and it stops working at once.

Sending a photo

Field	Type	Description
`image`	file (multipart)	The photo. JPEG, PNG, WebP or GIF, up to 5 MB.
`image_base64`	string (JSON)	The photo as base64. A data: URL prefix is accepted and stripped.
`media_type`	string (JSON)	MIME type of `image_base64`. Defaults to `image/jpeg`.
`image_url`	string	A public http(s) URL of the photo, as a JSON or multipart field.

Each API also takes its own optional fields, such as the user's age or what they ate. They go next to the photo, as form fields or JSON keys, and are listed on each API's page. Facts the user gives are trusted over what the photo shows.

Response

Every response has a metadata object (id, engine, cached, credits_used, processing_ms) and a one-line summary you can show in a list, followed by the API's own fields. Skin, body and color responses include a quality object with a reliability rating and photo warnings.

GET /v1/account

Returns the account balance and this key's usage for the month. It is free to call.

{
  "balance_usd": 8.42,
  "scans_left_on_balance": 842,
  "key": { "scans_this_month": 158, "monthly_limit": 1000 }
}

Errors

Errors come back as { "error": { "code", "message" } }. You are only charged for a 200.

Status	Code	Meaning
400	`missing_image`	No photo in the request.
400	`invalid_param`	A field is outside its allowed values. The message says which.
400	`invalid_image`	The photo could not be read.
401	`invalid_api_key`	Missing, unknown or revoked key.
402	`insufficient_credit`	The account is out of credit.
404	`unknown_engine`	No API at that path.
413	`image_too_large`	Over 5 MB.
415	`unsupported_media_type`	Not JPEG, PNG, WebP or GIF.
422	`no_face`	Skin or color: no face in the photo.
422	`minor_detected`	Body: the person looks under 18.
422	`refused`	The image cannot be analyzed.
429	`key_limit_reached`	The key hit its monthly limit. Raise it in the dashboard.
429	`rate_limited`	More than 60 calls a minute on one key. Back off and retry.
502 / 503	`upstream_error`	The vision model failed or is busy. Retry.

Billing and limits

Each successful new call costs the price listed with its API, drawn from prepaid credit. An identical request (same photo, same fields) is served from cache for free and marked cached: true. Every key can have a monthly call limit, which resets on the 1st of the month (UTC). Set one for each app so a bug or a leaked key can only spend so much. The rate limit is 60 calls a minute per key.