How to Get Result

Retrieve results from completed WaveSpeedAI tasks.

Endpoint

GET https://api.wavespeed.ai/api/v3/predictions/{task-id}/result

Request

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

Response (Processing)

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "pred_abc123",
    "model": "wavespeed-ai/z-image/turbo",
    "status": "processing",
    "outputs": [],
    "created_at": "2024-01-01T12:00:00.000Z"
  }
}

Response (Completed)

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "pred_abc123",
    "model": "wavespeed-ai/z-image/turbo",
    "status": "completed",
    "outputs": [
      "https://cdn.wavespeed.ai/generated/image123.png"
    ],
    "timings": {
      "inference": 2500
    },
    "created_at": "2024-01-01T12:00:00.000Z"
  }
}

Response (Failed)

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "pred_abc123",
    "status": "failed",
    "error": "Error message here",
    "created_at": "2024-01-01T12:00:00.000Z"
  }
}

Status Values

Status	Description	Action
`created`	Task queued	Continue polling
`processing`	Generation in progress	Continue polling
`completed`	Success	Get outputs
`failed`	Error occurred	Check error field
`cancelled`	Task cancelled	Stop polling
`timeout`	Execution timed out	Stop polling

Task Result Polling Frequency

After submitting a task, use the result query endpoint to check task status and retrieve the final output. To keep integrations stable, avoid high-frequency polling for the same task ID.

Recommended polling intervals:

Task type	Recommended interval
All prediction types	At least 2 seconds between checks

Start at 2 seconds. For long-running tasks, gradually increase the interval to 5–10 seconds while the task remains created or processing.

Stop polling as soon as the task reaches completed, failed, cancelled, timeout, or your own client deadline. The result query endpoint is intended for task status retrieval, not for millisecond-level or multiple-times-per-second probing.

Sustained high-frequency polling may trigger platform rate limiting, traffic control, or alerting. If rate limiting is triggered, requests may be rejected, responses may slow down, or result synchronization may become less stable for your application.

Polling Example

import os
import requests
import time
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
 
api_key = os.environ["WAVESPEED_API_KEY"]
 
def get_result(task_id, max_wait=300):
    """Poll safely, retrying only transient GET failures."""
    url = f"https://api.wavespeed.ai/api/v3/predictions/{task_id}/result"
    headers = {"Authorization": f"Bearer {api_key}"}
    session = requests.Session()
    session.mount("https://", HTTPAdapter(max_retries=Retry(
        total=5,
        backoff_factor=0.5,
        status_forcelist=(429, 500, 502, 503, 504),
        allowed_methods={"GET"},
        respect_retry_after_header=True,
    )))
 
    deadline = time.monotonic() + max_wait
    poll_interval = 2.0
 
    while time.monotonic() < deadline:
        response = session.get(url, headers=headers, timeout=(10, 30))
        response.raise_for_status()
        body = response.json()
        if body.get("code") != 200:
            raise RuntimeError(body.get("message", "Result query failed"))
        data = body["data"]
 
        if data["status"] == "completed":
            return data["outputs"]
        if data["status"] in {"failed", "cancelled", "timeout"}:
            raise RuntimeError(data.get("error") or f"Task ended with {data['status']}")
 
        time.sleep(poll_interval)
        poll_interval = min(10.0, poll_interval + 1.0)
 
    raise TimeoutError(f"Timed out waiting for prediction {task_id}")
 
# Usage
outputs = get_result("pred_abc123")
print(outputs[0])

Output Fields

Field	Type	Description
`outputs`	array	URLs to generated content
`timings.inference`	integer	Generation time in ms
`error`	string	Error message (if failed)

Alternatives to Polling

Webhooks — Receive notifications. See How to Use Webhooks
Streaming — Real-time updates. See How to Use Streaming
Python SDK — Auto-polling. See Python SDK

Error Codes List Models