Async Task Model

Most Weydub API capabilities are asynchronous. A create request returns task IDs immediately, and rendered media, subtitle files, or image results become available later.

Create

Submit a task to a create endpoint such as:

POST /v-w-c/gateway/ve/work/free

The response contains:

Persist these IDs in your own system before returning success to your user.

Lifecycle

submitted -> processing -> succeeded | failed | timed_out

For video tasks, processStatus is the terminal source of truth:

Image task status values can be queried through POST /v-w-c/enum/query2 with {"text":"ImageTaskStatus"}. The enum endpoint does not require signing.

Poll

POST /v-w-c/gateway/ve/work/status

Example body:

{
  "idWorks": [488026661]
}

Use a reasonable polling interval, such as 10 seconds for demos. Production systems should prefer callbacks and keep polling as a fallback.

Callback

Pass a callback URL when creating a task:

{
  "urls": ["https://example.com/demo.mp4"],
  "callback": "https://your-domain.example/webhooks/weydub",
  "needChineseOcclude": 1,
  "videoInpaintLang": "all"
}

When processing completes, Weydub pushes the result payload to your server.

Callback format:

Treat callback handling as production infrastructure:

• Verify the payload shape before updating your own job state.
• Verify Callback-Sign with the raw request body and your AppSecret.
• Make callback processing idempotent by work ID or image task ID.
• Store the raw callback payload for audit/debugging.
• Return HTTP 200 plus non-empty body only after durable storage succeeds.
• Keep polling as a fallback for missed callbacks.

Callback Signing

Weydub sends a header:

Callback-Sign: 86376328b7a9dce9e5b1691aa660a8e0

Verify it with the same signing logic used for API requests:

expected = md5(md5(raw_callback_body) + AppSecret)

Compare expected with the Callback-Sign header. Strong verification is recommended for all production webhook handlers.

Retry Mechanism

If callback delivery fails, Weydub retries failed callbacks for tasks created within the last 24 hours about every 30 minutes.

Because callbacks can repeat, all handlers must be idempotent. Use a unique work ID or image task ID as the deduplication key.

Some redo or retry endpoints can regenerate media after a failure or after manual edits. If video or image content changes, the corresponding output URL can also change. Always store the newest URL from the latest successful callback or status result.

Output Fields

Depending on the workflow, a successful video task can include:

Image tasks can include image task ID, task status, original image metadata, OCR/translation result JSON, and rendered output assets. Use the query path confirmed for your account or the callback payload when image callbacks are enabled.

Billing And Retention Notes

• Video workflows are billed in 30-second units.
• Combined services can stack costs.
• Final failed tasks (processStatus > 1) deduct zero credits.
• API-generated data follows Weydub web retention rules. By default, source files and rendered outputs for the last 30 days are retained.
• Download and transfer important videos, subtitles, and images to your own storage after callback.

Agent Contract

An automation agent should model Weydub jobs as:

submitted -> processing -> succeeded | failed | timed_out

Rules:

• Do not treat task creation as completion.
• Do not read result URLs until a task reaches a success status.
• Do not retry failed tasks blindly; surface errorDetail and workflow payload.
• Make task creation idempotent on your side when users may click or call twice.
• Persist callback payloads and output URLs before reporting success to users.
• Verify Callback-Sign and never expose AppSecret.