ModelsFit to spec

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.

POSThttps://serastudio.app/api/v1/fit

Send 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_type image/jpeg or image/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 422 and charges nothing. So does a failure on our side (503).
  • Send an Idempotency-Key header (1 to 255 ASCII characters). A retry with the same key and body returns the first answer without charging again.
  • output.url works 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_…"}}'

Input schema

targetstringrequired

Where the image will be posted. See the targets below.

imageobjectrequired

The photo: {"upload_id": "img_..."} from Create upload. JPEG or PNG, shorter side at least 300 pixels.

Targets

targetNameWhat the output followsOutput
coupangCoupangPure white, product fills 95%, 2000×2000 (min 1000)image/png
gmarketGmarketPure white, product fills 80%, 1000×1000 (min 600)image/png
amazonAmazonPure white, product fills 85%, 2000×2000 (min 1000)image/png
walmartWalmartPure white, product fills 85%, 2200×2200 (min 1500)image/png
ebayeBayPure white, product fills 85%, 1600×1600 (min 500)image/png
tiktok_shopTikTok ShopPure white, product fills 85%, 2000×2000 (min 600)image/png
mercado_libreMercado LibrePure white, product fills 95%, 1200×1200 (min 500)image/png
kauflandKauflandPure white, product fills 95%, 2048×2048 (min 1024)image/png
google_shoppingGoogle ShoppingPure white, product fills 85%, 1500×1500 (min 500)image/png
white_squareWhite squarePure white, product fills 85%, 2000×2000 (min 1000)image/png
baeminBaemin4:3, at least 1280×960image/jpeg
coupang_eatsCoupang Eats4:3, at least 1280×960image/jpeg
yogiyoYogiyo27:16, at least 1080×640image/jpeg
doordashDoorDash16:9, at least 1400×800, dish inside the centered squareimage/jpeg
lieferandoLieferando4:3, at least 1280×960image/jpeg
woltWolt16:9, at least 1000×563image/jpeg
uber_eatsUber Eats5:4, at least 550×440image/jpeg
grubhubGrubhub1:1, at least 200×200image/png
deliverooDeliveroo16:9, at least 1200×675, dish inside the centered squareimage/jpeg
just_eatJust Eat4:3, at least 1280×960image/jpeg
photo_4_3Dish photo 4:34:3, at least 1280×960image/jpeg
photo_16_9Dish photo 16:916:9, at least 1400×800, dish inside the centered squareimage/jpeg
photo_1_1Dish photo 1:11:1, at least 1000×1000image/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
  }
}
outputobject

url (signed, temporary), url_expires_at, content_type, width, height, bytes. Main images are PNG so the background is exactly white.

report.kindstring

main for a main image, menu for a dish photo.

report.fill, report.fill_targetnumber

Main image: share of the frame the product fills along its long side, and the target value.

report.background_exactboolean

Main image: every background pixel is exactly white (255).

report.dish_share, report.dish_whole, report.tightnumber, boolean

Dish 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_squareboolean

Only on targets whose list shows a centered square thumbnail: whether the dish fits inside it.

report.upscaled, report.scaleboolean, number

Whether the photo was enlarged to reach the minimum size, and by how much.

report.subject_cutboolean

The product or dish touches the edge of your photo, so part of it was already outside the frame.

report.generated_pixelsnumber

Always 0.

billing.charged_usdnumber

The amount charged for this image.

Errors

StatusCodeWhen it happensRetry
400invalid_jsonThe body is not a JSON object.No
400invalid_idempotency_keyThe Idempotency-Key header is empty, longer than 255 characters or not printable ASCII.No
401api_key_missingNo Bearer key was sent in the Authorization header.No
401api_key_invalidThe key is malformed or unknown.No
401api_key_revokedThe key was deleted in the console.No
401api_key_disabledThe key is disabled in the console.No
401api_key_expiredThe key is past its expiration date.No
403insufficient_scopeThe key lacks the create permission. Keys created in the console have it.No
403workspace_forbiddenThe account that owns the workspace is suspended or scheduled for deletion.No
422invalid_parametertarget is missing or not one of the targets above.No
422invalid_parameterimage.upload_id is missing or is not an image upload.No
404not_foundThe upload does not exist in this workspace, or no file was put to the upload address.No
402insufficient_balanceThe workspace balance is below the price of one image. Nothing was made.No
422subject_not_foundNo product or dish was found, for example a photo of a whole shop. Not charged.No
422photo_small_for_targetReaching the minimum size would enlarge the photo more than allowed. Not charged.No
422dish_cutThe target ratio would cut a dish that is whole in your photo. Not charged.No
422photo_too_smallThe shorter side is under 300 pixels. Not charged.No
422photo_formatThe file is not JPEG, PNG or WebP. Not charged.No
422idempotency_key_mismatchThe same Idempotency-Key was already used with a different body.No
409request_in_progressA request with the same Idempotency-Key is still running.Yes
410output_expiredThe request with this Idempotency-Key finished more than 7 days ago and its file was deleted.No
503fit_unavailableThe photo could not be processed on our side. Not charged; send the same request again.Yes
503temporarily_unavailableThe request could not be completed just now.Yes
500internal_errorSomething failed on our side. The request_id identifies the request.Yes
503api_unavailableThe 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"
}