Async Media Workflow

Use task mode for media requests that can run longer than a normal HTTP request window. Image and video generation endpoints return task envelopes.

Flow

1. Submit an image or video generation request.
2. Store the returned task ID.
3. Poll GET /v1/tasks/{taskId}.
4. Stop when the task reaches success or fail.
5. Persist result URLs or download generated assets promptly.

Suggested polling policy

attempt 1: wait 1 second
attempt 2: wait 2 seconds
attempt 3: wait 4 seconds
attempt 4+: wait 8 to 15 seconds with jitter

Failure handling

Show a useful error message and keep the task ID visible in logs. Failed tasks should include enough normalized information to help support or operators diagnose the issue without exposing internal routing details.

User experience

For product flows, avoid blocking a page indefinitely. Persist the task and let users return to the result later when possible.