REST API

WaveSpeedAI provides a RESTful API for programmatic access to 1,000+ AI models.

Base URL

https://api.wavespeed.ai/api/v3

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer ${WAVESPEED_API_KEY}

Get your API key at wavespeed.ai/accesskey. Store it as an environment variable for security.

Basic Workflow

Submit a task — Send a POST request with your parameters
Get the task ID — Returned in the response
Poll for results — Check status until completion, using a reasonable interval
Retrieve outputs — Get URLs to generated content

For result polling, start around 2 seconds and increase toward 5–10 seconds for long-running tasks. Avoid polling the same task more often than every 2 seconds, and stop on completed, failed, cancelled, timeout, or your own client deadline.

Example Request

# Submit task
curl --fail-with-body --connect-timeout 10 --max-time 60 \
  --request POST 'https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
--data-raw '{
  "prompt": "A cat wearing a space suit",
  "size": "1024*1024"
}'
 
# Get result (use the task ID from response)
curl --fail-with-body --connect-timeout 10 --max-time 30 \
  --retry 4 --retry-all-errors --retry-delay 1 \
  --request GET 'https://api.wavespeed.ai/api/v3/predictions/TASK_ID/result' \
--header "Authorization: Bearer ${WAVESPEED_API_KEY}"

Response Format

Task Submission Response

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "task-abc123",
    "status": "created",
    "urls": {
      "get": "https://api.wavespeed.ai/api/v3/predictions/task-abc123/result"
    }
  }
}

Task Result Response

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "task-abc123",
    "status": "completed",
    "outputs": ["https://..."],
    "timings": {
      "inference": 2500
    }
  }
}

Task Status Values

Status	Description
`created`	Task received
`processing`	Generation in progress
`completed`	Success, outputs available
`failed`	Error occurred
`cancelled`	Task was cancelled
`timeout`	Task exceeded its execution limit

Error Handling

Code	Description
200	Success
400	Bad request (invalid parameters)
401	Unauthorized (invalid API key)
403	Forbidden (account issue)
429	Rate limit exceeded
500	Server error

API Reference

Model Documentation

Each model has specific parameters. See the Model Library for complete API documentation for each model.

N8N Integration How WaveSpeedAI Works