Designing an Async Image API Client That Does Not Lie About Completion

Image generation is where a seemingly simple API client starts to accumulate production bugs. A request may finish inline for one model, return a task for another, or take a longer path when the input includes edits and uploaded files. Treating every successful HTTP response as a completed image is the fastest way to ship broken retry logic and incorrect user-facing status. This post adapts the TokenLab article TokenLab Async Image Generation Tasks for Production Apps . The canonical article contains the full implementation discussion; this version focuses on the contract decisions that matter when building an integration. The response is a delivery decision, not just a payload An image endpoint can return either a completed representation or an asynchronous task. The client should inspect the response envelope and normalize the delivery mode before it touches application state: type Delivery = | { mode : " sync " ; terminal : true } | { mode : " async " ; task_id : string ; status : string ; terminal : false }; The important invariant is that mode and terminal state come from the API contract. Do not infer completion from a missing progress field, a truthy data property, or a fast response time. Progress is useful when present, but it is not the completion signal. Poll by task identity, not by the original request When the server returns an async task, persist the task ID and the provider-neutral status. A worker can then poll the task endpoint with bounded backoff: async function waitForTask ( id : string ) { for ( let attempt = 0 ; attempt < 60 ; attempt += 1 ) { const task = await getTaskStatus ( id ); if ( task . status === " succeeded " ) return task . result ; if ([ " failed " , " cancelled " , " expired " ]. includes ( task . status )) { throw new Error ( `Media task ${ id } ended as ${ task . status } ` ); } await sleep ( Math . min ( 1000 * 2 ** Math . min ( attempt , 5 ), 30 _000 )); } throw new Error ( `Media task ${ id } exceeded the polling budget` );