Async Media Workflow

Use async task mode for media requests that can run longer than a normal HTTP request window.

Flow

1. Submit a media generation request with async: true.
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 inspecting upstream provider internals.

User experience

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