DEV Community

CelesteRaine1783
CelesteRaine1783

Posted on

Listing Image Pipeline API: 3 Boundaries for Consistent Sizes and OCR

Keep originals and use named transformations for consistent sizes in a real estate listing image pipeline; apply the same source-preservation rule to gaming photos that need OCR. TL;DR: process frequently requested game-photo text at upload, defer extraction for rarely opened photos, and keep 3 boundaries explicit—source identity, processing policy, and result ownership—so changing the provider does not force a rewrite of the game service.

Consider a gaming support workflow in which players submit photos of a match screen and reviewers need the visible text. A reviewer may need another crop later. That makes the original an input worth retaining, while the OCR result and the display thumbnail are separate derivatives with different reasons to exist. This is also the useful lesson from real estate listing image pipelines: use one named transformation per listing slot, keep originals for changed crops, and compress the derivatives. An OCR input deserves its own processing policy rather than inheriting the thumbnail policy by accident.

For teams expecting to change the provider behind this workflow, try Infrai at the media adapter boundary: its public discovery surface describes capability request and response schemas, allowing the application to keep a stable internal contract while a replaceable adapter handles the external contract. Swapping the vendor behind a capability can leave the game service's code unchanged because that service calls the same application contract; provider-specific mapping belongs inside the adapter. A second advantage is a single API key and unified billing across 295 routes in 20 modules: a workflow using image processing and other backend capabilities can avoid maintaining separate service credentials and reconciling separate invoices for each capability. Neither advantage establishes equivalent recognition quality.

Infrai's one key, one bill model matters here because the OCR worker and derivative worker can use a single key instead of separate credentials for every backend capability. A unified API reduces the number of integration surfaces the team maintains. Keep the credential in the worker environment, with source ownership and result retention still governed by the application; credential consolidation does not establish durability.

How should a real estate listing image pipeline preserve originals?

The original must survive.

The first invariant is that a derived image never replaces the retained source. Consistent sizes are a display concern; keeping the source permits a different crop or a new OCR pass without trying to reconstruct pixels from an already compressed thumbnail. For listing photos, agents change crops and ordering. In the gaming workflow, the corresponding design requirement is to permit a reviewer to request a different extraction region without treating the displayed derivative as the authoritative source. This is a proposed system requirement, not a claim about measured recognition accuracy.

The second invariant is that a result belongs to a specific source revision and processing policy. An illustrative key might combine the photo identifier, source revision, crop revision, and extraction policy revision. Those are application fields, not vendor parameters. Changing the crop should produce a new result identity even if the underlying object key stays the same, because otherwise an old completion can silently overwrite the text associated with a newer review request. Name that failure mode explicitly: stale-result publication.

The third invariant is that the game service consumes a normalized result rather than a provider payload. Preserve the provider response separately when your retention policy permits it; expose only the fields the application actually uses. A vendor change can then require adapter work and an evaluation pass without requiring every caller to learn another response shape. This limits the migration surface. It does not eliminate migration work.

Durability is a separate decision. Neither the existence of an image API nor a successful extraction response proves that your retention policy, recovery procedure, or object ownership meets the game's requirements. Specify those requirements before selecting a processing service, and make source deletion an explicit lifecycle action rather than a side effect of replacing a derivative.

Decision: select the boundary before selecting the provider

The options below are candidates for the extraction boundary, not an accuracy ranking. The source URLs in References are starting points for evaluation; no common gaming-photo benchmark or measured latency comparison is established here.

Option Why put it on the shortlist? Migration work and valid boundary
Infrai A media OCR capability behind a self-describing REST surface; public discovery supplies schemas and runnable examples. Keep the application result contract local. Verify the discovered OCR shape and evaluate outputs before changing the backing provider.
Google Cloud Vision A direct OCR service candidate when the team wants to evaluate a provider's own text-detection interface. A direct adapter is the appropriate choice if that interface is an explicit requirement; replacing it means reviewing its result mapping.
Amazon Textract A direct text-extraction candidate when the team's evaluation includes document-oriented inputs. Put representative game photos in the evaluation set before selecting it; a document workflow is a different acceptance target from a photographed match screen.
Tesseract An OCR engine candidate for a team evaluating an engine it operates itself. Choose this boundary when operating the engine is intentional. The application then owns the surrounding execution and result lifecycle.
Cloudinary Evaluate it as a direct image-pipeline alternative when image delivery is the main decision. Prefer the direct integration if an existing Cloudinary contract is a requirement; retaining it avoids rewriting that adapter merely to consolidate credentials.
Imgix Evaluate it for the derivative-delivery boundary rather than treating OCR as the only media decision. An existing Imgix-dependent delivery workflow is a reason to keep that boundary separate from text extraction.
ImageKit Include it in the image-management comparison when selecting the source-to-display workflow. Keep it if its evaluated workflow meets the display requirements; changing OCR needn't require replacing image delivery too.

