How to Submit Task

Submit generation tasks to WaveSpeedAI models via API.

Endpoint

POST https://api.wavespeed.ai/api/v3/{model_id}

Replace {model_id} with the complete model ID shown on its model page, such as wavespeed-ai/z-image/turbo or minimax/speech-2.6-hd.

Request Format

curl --fail-with-body --connect-timeout 10 --max-time 60 \
--request POST 'https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo' \
--header "Authorization: Bearer $WAVESPEED_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "A cat wearing a space suit",
    "size": "1024*1024"
}'

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer ${WAVESPEED_API_KEY}`
`Content-Type`	Yes	`application/json`

Request Body

The request body varies by model. Common parameters:

Parameter	Type	Description
`prompt`	string	Text description
`size`	string	Output dimensions, when supported
`seed`	integer	Random seed
`enable_sync_mode`	boolean	Wait for the final result in the same HTTP response when supported. See Sync Mode before using it in production.

Check the model’s documentation for specific parameters.

Response

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "pred_abc123",
    "model": "wavespeed-ai/z-image/turbo",
    "status": "created",
    "urls": {
      "get": "https://api.wavespeed.ai/api/v3/predictions/pred_abc123/result"
    },
    "created_at": "2024-01-01T12:00:00.000Z"
  }
}

Response Fields

Field	Description
`data.id`	Task ID for polling
`data.status`	Initial status (`created`)
`data.urls.get`	URL to check status

With Webhook

Receive notification when complete:

curl --fail-with-body --connect-timeout 10 --max-time 60 \
--request POST 'https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo?webhook=https%3A%2F%2Fyour-server.com%2Fwebhook' \
--header "Authorization: Bearer $WAVESPEED_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "prompt": "A cat in space",
    "size": "1024*1024"
}'

Python Example

import os
import requests
 
api_key = os.environ["WAVESPEED_API_KEY"]
 
response = requests.post(
    "https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "A cat wearing a space suit",
        "size": "1024*1024"
    },
    timeout=(10, 60),
)
response.raise_for_status()
body = response.json()
if body.get("code") != 200:
    raise RuntimeError(body.get("message", "Task submission failed"))
task = body["data"]
task_id = task["id"]
print(f"Task submitted: {task_id}")

Error Responses

Code	Description
400	Invalid parameters
401	Invalid API key
403	Account issue
429	Rate limit exceeded
500	Server error

Next Steps

After submitting, use How to Get Result to retrieve your output.

List Models Upload Files API