Fit to spec
Fit to spec API
Fit a product or dish photo to the listing spec of a marketplace or delivery app without redrawing it. $0.02 per image, charged only when an image comes back.
https://serastudio.app/api/v1/fitSend a photo you took and a target. A main image target cuts the product out and centers it on pure white at the share of the frame that marketplace asks for. A dish photo target crops the photo to the app ratio and keeps the whole dish in frame. Every output pixel comes from your photo, resized or cropped, or is the white background.
Usage notes
- The key needs the create permission. Keys created in the console have it.
- Upload the photo first with Create upload (
content_typeimage/jpegorimage/png). Send the full-size photo, not a screenshot or a thumbnail: a small photo is enlarged and the report says so. - One request is one photo and one target. The answer comes back in the same request, usually within 10 to 20 seconds. Allow up to 3 minutes.
- $0.02 per image is charged when the image comes back. A photo the target cannot use (no subject found, too small, a ratio that would cut the dish) returns
422and charges nothing. So does a failure on our side (503). - Send an
Idempotency-Keyheader (1 to 255 ASCII characters). A retry with the same key and body returns the first answer without charging again. output.urlworks for 60 minutes. The file is kept for 7 days; a retry with the same key returns a fresh URL until then.- The report lists what was measured. It cannot tell you whether a marketplace will accept the listing, so check the result against the real item before you post it.
Quick start
curl https://serastudio.app/api/v1/fit \
-H "Authorization: Bearer $SERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: listing-0417" \
-d '{"target": "amazon", "image": {"upload_id": "img_…"}}'import os, requests
r = requests.post(
"https://serastudio.app/api/v1/fit",
headers={"Authorization": f"Bearer {os.environ['SERA_API_KEY']}", "Idempotency-Key": "listing-0417"},
json={"target": "amazon", "image": {"upload_id": "img_…"}},
timeout=180,
)
r.raise_for_status()
print(r.json()["output"]["url"])const res = await fetch('https://serastudio.app/api/v1/fit', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SERA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'listing-0417',
},
body: JSON.stringify({ target: 'amazon', image: { upload_id: 'img_…' } }),
});
const fit = await res.json();
console.log(fit.output.url);Input schema
targetstringrequiredWhere the image will be posted. See the targets below.
imageobjectrequiredThe photo: {"upload_id": "img_..."} from Create upload. JPEG or PNG, shorter side at least 300 pixels.
Targets
target | Name | What the output follows | Output |
|---|---|---|---|
coupang | Coupang | Pure white, product fills 95%, 2000×2000 (min 1000) | image/png |
gmarket | Gmarket | Pure white, product fills 80%, 1000×1000 (min 600) | image/png |
amazon | Amazon | Pure white, product fills 85%, 2000×2000 (min 1000) | image/png |
walmart | Walmart | Pure white, product fills 85%, 2200×2200 (min 1500) | image/png |
ebay | eBay | Pure white, product fills 85%, 1600×1600 (min 500) | image/png |
tiktok_shop | TikTok Shop | Pure white, product fills 85%, 2000×2000 (min 600) | image/png |
mercado_libre | Mercado Libre | Pure white, product fills 95%, 1200×1200 (min 500) | image/png |
kaufland | Kaufland | Pure white, product fills 95%, 2048×2048 (min 1024) | image/png |
google_shopping | Google Shopping | Pure white, product fills 85%, 1500×1500 (min 500) | image/png |
white_square | White square | Pure white, product fills 85%, 2000×2000 (min 1000) | image/png |
baemin | Baemin | 4:3, at least 1280×960 | image/jpeg |
coupang_eats | Coupang Eats | 4:3, at least 1280×960 | image/jpeg |
yogiyo | Yogiyo | 27:16, at least 1080×640 | image/jpeg |
doordash | DoorDash | 16:9, at least 1400×800, dish inside the centered square | image/jpeg |
lieferando | Lieferando | 4:3, at least 1280×960 | image/jpeg |
wolt | Wolt | 16:9, at least 1000×563 | image/jpeg |
uber_eats | Uber Eats | 5:4, at least 550×440 | image/jpeg |
grubhub | Grubhub | 1:1, at least 200×200 | image/png |
deliveroo | Deliveroo | 16:9, at least 1200×675, dish inside the centered square | image/jpeg |
just_eat | Just Eat | 4:3, at least 1280×960 | image/jpeg |
photo_4_3 | Dish photo 4:3 | 4:3, at least 1280×960 | image/jpeg |
photo_16_9 | Dish photo 16:9 | 16:9, at least 1400×800, dish inside the centered square | image/jpeg |
photo_1_1 | Dish photo 1:1 | 1:1, at least 1000×1000 | image/jpeg |
Each target follows the rules the marketplace or app publishes. Where a rule gives no number (how much of the frame the product fills, how large the dish is), we use the value of a similar target. A photo smaller than the minimum is enlarged at most 2 times and the report says so. DoorDash does not allow enlarging, so a smaller photo returns photo_small_for_target.
Response
{
"id": "6c1d9e2a-3b4f-4a5c-8d7e-9f0a1b2c3d4e",
"object": "fit",
"target": "amazon",
"status": "succeeded",
"created_at": "2026-11-09T05:15:00.000Z",
"output": {
"url": "https://rvzzbovxmjgldcnlbwyx.supabase.co/storage/v1/object/sign/episodes/7d9e2f10-4b3a-4c5d-8e6f-0a1b2c3d4e5f/api/fit/6c1d9e2a-3b4f-4a5c-8d7e-9f0a1b2c3d4e.png?token=<signed>",
"url_expires_at": "2026-11-09T06:15:00.000Z",
"content_type": "image/png",
"width": 2000,
"height": 2000,
"bytes": 1665840
},
"report": {
"size": [
2000,
2000
],
"fill": 0.85,
"fill_target": 0.85,
"background": 255,
"background_exact": true,
"off_center_px": [
0,
0
],
"scale": 0.59,
"upscaled": false,
"subject_cut": false,
"kind": "main",
"source": [
5061,
3374
],
"color_profile": false,
"generated_pixels": 0
},
"billing": {
"currency": "usd",
"charged_usd": 0.02
}
}outputobjecturl (signed, temporary), url_expires_at, content_type, width, height, bytes. Main images are PNG so the background is exactly white.
report.kindstringmain for a main image, menu for a dish photo.
report.fill, report.fill_targetnumberMain image: share of the frame the product fills along its long side, and the target value.
report.background_exactbooleanMain image: every background pixel is exactly white (255).
report.dish_share, report.dish_whole, report.tightnumber, booleanDish photo: share of the frame the dish fills, whether the whole dish is in frame, and whether the dish fills more than the target range because the photo is tight.
report.center_squarebooleanOnly on targets whose list shows a centered square thumbnail: whether the dish fits inside it.
report.upscaled, report.scaleboolean, numberWhether the photo was enlarged to reach the minimum size, and by how much.
report.subject_cutbooleanThe product or dish touches the edge of your photo, so part of it was already outside the frame.
report.generated_pixelsnumberAlways 0.
billing.charged_usdnumberThe amount charged for this image.
Errors
| Status | Code | When it happens | Retry |
|---|---|---|---|
400 | invalid_json | The body is not a JSON object. | No |
400 | invalid_idempotency_key | The Idempotency-Key header is empty, longer than 255 characters or not printable ASCII. | No |
401 | api_key_missing | No Bearer key was sent in the Authorization header. | No |
401 | api_key_invalid | The key is malformed or unknown. | No |
401 | api_key_revoked | The key was deleted in the console. | No |
401 | api_key_disabled | The key is disabled in the console. | No |
401 | api_key_expired | The key is past its expiration date. | No |
403 | insufficient_scope | The key lacks the create permission. Keys created in the console have it. | No |
403 | workspace_forbidden | The account that owns the workspace is suspended or scheduled for deletion. | No |
422 | invalid_parameter | target is missing or not one of the targets above. | No |
422 | invalid_parameter | image.upload_id is missing or is not an image upload. | No |
404 | not_found | The upload does not exist in this workspace, or no file was put to the upload address. | No |
402 | insufficient_balance | The workspace balance is below the price of one image. Nothing was made. | No |
422 | subject_not_found | No product or dish was found, for example a photo of a whole shop. Not charged. | No |
422 | photo_small_for_target | Reaching the minimum size would enlarge the photo more than allowed. Not charged. | No |
422 | dish_cut | The target ratio would cut a dish that is whole in your photo. Not charged. | No |
422 | photo_too_small | The shorter side is under 300 pixels. Not charged. | No |
422 | photo_format | The file is not JPEG, PNG or WebP. Not charged. | No |
422 | idempotency_key_mismatch | The same Idempotency-Key was already used with a different body. | No |
409 | request_in_progress | A request with the same Idempotency-Key is still running. | Yes |
410 | output_expired | The request with this Idempotency-Key finished more than 7 days ago and its file was deleted. | No |
503 | fit_unavailable | The photo could not be processed on our side. Not charged; send the same request again. | Yes |
503 | temporarily_unavailable | The request could not be completed just now. | Yes |
500 | internal_error | Something failed on our side. The request_id identifies the request. | Yes |
503 | api_unavailable | The API is turned off. | No |
A photo with no product in it, for example, returns 422 and charges nothing:
{
"error": {
"type": "invalid_request",
"code": "subject_not_found",
"message": "No product or dish was found in the photo.",
"fix": "Send a photo where the product or dish is the main subject.",
"charged": false,
"retryable": false
},
"request_id": "req_k38ss8hmb36g9308sy351ot3yi"
}