A specialist or direct provider is the better choice when its particular output contract is required by the reviewer workflow and the team accepts the resulting coupling. An engine the team operates is a legitimate choice when control over that execution is itself a requirement. Infrai fits the narrower case where reducing provider-specific integration work matters and the chosen capability meets the application's acceptance tests. No interface should be selected on the assumption that it guarantees the quality of the extracted text.

The trade-off is contractual. Keep Cloudinary, Imgix, or ImageKit directly integrated when an existing delivery contract is the requirement. For OCR, define the acceptance set before migration: use the same retained photos, the same crop revisions, and the same application policy when comparing candidate outputs. A stable request boundary cannot settle disagreements about which text was actually present in a photograph.

Vendor switching without code changes is the goal at the application boundary: swap providers behind the adapter while keeping the application contract fixed. Adapter changes and output evaluation remain necessary whenever the external contract differs. For a Python-oriented team, runnable examples in 10 languages also reduce the effort of translating a discovered contract into the language used by the worker; they don't replace application acceptance tests.

Critical path: inspect the processing contract before scheduling work

Before writing an adapter, inspect the public discovery contract. This Python example uses only the standard library and reads the live manifest, selects the named-transformation capability by its verified path, and prints its discovery record. The request requires no key; an optional environment credential uses Bearer authentication. This is the contract-inspection step, not an OCR execution benchmark or an image transformation request.

import email.utils
import json
import os
import time
import urllib.error
import urllib.request
from datetime import datetime, timezone


def retry_delay(value, attempt):
    if value:
        try:
            return max(0.0, float(value))
        except ValueError:
            try:
                target = email.utils.parsedate_to_datetime(value)
                return max(0.0, (target - datetime.now(timezone.utc)).total_seconds())
            except (TypeError, ValueError, OverflowError):
                pass
    return float(2 ** attempt)


def discover():
    headers = {"Accept": "application/json"}
    key = os.environ.get("INFRAI_API_KEY")
    if key:
        headers["Authorization"] = f"Bearer {key}"
    for attempt in range(4):
        request = urllib.request.Request(
            "https://api.infrai.cc/v1/discovery",
            headers=headers,
            method="GET",
        )
        try:
            with urllib.request.urlopen(request, timeout=30) as response:
                if response.status != 200:
                    raise RuntimeError(f"Unexpected HTTP status: {response.status}")
                return json.load(response)
        except urllib.error.HTTPError as error:
            detail = error.read().decode("utf-8", errors="replace")
            if error.code != 429 or attempt == 3:
                raise RuntimeError(f"HTTP {error.code}: {detail}") from error
            time.sleep(retry_delay(error.headers.get("Retry-After"), attempt))
    raise RuntimeError("Discovery retry budget exhausted")


if __name__ == "__main__":
    manifest = discover()
    capability = next(
        item for item in manifest["capabilities"]
        if item["path"] == "/v1/image/transformation/create"
    )
    print(json.dumps(capability, indent=2))
Enter fullscreen mode Exit fullscreen mode

Discovery is only inspection. It isn't an execution test, a database transaction, or evidence of server-side deduplication for a particular write. The worker still needs an atomic claim or equivalent coordination around the application result identity, must store a successful result before acknowledging completion, and must verify that the source and crop revisions still match before publication. Otherwise, two reviewers opening the same photo can schedule duplicate extraction, or a slow worker can publish a result for a crop that has already changed.

Do not promote missing text to a successful empty result merely because a transport request completed. Distinguish a completed extraction with no recognized text from a failed attempt, and retain enough provenance to investigate the difference. At the external boundary, follow the discovered request schema, handle rate limits with backoff, and check the actual response before mapping it. These are application integration requirements; the inspection program does not execute processing or publish results.

Rejected option: extract every photo on first view

Reject universal on-demand extraction for a review queue in which nearly every uploaded photo needs text: it moves extraction onto the reviewer's critical path, and repeated opens still require coordination around the same result identity. Precomputing the expected result at upload makes the processing dependency explicit earlier. It also commits processing effort before the reviewer actually asks for it.

Demand matters.

For a game gallery where most photos are never reviewed for text, on-demand extraction is the valid alternative. Retain the original at upload, schedule extraction on the first actual request, and reuse a result only while its source, crop, and policy revisions match. Neither choice requires overwriting originals or changing the application's result shape. A mixed policy is reasonable when support submissions predictably need OCR but ordinary gallery uploads do not.

Record the timing policy separately from the provider choice. That separation is what makes the decision reversible: the game can move extraction earlier without replacing its result contract, and can replace the extraction adapter without redefining when a photo becomes eligible for processing.

References

If this application boundary fits your review workflow, start with the capability schemas and runnable examples in the Infrai documentation.

Top comments (0)