How to Get Result

Retrieve results from completed WaveSpeedAI tasks.

Endpoint

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

Request

curl --location --request GET 'https://api.wavespeed.ai/api/v3/predictions/pred_abc123' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}'

Response (Processing)

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

Response (Completed)

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "pred_abc123",
    "model": "wavespeed-ai/flux-dev",
    "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

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
Image tasks	At least 2 seconds between checks
Video tasks	At least 5 seconds between checks

For long-running tasks, use an increasing interval instead of fixed high-frequency polling. For example, check after 2 seconds, then after 5 seconds, and gradually increase the interval while the task is still created or processing.

Stop polling as soon as the task reaches a terminal status such as completed, failed, or your own timeout. 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
 
api_key = os.environ.get("WAVESPEED_API_KEY")
 
def get_result(task_id, max_wait=300):
    """Poll for result with timeout."""
    url = f"https://api.wavespeed.ai/api/v3/predictions/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
 
    start = time.time()
    poll_interval = 2
    max_interval = 30
 
    while time.time() - start < max_wait:
        response = requests.get(url, headers=headers)
        data = response.json()["data"]
 
        if data["status"] == "completed":
            return data["outputs"]
        elif data["status"] == "failed":
            raise Exception(data.get("error", "Unknown error"))
 
        time.sleep(poll_interval)
        poll_interval = min(max_interval, poll_interval * 1.5)
 
    raise Exception("Timeout waiting for result")
 
# 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