Sync Mode (enable_sync_mode)

This document explains the difference between asynchronous mode and synchronous mode, plus the limits and risks of using enable_sync_mode in API requests.

Parameter Definition

Async Mode vs Sync Mode

By default, WaveSpeedAI uses asynchronous mode.

When enable_sync_mode = true:

• The API attempts to return the final result in the same request.
• If the task finishes during the sync wait window, the response includes output URLs or results.
• If the task is still running after the wait window, the raw REST response can be HTTP 200 OK with body fields that identify the sync wait timeout: status: "processing" and code: 5004.
• The timeout body includes the prediction ID and result URL when available.
• The task continues on the server after the timeout response.

When enable_sync_mode = false (default):

• The API returns immediately with a task ID.
• Results must be retrieved by polling, webhook callback, or SDK auto-polling.
• The task can continue safely even if your first HTTP request disconnects.

Response Behavior

Completed During the Wait Window

If the result is ready quickly enough, the response is terminal and includes generated outputs:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "pred_abc123",
    "model": "wavespeed-ai/example-model",
    "outputs": ["https://..."],
    "status": "completed",
    "created_at": "2026-06-17T00:00:00Z"
  }
}

Still Running After the Wait Window

If the task is still running, the response is a sync timeout body. The prediction itself is not failed; it continues processing and can be queried later.

For raw REST calls, this response uses HTTP 200 OK so clients can still parse the prediction ID and result URL from the response body. Detect the timeout using the body, especially data.code: 5004 and data.status: "processing".

The wait window is currently about 120 seconds, but it may vary by endpoint, model, or infrastructure. Treat the returned status and code as the source of truth.

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "pred_abc123",
    "model": "wavespeed-ai/example-model",
    "outputs": [],
    "status": "processing",
    "created_at": "2026-06-17T00:00:00Z",
    "code": 5004,
    "error": "Sync mode timed out while the prediction is still processing.",
    "urls": {
      "get": "https://api.wavespeed.ai/api/v3/predictions/pred_abc123/result"
    }
  }
}

Use the data.urls.get value, or GET /api/v3/predictions/{task-id}/result, to retrieve the final result.

SDKs and the CLI may surface this body as a timeout error for ergonomics. The important fields are still the same: keep the prediction ID and poll the result URL when available.

Refund and Waiting Policy

Sync mode changes how your client waits for the result, but it does not change how the underlying task is billed.

If a sync-mode request is accepted and the task continues running or completes successfully, no refund is issued simply because the sync wait returned code: 5004, or because your client did not receive the final response in time. This includes cases where the response is delayed or interrupted by your local network, proxy, browser, client timeout, gateway timeout, or other connection instability.

Please wait patiently and retrieve the result with the prediction ID. If your application uses sync mode in production, store the returned prediction ID whenever it is available so you can query:

GET /api/v3/predictions/{task-id}/result

Refunds are only handled for eligible failed requests or system-side failures. A client-side timeout, network interruption, or disconnected sync response is not by itself proof that the prediction failed.

See Refund Policy for the general refund rules.

Limitations and Risks

Inference times can fluctuate significantly depending on the model, input complexity, queue depth, upstream compute availability, output upload time, and network conditions.

Sync mode may cause these issues:

Common Issue: Timeout in Sync Mode

Example Scenario

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "pred_abc123",
    "status": "processing",
    "code": 5004,
    "outputs": [],
    "urls": {
      "get": "https://api.wavespeed.ai/api/v3/predictions/pred_abc123/result"
    }
  }
}

This means the sync wait timed out, not that the prediction failed. The task may still be running or may later complete successfully.

Do not assume a sync timeout means the task failed or that it is automatically refundable. Check the prediction status first:

curl --fail-with-body --connect-timeout 10 --max-time 60 --request GET 'https://api.wavespeed.ai/api/v3/predictions/pred_abc123/result' \
  --header "Authorization: Bearer ${WAVESPEED_API_KEY}"

If the status is created or processing, poll again starting around 2 seconds later and increase the interval for long-running tasks. If the status is completed, read the outputs. Stop on failed, cancelled, or timeout and inspect the error when present.

Best Practices

• Use async mode by default for production systems.
• Use sync mode only for models and inputs that usually finish quickly.
• Set your client timeout above the expected sync wait window if you want to receive the timeout body with the prediction ID and result URL.
• Preserve the prediction ID for recovery whenever it is returned.
• Do not automatically retry sync requests after transport errors unless your application can prevent duplicate submissions.
• Use webhooks for long-running tasks when your application needs completion notifications.
• Use SDK polling if you want a simple blocking call while still relying on async task recovery internally.

Related Pages

• How to Submit Task
• How to Get Result
• How to Use Webhooks
• Refund Policy