From part photo to listing: the image route through the tapinomahub API

Growing an online parts business rarely fails on stock and almost always on data entry. The part is out, the number is printed on the type plate, and minutes still disappear into retyping, category hunting and background removal. The image route of the tapinomahub API reverses the order: the photo is not the last thing added to a listing, it is the first thing the listing grows out of.

What the image route requires

• A retrievable image address. The image services accept imageUrl, not an uploaded file. The picture therefore has to sit in your storage, your shop or a signed object store and be retrievable — a time-limited address is enough.
• A photo that carries information. A 200-pixel thumbnail contains no readable type plate. Load the largest version you have, not the one your catalogue displays.
• The right to the image. By submitting you confirm that you are permitted to transmit it for automated processing. Personal content — a number plate in the background, for instance — needs a legal basis and should, where possible, be kept out of the frame.
• A decision on the processing level. quality accepts standard, enhanced and maximum. The levels differ in scope and response time; what each level costs follows your agreement.

Step 1: read the label

POST /scanner/label/extract-all analyses a label photo and returns every attribute recognised with sufficient certainty in a structured form — not just the part number. It is the most substantial call of the whole route and replaces most of the manual work. Usage and billing details are covered in Extract all detectable label information.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: part-4711-label' \
  -d '{"imageUrl":"https://example.com/control-unit.jpg","quality":"maximum"}' \
  'https://api.tapinomahub.com/scanner/label/extract-all'

Step 2: turn a reading into a number you can rely on

A string read off a label is not yet an OE number. It may carry hyphens the catalogue does not know, be a supplier number, or match several manufacturers. Two calls settle that before anything is stored.

1. `GET /parts/oe/normalize` checks the notation and answers with status: matched, unresolved, ambiguous or invalid. On a match the response carries normalizedOeNumber, lookupKey, matchRule and confidence, plus equivalentOeNumbers with equal notations. See Normalize and validate an OE number.
2. `POST /parts/identify` decides when several sources are involved. The call takes the customer number, the step 1 reading as labelReadings and — where available — the donor vehicle's VIN. It returns status with matched, candidates or unresolved, plus source with customer, label or vin_parts_list and a candidate list with score and reasons.
3. With `candidates` a human decides. The list is ranked and names its reasons; it is a shortlist, not a determination. This is exactly where a review queue belongs in the ERP, not an automatic transfer.
4. With `unresolved` the field stays empty and the record gets a task. An unidentified part can be photographed, stored and identified later — it is not listed.

Step 3: the part record behind the number

With a confirmed number, GET /parts/oe/{oeNumber} returns the name, the manufacturer, the vehicle assignments in fitment, the documented replacement edges in replacementChain and the reference numbers grouped by manufacturer in references. This part of the route is the one From the OE number to a marketplace-ready article describes in full — including each field's meaning and why a reference number never becomes a fitment statement.

Step 4: the gallery image

The first image decides the click. POST /vision/part/remove/bg cuts out the component and returns a PNG: with background: "transparent" an alpha channel, with background: "white" a pure white field. The default is transparent, because white can be placed behind an image afterwards but never removed again. The call is described in Remove the background from a part photo.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"imageUrl":"https://example.com/bumper.jpg","background":"transparent","partType":"front bumper"}' \
  'https://api.tapinomahub.com/vision/part/remove/bg'

• `found` states whether an object was recognised at all. If it is false, imageUrl is null — and the listing keeps its original photo instead of showing an empty frame.
• `coverage.cropped` and `coverage.touchesImageEdge` report that the object runs past the edge of the frame. Such photos should be retaken, not published.
• `sourcePixelsPreserved` confirms that the object's pixels come from the submitted photo. The procedure determines the outline; it does not repaint the part.
• `limitations` names what remained uncertain — an edge in shadow, for example. That note belongs on the approval checklist.
• `422 part_segmentation_failed` is the honest answer when the component could not be separated reliably from the background or adjacent surfaces. No half-cut image is returned.

Step 5: identifiers that do not belong online

Control units, instrument clusters and keys carry numbers that do not describe the part type but the individual item: serial numbers, IMEI, calibration codes, data matrix fields. POST /vision/identifiers/redact makes them unreadable and only returns an image when redaction could be confirmed — otherwise 422 identifier_redaction_unverified and no image at all. Why that matters commercially and legally is set out in Anonymising identifiers on part images without losing the OE number.

Step 6: the condition the buyer wants to see

POST /vision/part/quality takes one to three photos of the same component and returns a grading: grade with A, B or C, the individual criteria in criteria — wear, corrosion, deformation, scratches, paint condition, completeness, soiling — plus reworkEffort and refinishEffort as effort classes. visualOnly makes clear what the judgement rests on: what can be seen. A gearbox with metal shavings inside looks unremarkable from outside. If the image is unsuitable for grading, the response carries gradable: false with an explanation in reason, and no grade is guessed. More in Assessing used parts from images: condition, damage and limits.

What the route costs and how it behaves

• The analysis is the service. An image service that runs and answers has delivered — even when the photo showed no number. A failure is refunded, an empty finding is not. That is the reason to sort out blurred photos beforehand instead of discussing them afterwards.
• `Idempotency-Key` protects against double charging. A repeat with the same key returns the same result without running again. While the first call is still running, the API answers 409 idempotency_request_in_progress.
• One call per client at a time. Further parallel requests are rejected with 429 client_request_in_progress. A queue in the ERP is therefore mandatory, not polish.
• `402 insufficient_credits` means no plan covers the endpoint and balance plus overdraft are not enough. The X-Tapinoma-Usage-Warning header warns before that, from 90 per cent plan usage.
• Results belong in your database. No call on every page view, no second lookup for the same article. The fields from steps 1 to 3 do not change while the part stays the same.

Integrating it into ERP, shop and marketplace

1. Define the photo routine: one picture of the component, one of the type plate, both at the highest resolution, both under a retrievable address.
2. Call step 1 and store the answer in full, not just the part number. The remaining fields belong to this order's response and later answer questions nobody is asking today.
3. Run step 2 and record the outcome as matched, candidates or unresolved — with confidence and source, so that the origin of the number stays explainable.
4. Fetch part data and marketplace data, then map the fields to your article fields. That mapping is the real work of an integration, not the call.
5. Create the images: the cut-out gallery image and, for electronics, the redacted version as well. Put both files in your own storage instead of linking to the response address.
6. Draw the approval line: anything published automatically needs a confirmed number, an image with found: true and a condition grade. Everything else goes to the review queue.
7. Measure after two weeks: handling time per article, share of the review queue, correction rate after publication, returns due to wrong fitment.

Limits you need to know

• No image delivers fitment. The assignment comes from the confirmed number and the reference data, not from the photo. A usage list is documentation, not an assurance.
• Hidden damage stays hidden. The grading is explicitly visual. Assemblies need a functional test as well — and that test belongs in the item description.
• Manufacturer and brand names are references, not an origin claim. A used part is described as one. Misleading statements about essential characteristics are unlawful under German unfair competition law, whatever data source they came from.
• Marketplace data is publication content, never a fitment statement. Before publishing, the business checks what it publishes — title, category and item specifics alike.
• Coverage is not the same everywhere. Rare series and very old parts carry less reference data. An empty list is information about the data, not a statement about the part.

Complete schemas, error codes and example responses are in the developer documentation. If you want to build the same article from the number or from the vehicle instead of the image, see From the OE number to a marketplace-ready article and From the VIN to the economic evaluation: the vehicle route.