A 7-Stage Image Artifact Contract for Portable Media Hiring SaaS
When a media hiring SaaS must compare image generation APIs, the expensive mistake is treating generation as a single request that returns a URL. A candidate-scoring workflow needs a durable artifact contract: prompt intent, provider request, binary output, policy result, and rubric evidence must remain understandable after the underlying API changes.
Short answer: put a provider-neutral job record in front of every image API, store the resulting bytes under your own immutable object key, and make the scoring service consume that record rather than a vendor response. Compare providers on the shape and survivability of that record first. A lower request price is irrelevant if a rerun cannot reproduce which input produced the portfolio image being scored.
This matters in a media application where a recruiter uploads a candidate’s sample brief, asks for a visual concept, and scores the candidate against a rubric such as composition, brand interpretation, and delivery discipline. The generated image is evidence in a workflow, not the workflow itself.
Why does a portable artifact contract matter?
Image APIs expose different request semantics, output representations, moderation behavior, and operational limits. Your application still needs one answer to a boring question: what exactly did the scorer inspect?
A provider response is usually a transient boundary object. It may contain a URL, an encoded payload, an identifier, or an asynchronous job status. Those forms have different retention and retry implications. Storing the response verbatim as the canonical record couples the hiring decision to that boundary. Storing only the final image loses the prompt, model settings, policy decision, and request lineage.
I start with an internal record that can survive a provider replacement. The record is deliberately less clever than most SDK abstractions:
from dataclasses import dataclass
from typing import Any
@dataclass(frozen=True)
class ImageArtifact:
artifact_id: str
candidate_id: str
rubric_version: str
prompt: str
provider: str
provider_request_id: str | None
status: str
media_type: str | None
object_key: str | None
sha256: str | None
policy_state: str
created_at: str
metadata: dict[str, Any]
The provider field is evidence, not a routing decision. The scorer can use it for analysis, but it should not need to know how that provider names a model or returns an image. rubric_version deserves equal status: if the rubric changes from version 3 to version 4, a later reviewer must be able to distinguish a new judgment from a new rendering.
The contract also creates a clean boundary for 429 handling. HTTP 429 means the client sent too many requests in a given period; MDN describes it as a rate-limit response and notes that a Retry-After header may indicate how long to wait. That is a scheduling signal, not proof that the image job failed permanently.
Do not retry a request merely because the network connection closed after submission. First reconcile it using your idempotency key or provider request identifier. Otherwise one candidate brief can produce two images, and the scorer may quietly evaluate the one that arrived last.
The seven stages that keep the record intact
The stages are a state machine, not seven mandatory API calls. Some providers complete several stages in one response; your system should still preserve the transitions.
- Capture intent. Persist the candidate, source brief, actor, consent or policy reference, and rubric version before calling an external service. Normalize whitespace and retain the original text separately if the distinction matters for review.
- Freeze the request. Store a canonical request document containing the prompt, selected size or aspect ratio, requested output type, and application policy version. Hash this document. A mutable Python dictionary is not an audit trail.
- Submit once. Generate an application idempotency key from the artifact identifier and frozen request hash. The adapter translates that request into provider-specific fields.
- Reconcile status. Represent
queued,running,succeeded,rejected, andunknownexplicitly.unknownis essential after a timeout; it prevents the queue from treating uncertainty as permission to duplicate work. - Acquire bytes. Fetch the completed output, verify the declared media type, calculate a cryptographic digest, and write the bytes to an application-owned object key. A remote result URL is a transport detail, not durable storage.
- Apply policy and rubric inputs. Run content checks and attach the rubric version used by the scoring job. Keep policy state separate from score state: a technically valid image can still be ineligible for evaluation.
- Publish an evidence bundle. The scorer receives the artifact ID, immutable object reference, digest, prompt hash, provider request ID, and policy state. It should not receive an SDK response object.
The crucial failure mode is a half-committed record. If bytes exist but the database still says running, a reconciliation worker should be able to verify the object digest and complete the record. If the database says succeeded but the object is missing, the workflow needs a visible repair state. Silent deletion is worse than a failed job because it corrupts confidence in the score.
What should the adapter hide, and what must remain visible?
The adapter hides syntax. It must not hide facts that affect evidence. This is the useful split:
| Concern | Keep behind the adapter | Persist in the application record |
|---|---|---|
| Request vocabulary | Provider field names and SDK types | Canonical prompt and normalized options |
| Delivery | Polling, callback parsing, transient retry | State transitions and timestamps |
| Output | URL or encoded response handling | Object key, media type, byte digest |
| Limits | Provider-specific quotas and backoff mechanics | Attempt count, last error class, next retry time |
| Governance | Provider policy response shape | Policy state and policy version |
| Attribution | Provider identifiers | Provider name and request identifier |
A small interface is enough. Its job is to force every integration to return the same application facts, not to pretend that providers have identical capabilities.
from typing import Protocol
class ImageProvider(Protocol):
def submit(self, request: dict[str, object], key: str) -> str:
...
def reconcile(self, provider_job_id: str) -> dict[str, object]:
...
def fetch_bytes(self, provider_job_id: str) -> tuple[bytes, str]:
...
def provider_request(request: dict[str, object], adapter: ImageProvider) -> str:
key = f\"{request['artifact_id']}:{request['request_hash']}\"
return adapter.submit(request, key)
The interface intentionally does not promise identical controls. If one API supports a particular image size and another does not, the normalized request should record the requested capability and the adapter should return a typed incompatibility. Converting every difference into a default is how portability becomes a false sense of safety.
How should SaaS teams compare image generation APIs for hiring?
The comparison becomes clearer after the contract exists. OpenAI’s image API documentation describes image generation from a text prompt and image editing capabilities. Stability AI documents image generation services around Stable Diffusion models and related controls. Midjourney has historically centered its service on its own web and Discord experiences and has not offered the same official general-purpose API contract as those API-first services. DALL-E and Stable Diffusion therefore belong in the adapter test matrix, while Midjourney needs a separate check for automation terms and interface availability. Confirm the current terms and interfaces before committing an integration; that boundary is precisely why the adapter must be replaceable.
| Service family | Integration boundary | Portability implication |
|---|---|---|
| OpenAI image generation | Documented API request and image result flow | Map documented request options into the canonical request; preserve the returned request identifier when available |
| Stability AI / Stable Diffusion services | API-accessible generation around Stable Diffusion model capabilities | Capability negotiation matters because model and parameter availability can vary by endpoint |
| Midjourney | Product workflow historically centered outside a general public image-generation API | Treat it as a separate workflow integration unless an official interface and terms support the required automation |
This table is not a quality ranking. It answers a narrower engineering question: can the service participate in the evidence lifecycle your SaaS needs, with a documented interface and a retrievable result? A service can produce excellent images and still be a poor fit for an unattended candidate-scoring pipeline.
There is a real limitation to this abstraction: it cannot make missing capabilities appear. If an API does not expose a required size, edit operation, retention guarantee, or automation permission, the adapter should reject the job or route it to a human review queue. Silently approximating the request preserves uptime while weakening the candidate score.
That trade-off is intentional. A portable contract costs a little storage and adapter code, but a direct SDK call costs historical evidence each time its response shape changes.
The cheapest advertised path also does not settle the decision. Measure the complete unit of work: accepted submissions, successful byte acquisition, storage, moderation, retries, and human review of ambiguous results. Keep those measurements internal and time-bounded; public prices and available models change, while a lost artifact remains lost.
Rollout without binding the scoring system to one provider
Start with a fixture suite made from representative media briefs, not random prompts. For each fixture, assert the contract fields, output digest, policy state, and scorer input shape. Do not assert that two providers produce pixel-identical images; that would test the wrong property. Assert that every accepted result can be traced to one frozen request and one immutable object.
Run the first adapter in shadow mode. Submit a bounded sample, retain the provider response as diagnostic metadata, and make the canonical record the only object consumed by scoring. Compare queue latency, unknown-state recovery, rejection rates, and manual review volume. A provider that is quick on the happy path may create more operational work at reconciliation time.
Then make selection a configuration decision at the job boundary. New jobs choose an adapter version; existing artifacts retain their original provider and request facts. This avoids the dangerous migration pattern where changing one environment variable changes the meaning of historical scores.
For a media hiring workflow, the final decision rule is compact: choose the service that can satisfy the artifact contract, the policy requirements, and the recovery behavior at an acceptable total operating burden. The image API is replaceable infrastructure. The evidence chain is the product.
Top comments (0)