
Keep FastAPI media operations recoverable by storing them durably and letting an external worker reconcile Imagild task IDs. FastAPI's in-process background task facility can run work after a response, but it should not be the only record of paid generation that must survive an application restart.
The FastAPI background-task guide describes the feature and points to larger worker tools for work spanning processes or servers. Durability still depends on the queue, database and recovery policy you implement.
Key Takeaways
- Commit operation identity and a durable submission event before returning acceptance.
- Keep provider task IDs and exact retry parameters outside process memory.
- Use worker retries to recover the same logical work, not to generate a fresh paid request automatically.
Define an authenticated intake boundary
Your FastAPI endpoint accepts a small application request, validates it and stores an operation. The example uses current Pydantic-style configuration and an image-only request to keep the boundary explicit.
The authentication dependency and store function are application helpers you implement. They are not Imagild framework integrations.
from typing import Literal
from fastapi import FastAPI, Depends
from pydantic import BaseModel, ConfigDict, Field
from your_app.auth import require_user
from your_app.operations import commit_operation_and_outbox
app = FastAPI()
class ImageDraft(BaseModel):
model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
model: Literal["gpt-image-2.5", "nano-banana-pro", "nano-banana-2.1"]
prompt: str = Field(min_length=1, max_length=4000)
resolution: Literal["1K", "2K", "4K"] = "1K"
@app.post("/media-operations", status_code=202)
def create_operation(draft: ImageDraft, user=Depends(require_user)):
operation = commit_operation_and_outbox(user.id, draft.model_dump())
return {"operation_id": str(operation.id)}
The helper must enforce spending approval, assign or reuse a logical operation identity, and atomically persist the operation with an outbox event. Add your request-size and browser-security policies at the application boundary.
The local route above is not an Imagild endpoint. Its response uses a local operation ID rather than pretending the provider has already returned data.id.
Let a durable worker cross the network
The worker reads the frozen request and sends raw JSON to POST /images/generations on the base URL https://imagild.com/api/relay/v1 with Bearer authentication and its saved Idempotency-Key. On HTTP 202 it commits the returned data.id.
The Imagild API console is the product contract. Current public image choices support 1K, 2K and 4K at 10, 15 and 20 points; active membership is required separately. The application should discover current availability through the model hub rather than assume this example's allowlist never changes.
If the worker loses the response, it retains the original operation identity and unchanged parameters for recovery. An automatically generated new key would change the operation instead of recovering it.
Make restart behavior observable
Record the submission attempt time, provider task ID when known, latest task status and usage state. A worker that restarts can distinguish an unsent operation from one with an uncertain receipt.
For a known task, perform bounded authenticated GET reads. For an uncertain submission without an ID, recover with the saved key and body. If the task is unknown, retain it for reconciliation rather than making another paid image or video.
Do not treat a failed FastAPI process as evidence that the remote task failed. Do not hold one database transaction open while waiting for remote generation to finish.
Reserve in-process tasks for work with an acceptable loss model
A background callback can be suitable for noncritical telemetry or a best-effort notification when you have explicitly accepted its failure mode. It is different from your sole durable record of a paid operation.
If you use a persistent queue, verify its acknowledgment and retry configuration. Calling a component “a worker” does not automatically make it durable or exactly once.
Test the failure boundaries
Using mocks, stop the web process after the outbox commit, stop the worker after provider acceptance, and restart it after task-ID persistence. Confirm that one operation survives and that the original idempotency key remains unchanged.
Test unauthorized reads of another user's operation as well. The failed-job guide supports recovery messaging, while the points planning guide keeps deliberate retakes separate from restarting existing work. These are application acceptance tests, not a paid FastAPI-to-Imagild benchmark.
Related tasks
- What Should You Check Before Retrying a Failed Image or Video Job?
- Imagild Points, Resolution and Jobs: Plan a Creation Before You Spend
Sources and scope
- Imagild API console: Active-member access, supported media request fields, idempotency, asynchronous task records and authenticated downloads; checked against the 2026-10-28 relay contract.
- FastAPI Background Tasks: Post-response task facility and guidance to consider external worker tooling across processes/servers; durable outbox is an application design.
Product instructions were checked against the current Imagild API contract and the public model catalog. Code, budgets and acceptance checks are illustrative; this article does not claim a new paid generation test, an uptime measurement, a search-volume study or a ranking of AI citations.
Prepared by Imagild Editorial, the company editorial team responsible for these guides. AI assisted research and drafting. This is documentation-based guidance with proposed examples, not a claim of hands-on testing or an independent product review. Report a correction.
Cover: Original Imagild product screenshot captured on 28 October 2026; model availability and prices may change. This image is not an API response or a performance benchmark.