When integrating Seedance into a product, many teams first pick a relay or proxy endpoint: change the base URL and the key, and it looks simpler than connecting directly. But video generation is an asynchronous task, and a relay chain has more stages than a text API: persisting tasks, mapping statuses, copying results, and handling callbacks. If any one stage is thin, the symptom is always the same: "the task was submitted successfully, but the video never arrives."

This article starts from the actual chain of a relay service and explains task reliability, result retention, billing transparency, key risk, and how to accept a relay when migrating from a direct connection.

Note: Seedance is the name of a video generation model from ByteDance's Volcano Engine, and related trademarks belong to their respective owners. This article is for technical explanation only; it implies no affiliation or partnership with ByteDance. Interfaces, models, and prices are governed by official documentation and the on-site model pricing page.

1. Distinguish four kinds of "relay" first

Type What it does Main risk Suitable for
Reverse proxy Forwards requests to the official endpoint Single point, egress bandwidth, authentication configuration Teams with operations capability
Aggregation gateway One entry point that aggregates multiple providers Status mapping, parameter differences between models Multi-model products
Reseller / top-up service Resells upstream credits or pays on your behalf Upstream stability, terms of service Small trials, temporary needs
Self-hosted gateway You deploy and maintain the forwarding layer You carry all responsibility Teams with engineers and data-control needs

Whether you are buying "technical service" or "model credits" determines who is responsible when something breaks. Ask about contracts, invoices, and data-processing terms with that distinction in mind.

2. What extra stages async tasks add to a relay chain

Your service
  → Relay entry (authentication, rate limiting, billing)
  → Upstream creates the task and returns a task_id
  → Relay stores the mapping between task_id and business order number
  → Relay polls upstream or receives callbacks
  → Relay maps statuses and exposes a polling endpoint or webhook to you
  → You download the result and copy it to your own storage

Every extra hop is another place where state can be lost:

  • The relay restarts or changes instances, and in-memory task mappings disappear.
  • Upstream times out but the task was actually created; the relay returns a failure, the caller retries, and two jobs are generated.
  • Upstream reports expired, but the relay only maps success and failure, so the business side waits forever.
  • The relay caches the result URL behind its own address but does not fall back to the origin after the cache expires.
  • Webhook retries lack an idempotency key, so the business side inserts the same record twice.

When evaluating a relay, do not ask only "does it support Seedance?" Ask how task IDs are persisted, how statuses are mapped, and how failures are compensated.

3. Task status and result retention

According to the Volcano Ark documentation, Seedance task statuses typically include queued, running, succeeded, failed, cancelled, and expired. Task queries generally cover only the most recent 7 days, and the video URL in a successful result is usually cleaned up after 24 hours.

A relay service needs to add a layer on top of both limits:

  • Does it store task records? For how long? Can tasks still be queried after 7 days?
  • Does it download videos on your behalf? If it stores them, for how many days, and is there an extra charge?
  • Does it return the upstream temporary URL or a long-lived address of its own?
  • How are cancellation, timeout, and moderation rejection mapped into statuses?

If the relay only passes requests through, the caller still carries the 24-hour copy responsibility. If the relay hosts results, confirm the storage location, access permissions, and deletion mechanism. Either model can work; ambiguity cannot.

4. How to check billing transparency

Video task billing is more dispute-prone than text billing because failures, retries, and cancellations all happen in the asynchronous stage. Before signing, confirm:

  • Whether billing is by duration, by resolution, by task, or by token conversion.
  • Whether failures, timeouts, cancellations, and moderation rejections are billed.
  • Whether duplicate submissions and retries are charged twice, and whether idempotent deduplication exists.
  • Whether there is a minimum spend, prepayment threshold, refund policy, and invoice type.
  • Whether usage details include task ID, model, duration, resolution, status, and charged amount.

Do not rely on the discount advertised on a landing page. Run 20–50 small tasks over one week and reconcile successful tasks, failed tasks, and the invoice line by line. That is more reliable than any verbal assurance. Actual rates are governed by the on-site model pricing page.

5. Key and upstream risk

