WaveSpeedAI

https://wavespeed.ai/docs
Admin
WaveSpeedAI is an AI platform that provides access to multiple generative models for image...
Tokens:2,780,954
Snippets:14,697
Trust Score:8.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Ovi Image-to-Video Prompt Example

Source: https://wavespeed.ai/docs/docs-api/character-ai/character-ai-ovi-image-to-video

Example prompt for the Ovi image-to-video API, including dialogue and audio cues. Use this format to guide video generation with character speech and sound effects.

```text
A wide shot of a medieval knight standing in the rain, sword planted into the ground, glowing with mystical energy. 
<S>I will defend this land until my last breath.</E> 
<AUDCAP>Thunder rolls across the dark sky, distant war drums echo.</ENDAUDCAP>
```

--------------------------------

### Install with yarn

Source: https://wavespeed.ai/docs/javascript-sdk

Installs the WaveSpeedAI SDK via yarn.

```bash
yarn add wavespeed
```

--------------------------------

### Install WaveSpeedAI Python SDK

Source: https://wavespeed.ai/docs/python-sdk

Install the SDK using pip.

```bash
pip install wavespeed
```

--------------------------------

### Install standardwebhooks Go library

Source: https://wavespeed.ai/docs/verify-webhooks

Install the official Go library for verifying Standard Webhooks signatures.

```bash
go get github.com/standard-webhooks/standard-webhooks/libraries
```

--------------------------------

### Install with npm

Source: https://wavespeed.ai/docs/javascript-sdk

Installs the WaveSpeedAI SDK via npm.

```bash
npm install wavespeed
```

--------------------------------

### Install the WaveSpeed skill for coding agents

Source: https://wavespeed.ai/docs/wavespeed-cli

Run `wavespeed skill install` to install the WaveSpeed skill file for compatible coding agents. This creates the file `.claude/skills/wavespeed/SKILL.md`.

```bash
# Install the WaveSpeed skill file for compatible coding agents.
wavespeed skill install
```

--------------------------------

### Install standardwebhooks Node.js library

Source: https://wavespeed.ai/docs/verify-webhooks

Install the official Node.js library for verifying Standard Webhooks signatures.

```bash
npm install standardwebhooks
```

--------------------------------

### Install standardwebhooks Python library

Source: https://wavespeed.ai/docs/verify-webhooks

Install the official Python library for verifying Standard Webhooks signatures.

```bash
pip install standardwebhooks
```

--------------------------------

### Install Dependencies on Windows

Source: https://wavespeed.ai/docs/comfyui-integration

Install Python dependencies using pip on Windows. Run this after cloning the repository.

```bash
python -m pip install -r requirements.txt
```

--------------------------------

### Initialize project configuration with wavespeed init

Source: https://wavespeed.ai/docs/wavespeed-cli

Creates a wavespeed.json file with sensible defaults.

```bash
# Create wavespeed.json with sensible defaults.
wavespeed init -y
```

--------------------------------

### cURL Request to Predictions API

Source: https://wavespeed.ai/docs/predictions-api

cURL example for the Predictions API. Both page and page_size are required; start with page: 1 and increment to retrieve subsequent results.

```bash
curl --fail-with-body --connect-timeout 10 --max-time 60 \
--request POST "https://api.wavespeed.ai/api/v3/predictions" \
--header "Authorization: Bearer $WAVESPEED_API_KEY" \
--header "Content-Type: application/json" \
--data '{"page": 1, "page_size": 20}'
```

--------------------------------

### Example task for a coding agent

Source: https://wavespeed.ai/docs/wavespeed-cli

After the skill is installed, you can ask a coding agent to perform tasks like finding a text-to-image model, generating a product photo, and downloading it locally.

```text
Find a text-to-image model, generate a product photo, and download it locally.
```

--------------------------------

### Python example: Get usage statistics from Wavespeed API

Source: https://wavespeed.ai/docs/check-usage

This example shows how to call the Wavespeed usage statistics API using the requests library. It requires the WAVESPEED_API_KEY environment variable to be set. The function get_usage sends a POST request to the endpoint and returns the data field from the response, raising an error if the API returns a non-200 code. The example then prints the total cost, total requests, and top models by usage.

```python
import os
import requests
 
api_key = os.environ["WAVESPEED_API_KEY"]
 
def get_usage(start_time, end_time, model_uuid=None):
    payload = {
        "start_time": start_time,
        "end_time": end_time
    }
    if model_uuid:
        payload["model_uuid"] = model_uuid
 
    response = requests.post(
        "https://api.wavespeed.ai/api/v3/user/usage_stats",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        },
        json=payload,
        timeout=(10, 60),
    )
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(body.get("message", "Failed to retrieve usage"))
    return body["data"]
 
# Get usage for a time range
usage = get_usage("2025-10-01T00:00:00Z", "2025-10-12T23:59:59Z")
 
print(f"Total cost: ${usage['summary']['total_cost']}")
print(f"Total requests: {usage['summary']['total_requests']}")
 
# Show top models
for model in usage["per_model_usage"][:5]:
    print(f"- {model['model_uuid']}: {model['total_count']} requests, ${model['total_cost']}")
```

--------------------------------

### Submit Task & Query Result

Source: https://wavespeed.ai/docs/docs-api/ideogram-ai/ideogram-ai-ideogram-v2a-turbo

Submits an image generation task to the Ideogram V2A Turbo model and polls for the result. The example uses cURL to POST a prediction and then repeatedly GET the result until the status is completed.

```APIDOC
## [POST] https://api.wavespeed.ai/api/v3/ideogram-ai/ideogram-v2a-turbo

### Description
Submits a new image generation task to the Ideogram V2A Turbo model. The response contains a prediction ID used to query the result.

### Method
POST

### Endpoint
https://api.wavespeed.ai/api/v3/ideogram-ai/ideogram-v2a-turbo

### Parameters
#### Request Body
- **prompt** (string) - Required - The text prompt describing the image to generate.
- **style** (string) - Optional - The style for the image. Example: "Auto".
- **aspect_ratio** (string) - Optional - The aspect ratio of the image. Example: "1:1".

### Request Example
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "style": "Auto",
  "aspect_ratio": "1:1"
}

### Response
#### Success Response (200)
- **id** (string) - The prediction ID for the submitted task.

#### Response Example
{
  "id": "prediction-id"
}

## [GET] https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

### Description
Retrieves the result of a submitted prediction task. Poll this endpoint until the status is "completed" to obtain the generated outputs.

### Method
GET

### Endpoint
https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

### Parameters
#### Path Parameters
- **prediction_id** (string) - Required - The ID of the prediction task returned from the submission endpoint.

### Response
#### Success Response (200)
- **status** (string) - The status of the prediction. Possible values: "completed", "failed", "cancelled", "timeout", "deleted".
- **outputs** (array) - The generated image outputs, present when status is "completed".

#### Response Example
{
  "status": "completed",
  "outputs": []
}
```

--------------------------------

### Quick Start: Run a model

Source: https://wavespeed.ai/docs/javascript-sdk

Runs a model with the default client, specifying prompt, size, and polling options. Logs the outputs or sets exit code 1 on failure.

```javascript
import wavespeed from 'wavespeed';
 
wavespeed.run("wavespeed-ai/z-image/turbo", {
  prompt: "A cat wearing a space suit",
  size: "1024*1024"
}, {
  pollInterval: 2.0,
  timeout: 3600
})
.then(output => {
  console.log(output["outputs"]);
})
.catch(error => {
  console.error("Generation failed:", error);
  process.exitCode = 1;
});
```

--------------------------------

### InfiniteTalk API Call for Image + Audio Workflow

Source: https://wavespeed.ai/docs/create-digital-human

Alternative InfiniteTalk API call for the Image + Audio workflow, using placeholder URLs for the face image and audio. Same parameters and authentication as the Quick Start example.

```bash
curl --fail-with-body --connect-timeout 10 --max-time 60 --request POST 'https://api.wavespeed.ai/api/v3/wavespeed-ai/infinitetalk' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
--data-raw '{
  "image": "https://your-face-image-url",
  "audio": "https://your-audio-url",
  "resolution": "480p"
}'
```

--------------------------------

### Submit Task & Query Result

Source: https://wavespeed.ai/docs/docs-api/wavespeed-ai/flux-2-dev-edit

This example demonstrates how to submit an image editing task to the FLUX.2 [dev] Edit endpoint and poll for the result. It uses the POST endpoint to submit the task and the GET result endpoint to retrieve the output.

```APIDOC
## [POST] https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-2-dev/edit

### Description
Submits an image editing task to the FLUX.2 [dev] Edit model. The request includes a prompt and a list of image URLs to be edited.

### Method
POST

### Endpoint
https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-2-dev/edit

### Authentication
Bearer token (API key) in the Authorization header. Refer to the Authentication Guide for details.

### Request Body
- **prompt** (string) - Required - The editing instruction or description of the desired edit.
- **images** (array of strings) - Required - List of image URLs to be edited.

### Request Example
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ]
}

### Response
#### Success Response (200)
- **id** (string) - The prediction ID for the submitted task.
- **status** (string) - The status of the prediction (e.g., completed, failed, cancelled, timeout, deleted).
- **outputs** (array) - The edited image outputs when status is completed.

#### Response Example
{
  "id": "prediction-id",
  "status": "completed",
  "outputs": ["https://example.com/output.png"]
}

---

## [GET] https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

### Description
Retrieves the result of a previously submitted prediction task. Poll this endpoint until the status becomes completed, failed, cancelled, timeout, or deleted.

### Method
GET

### Endpoint
https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

### Path Parameters
- **prediction_id** (string) - Required - The ID of the prediction task returned from the submission endpoint.

### Authentication
Bearer token (API key) in the Authorization header.

### Response
#### Success Response (200)
- **status** (string) - The status of the prediction (e.g., completed, failed, cancelled, timeout, deleted).
- **outputs** (array) - The edited image outputs when status is completed.

#### Response Example
{
  "status": "completed",
  "outputs": ["https://example.com/output.png"]
}

### Error Handling
- If the status is failed, cancelled, timeout, or deleted, the response will contain error details.
```

--------------------------------

### Submit Task & Query Result

Source: https://wavespeed.ai/docs/docs-api/wavespeed-ai/minimax-h3-text-to-video

Submits a text-to-video generation task to the Minimax H3 model and polls for the result. The example uses cURL to POST the request and then repeatedly GETs the result endpoint until the status is completed, failed, cancelled, timeout, or deleted.

```APIDOC
## [POST] https://api.wavespeed.ai/api/v3/wavespeed-ai/minimax-h3/text-to-video

### Description
Submits a text-to-video generation task using the Minimax H3 model. The response contains a prediction ID used to query the result.

### Method
POST

### Endpoint
https://api.wavespeed.ai/api/v3/wavespeed-ai/minimax-h3/text-to-video

### Parameters
#### Request Body
- **prompt** (string) - Required - The text prompt describing the video to generate.
- **aspect_ratio** (string) - Optional - The aspect ratio of the video (e.g., "16:9").
- **resolution** (string) - Optional - The resolution of the video (e.g., "480p").
- **duration** (integer) - Optional - The duration of the video in seconds (e.g., 5).

### Request Example
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "duration": 5
}

### Response
#### Success Response (200)
- **id** (string) - The prediction ID used to query the result.
- **status** (string) - The status of the prediction (e.g., "completed", "failed", "cancelled", "timeout", "deleted").
- **outputs** (array) - The generated video outputs when status is "completed".

#### Response Example
{
  "id": "prediction-id",
  "status": "completed",
  "outputs": ["https://example.com/video.mp4"]
}

## [GET] https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

### Description
Retrieves the result of a previously submitted prediction. Poll this endpoint until the status is completed or a terminal state.

### Method
GET

### Endpoint
https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

### Parameters
#### Path Parameters
- **prediction_id** (string) - Required - The ID of the prediction returned from the submission endpoint.

### Response
#### Success Response (200)
- **id** (string) - The prediction ID.
- **status** (string) - The status of the prediction (e.g., "completed", "failed", "cancelled", "timeout", "deleted").
- **outputs** (array) - The generated video outputs when status is "completed".

#### Response Example
{
  "id": "prediction-id",
  "status": "completed",
  "outputs": ["https://example.com/video.mp4"]
}

```
Tokens:
Raw