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`)

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?standard_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

Do not retry automatically

Send the submit request once. If the connection drops or you get a 5xx response and you did not receive a task id, the task may still have been created and billed. Check History (or Predictions API) for a matching task before submitting again, and only resubmit if none exists. If you have a task id, poll it instead. See Errors, Retries and Timeouts.

Next Steps

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

Refund Policy Get Result