A relay means request content passes through a third party. At minimum, confirm:

  1. Whether prompts, first-frame images, and generated videos are written to disk, and for how long.
  2. Whether data is used for training or service improvement.
  3. Whether keys can be limited by quota, IP address, and expiry.
  4. How leaks or abuse are reported and how keys are revoked.
  5. Whether the upstream is a single channel or multiple channels, and how migration works if a model is retired.
  6. Whether the terms of service permit resale or agency, and where liability lies when something goes wrong.

Never put production keys in front-end code or public repositories. For highly sensitive material, prefer a provider that supports no-persistent-storage operation or will sign a data-processing agreement. If you cannot confirm the terms, do not upload unredacted customer material.

6. Steps for migrating from a direct connection to a relay

  1. Inventory existing calls: model IDs, parameters, concurrency, average latency, and failure types.
  2. Confirm the relay's endpoint paths, authentication method, and field differences, and write a mapping table.
  3. Exercise all four paths in a test environment: create, query, cancel, and download.
  4. Run a shadow period with the same task batch, one copy direct and one through the relay, comparing without switching traffic.
  5. Compare success rate, P95 latency, result download rate, and cost per clip.
  6. Shift traffic gradually at 5%–20%, keeping a switch back to the direct connection.
  7. Observe for 3–7 days and confirm that invoices reconcile with task details.
  8. After full cutover, keep dual channels for a while, then simplify the architecture once stability is confirmed.

During migration, do not delete the direct-connection key, and do not write both sets of tasks under the same business order number, or reconciliation becomes impossible.

7. How to validate a relay service

# 1. Submit a minimal task and record the task_id and submission time
curl -X POST "$RELAY_BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"the model ID in the relay documentation","content":[{"type":"text","text":"A cat yawning by a window"}]}'

# 2. Query every 10 seconds and record the full status transitions
curl "$RELAY_BASE_URL/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $RELAY_API_KEY"

Deliberately create anomalies during testing: cancel immediately after submission, pass a wrong model ID, submit concurrently, and disconnect mid-download. Observe whether the statuses, error messages, and billing returned by the relay are consistent. Then revisit the result URL after 24 hours to see whether it still downloads, and query the task again after 7 days to see whether the record still exists.

8. Monitoring and rollback after migration

  • Count tasks by status, focusing on the share of failed, cancelled, and expired.
  • Record total time from submission to success, separating queue time from generation time.
  • Monitor the result download success rate and maintain a compensation queue for failed downloads.
  • Track 401, 404, 429, and 5xx separately to distinguish key problems, model problems, and rate limiting.
  • Calculate "cost per successful video," not just the unit price per request.
  • Define a rollback threshold, for example switching back to the direct connection if the success rate stays clearly below baseline for two consecutive hours.

FAQ

Does a relay offer the same model capability as a direct connection?

It depends on whether the relay forwards the same upstream model and parameters. Model IDs, duration, resolution, audio, and other capabilities may differ. Before integrating, compare outputs and supported parameters with the same prompt.

Will a relay store my videos?

It varies by service. Ask whether data is written to disk, how long it is kept, where it is stored, who can access it, and how deletion works. When customer material is involved, prefer a provider with clear terms.

What if a task is lost on the relay side?

First look up the local record by business order number, then check the relay logs and the upstream task. If it cannot be recovered, the only option is to resubmit. That is why you should confirm before migrating whether the relay persists task mappings and supports lookup by business order number.

Why does the invoice not match the task count?

Common causes include duplicate submissions, retries after failure, different cancellation rules, minimum spend, and cache hits. Ask for a per-task billing breakdown and reconcile line by line rather than looking only at the total.

Does migration require code changes?

If the relay is compatible with OpenAI or the official task interface, usually only the base URL, key, and a few fields change. If status mapping or callback formats differ, you also need to change polling and persistence logic. A shadow run catches most differences in advance.

Next steps

Create a test key in the ZSQH AI Gateway, validate the four links of creation, polling, download, and billing with a minimal task, and then migrate gradually. Models and rates are governed by model pricing.

Related reading: