Designing a Reliable Async Pipeline for the Seedance 2.5 API

Description and use

Guide to designing a reliable async pipeline for the Seedance 2.5 API. Covers task modeling, idempotency keys to prevent duplicates, input validation, and asset lifecycle management via a job queue system.

Problem

Long-running video generation tasks are prone to production failures such as duplicate submissions after timeouts, polling storms, expired result URLs, and lost ownership between the task and the user when treated as simple HTTP requests.

Outcome

A reliable integration pattern is established that prevents duplicate charges, handles transient errors gracefully, and ensures asset persistence through explicit task modeling and idempotent retries.

Workflow

• Model the task explicitly: Store internal request ID, provider task ID, model parameters, user owner, status, attempt count, timestamps, and output URLs.
• Use idempotency keys: Derive keys from the internal request ID to prevent duplicate paid generations on client retries.
• Separate submission from completion: Implement a worker loop that polls the provider with bounded exponential backoff and jitter.
• Handle terminal states: Update job status to 'succeeded' (copying asset to durable storage) or 'failed' (normalizing error codes) based on provider response.
• Validate references before submission: Verify file type, size, duration, dimensions, and downloadability of user uploads to avoid expensive failures.
• Normalize parameters: Standardize aspect ratio, duration, resolution, and audio flags at the API boundary.
• Design UX for uncertainty: Return internal job ID immediately, support polling or SSE, and display distinct states (queued, generating, finalizing, completed, failed).
• Operate for retries: Retry transport failures and transient 5xx responses using the same idempotency key; do not retry invalid prompts or moderation decisions.
• Manage asset lifecycle: Copy provider results to durable storage, generate thumbnails, and run media checks during the 'finalizing' state.

Evidence

Long-running video generation should be treated as a job system, not a slow HTTP request.

Source

Use an idempotency key derived from the internal request, not from the prompt alone.

Source

Poll with bounded exponential backoff and jitter.

Source