# Integrating Seedance 2.5 Through an Asynchronous Video API

This guide covers request validation, job tracking, safe retries, result downloads, and billing reconciliation for an asynchronous video-generation API. The service discussed here, 无限扩散 at api.wxksai.com, is a third-party API gateway, not the model publisher. Confirm current model availability, limits, and pricing in the official API docs and model catalog before production use.

Contents

# 1. Confirm the model and credential scope

Use the exact model ID shown in the live catalog. The current catalog describes seedance-2.5-special2 as a 5–30 second, fixed 1080P model, with up to nine reference images and three audio references; it does not accept reference video. These limits are model-specific and may change.

Create a server-side API key with only the model access and quota your application needs. Send it in the Authorization: Bearer … header. Keep it in a secret manager or server environment variable; never embed it in browser JavaScript, a mobile app, source control, or public logs.

# 2. Validate before submitting

Validate the complete model ID, supported duration, resolution, aspect ratio, prompt length, and reference-media limits before making a paid request. For this model, the current documentation lists 5–30 seconds, fixed 1080P, no reference video, and up to nine reference images plus three audio references. Do not assume another Seedance model has the same capabilities.

Validate file type and size on your server. Avoid logging file contents, API keys, or signed media URLs. When using reference assets, follow the current docs for the selected model’s upload format and field names.

# 3. Submit one job and save its ID

The current unified API guide documents video generation at POST https://api.wxksai.com/v1/videos. A JSON request can look like this:

curl -X POST 'https://api.wxksai.com/v1/videos' \
  -H 'Authorization: Bearer YOUR_SERVER_SIDE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "seedance-2.5-special2",
    "prompt": "A quiet harbor at sunrise, slow camera movement",
    "seconds": "10",
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }'

Store the returned task ID against your own request record. If the client times out after sending the request, first check whether your server received and saved the response. Do not blindly send a second generation request: it could create another paid job.

# 4. Poll the same task

Use the returned task ID with the documented query endpoint. The unified video API reports these states:

queued: waiting to start; keep waiting.
in_progress: generation is running; keep waiting.
completed: generation succeeded; download the result.
failed: inspect the error and task details before deciding whether to retry.

The API guide recommends polling no more frequently than every 30 seconds. Use a bounded retry policy with jitter and a maximum overall wait. An HTTP timeout by itself does not prove the generation task failed.

# 5. Download and validate the result

After the task reaches completed, download the result using the same authorized key and task ID. Stream it to storage rather than holding a large video in application memory. Check the HTTP status, content type, byte length, and decodability before exposing it to your users. Result links are time-limited, so copy successful outputs to storage you control promptly.

# 6. Reconcile usage and protect retries

Keep a request ledger with your application request ID, gateway task ID, selected model ID, submission time, terminal state, download outcome, and billed amount. Reconcile it against account usage records instead of estimating from a display name. Model prices and availability can change; check the live catalog and actual billing records.

When a task fails, classify the error before retrying. Fix invalid parameters and missing permissions first. For transient network errors, query the same task before resubmitting. Make your own retry handling idempotent so a double-click or client reconnect cannot launch duplicate paid work.

# Official references

This is an independent integration note. It does not claim affiliation with the Seedance model publisher. Specifications and pricing should be checked against the linked official pages and actual account billing.

End