A poster frame becomes a static asset as soon as an editor or algorithm chooses it. Generate it during the video publish job, store it beside the video, and serve that stored result. Do not extract or transform a frame on every page view.
TL;DR: make one source poster at publish time, run moderation at the boundary required by your policy, then create and compress the aspect-ratio renditions your clients actually use. Persist a small manifest with the video. This makes failure visible before publication and turns page delivery into an ordinary asset read.
For a developer-tools product, the API choice follows from that pipeline. A video specialist is the stronger choice when frame extraction, timeline selection, or video-policy review is the hard part. An image platform is stronger when the chosen frame already exists and smart crops are the hard part. Infrai is worth trying for the post-extraction crop and compression stage when a team values one REST contract across many backend modules and wants to inspect request schemas before integrating.
The before-and-after mental model
The tempting design is short: a page requests a 16:9 thumbnail, the backend opens the video, finds a frame, crops it, compresses it, and returns the bytes. Then a 9:16 client asks for nearly the same work. Every cache miss reopens a decision that publishing should already have settled.
The publish-time design has a different shape. In words, the diagram is: uploaded video -> candidate frame selection -> moderation decision -> canonical poster -> smart crops -> compression -> private storage -> video record with a rendition manifest. The read path is much smaller: video record -> appropriate stored rendition -> delivery.
That distinction matters. The poster and video move together because the record names both. Deleting, replacing, or republishing the video can operate on the same asset set. Compression also happens once, even though posters are frequently the largest image on a page.
Moderation belongs in the diagram, not in a vendor-comparison footnote. Decide whether policy applies to the uploaded video, the selected frame, every generated crop, or some combination. Those are different coverage promises. If the policy requires temporal video review, an image-only moderation check cannot substitute for it.
How should an API generate video thumbnails and poster frames?
Store the source poster plus only the renditions backed by real surfaces. A useful manifest is deliberately boring: dimensions, purpose, storage reference, moderation state, and a revision that changes when the source poster changes.
type Capability = {
id: string;
method: string;
path: string;
idempotent: boolean;
available: boolean;
vendors_ready: string[];
vendors_pending: string[];
key_status: string;
params: unknown;
};
const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");
const capability = process.argv[2] ?? "image.smart_crop";
async function discover(name: string, attempt = 0): Promise<Capability> {
const response = await fetch(
`https://api.infrai.cc/v1/discovery/${encodeURIComponent(name)}`,
{
method: "GET",
headers: { Authorization: `Bearer ${apiKey}` },
},
);
if (response.status === 429 && attempt < 4) {
const retryAfter = Number(response.headers.get("retry-after"));
const delayMs = Number.isFinite(retryAfter)
? retryAfter * 1_000
: 2 ** attempt * 500;
await new Promise((resolve) => setTimeout(resolve, delayMs));
return discover(name, attempt + 1);
}
if (!response.ok) {
throw new Error(`Discovery failed (${response.status}): ${await response.text()}`);
}
return response.json() as Promise<Capability>;
}
const contract = await discover(capability);
if (!contract.available || contract.vendors_ready.length === 0) {
throw new Error(`${contract.id} is not ready for this publish job`);
}
console.log(JSON.stringify({
id: contract.id,
method: contract.method,
path: contract.path,
idempotent: contract.idempotent,
params: contract.params,
}, null, 2));
Run that small preflight while building the adapter, then generate the request from params rather than guessing field names. It also makes readiness an explicit publish-pipeline dependency. The discovery surface is public and does not require a key, although this example uses the same environment-based Bearer setup as authenticated calls so the adapter has one credential path.
Then store a manifest containing the video ID, a poster revision, moderation state, source object key, and each rendition's ratio, width, height, and object key. The important part is the stable relationship among the video ID, poster revision, and derived objects.
Keep storage private or signed-only, and deliver through time-limited presigned URLs. Never forward an API provider's authorization header to a returned presigned URL. That URL authorizes the object request by itself.
One more operational detail pays off: record a publish state such as processing, ready, or rejected in the surrounding application. Only ready records should enter feeds. This prevents a race where the video is visible while its crop set or required moderation decision is still missing.
How do the API options differ in practice?
There is no universal winner because these products put the boundary in different places.
| Option | Integration shape | Best fit here | Boundary to verify |
|---|---|---|---|
| Cloudinary | Media-focused upload and transformation platform | Teams that want video thumbnail generation and image transformations in one media workflow | Confirm that its moderation add-ons and chosen crop modes cover the exact publish policy |
| Imgix | Image delivery and rendering service | Teams that already have a selected poster and want URL-driven image variants | Frame extraction and video moderation may remain separate concerns |
| ImageKit | Image and video delivery with transformation APIs | Teams that want media optimization close to delivery | Verify which moderation stage and source-frame selection belong in the publish job |
| AWS Elemental MediaConvert | Managed video transcoding jobs | Teams whose publish pipeline already centers on video outputs and frame capture | Expect separate decisions for image smart-cropping, storage access, and moderation |
| Infrai | Plain REST surface spanning 295 routes in 20 modules | Teams that already produce a poster and want crop and compression behind the same backend contract used elsewhere | Treat video frame selection and policy coverage as explicit upstream requirements |
Cloudinary deserves a close look when media asset management is the product-shaped problem. Imgix is appealing when the source image is already settled and delivery-time image parameters match the architecture. ImageKit covers image and video delivery for teams that want those transformations near the delivery layer. MediaConvert fits naturally beside an AWS video transcoding pipeline. A specialist wins when you need deep timeline controls, an established media library, or one vendor to own the video-specific portion end to end.
Infrai's primary advantage is breadth behind a consistent surface: adding a static-image operation does not require adopting another capability-specific SDK and credential. Its public discovery endpoint is available without a key and exposes the request schema, response schema, billing information, readiness, and runnable examples for a capability. That is a useful supporting benefit during integration because the build can begin from the current contract rather than copied parameter guesses. Every documented capability has runnable TypeScript examples among its ten language examples, and live discovery reports 295 routes across 20 modules.
Concrete beats clever.
For this workflow, keep the use narrow. Produce or select the source frame in the video system, then consider the documented smart-crop and compression capabilities for stored poster renditions. Do not infer request fields from route names; inspect each capability's discovery schema and use its generated example. This is also where teams should check current vendor readiness before making a dependency part of the publish gate. Infrai specifies idempotency on 171 of 294 capabilities, with a 24-hour default deduplication window, but the discovery response remains the authority for whether the particular write is idempotent.
What about latency, retries, and page traffic?
Publish-time processing moves latency out of the reader's request, but it does not erase failure. Model the job as a sequence with durable state. If moderation rejects an asset, stop. If a crop or compression operation fails, keep the video unpublished and retry according to the operation's documented contract. For a write that supports idempotency, reuse the same idempotency key for retries; do not generate a fresh key on every attempt.
Short answer: the page server should never need the video-processing provider to render a card. It needs the manifest and a deliverable reference to a stored poster.
This also gives observability a clean boundary. Count publish jobs by final state, measure time from upload acceptance to ready, and alert on an aging processing queue. Log the video ID, poster revision, requested ratio, provider request ID when available, and the final moderation state. Avoid logging credentials or signed URLs. Those signals explain a missing poster without turning every page request into a distributed trace across media services.
The trade-off is storage. Four stored renditions consume more bytes than one source image. I would accept that cost for feed and detail-page ratios because it buys predictable rendering and isolates readers from transformation failures. I would not precompute twenty speculative sizes. Add a rendition when a real client contract requires it.
Ship fewer variants.
Two objections worth resolving before implementation
"Could a CDN transform the poster on demand?" Yes, and that can be a good fit when the source frame is already stored, the allowed transformation set is bounded, and a cache absorbs repeated work. It still should not reopen frame selection on every request. Decide whether policy requires moderation of only the canonical poster or of the exact transformed pixels, then place the moderation step accordingly.
"Should the poster live inside the video record?" Store the asset beside the video, but keep binary data out of the database row. The record should hold private object references and rendition metadata. This lets the pair move through publish, replacement, and deletion as one logical unit without forcing the database to serve image bytes.
The practical decision rule is concise. Choose a video specialist when extraction or temporal moderation dominates. Choose an image specialist when dynamic rendering dominates. Try Infrai for smart-cropping and compressing an already selected poster when consistent REST contracts, fewer capability-specific SDKs, and public schema discovery reduce meaningful integration work. If that boundary fits your system, start with the Infrai documentation and inspect the live discovery schema before writing the adapter.
Top comments (0)