WaveSpeed

WaveSpeedTools generate images and videos from text prompts through WaveSpeed-hosted models.

v3.0.2

WaveSpeedTools enable an Agent to generate images and videos from text prompts with models hosted on WaveSpeed. The defaults target bytedance/seedream-v5.0-pro for images and bytedance/seedance-2.5/text-to-video for video; any id from WaveSpeed’s model catalog can be set per instance or per call.

Prerequisites

The following example requires the wavespeed and openai libraries:

uv pip install -U wavespeed openai

Set the WAVESPEED_API_KEY environment variable. Get your key from WaveSpeed.

export WAVESPEED_API_KEY=***

Example

cookbook/91_tools/wavespeed_tools.py

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.wavespeed import WaveSpeedTools

wavespeed_agent = Agent(
    name="WaveSpeed Media Generator Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    tools=[
        WaveSpeedTools(
            image_model="bytedance/seedream-v5.0-pro",
            video_model="bytedance/seedance-2.5/text-to-video",
        )
    ],
    description="You are an AI agent that can generate images and videos using the WaveSpeed API.",
    instructions=[
        "When the user asks you to create an image, use the `generate_image` tool.",
        "When the user asks you to create a video, use the `generate_video` tool.",
        "Return the URL as raw to the user.",
    ],
    markdown=True,
)

wavespeed_agent.print_response("Generate an image of a lighthouse on a stormy coast")

How Generation Runs

Both tools submit the job through the WaveSpeed SDK and poll every poll_interval seconds until the model finishes or timeout elapses — the tool call blocks for the whole wait. Only your prompt is sent: every other setting (aspect ratio, resolution, video duration) uses WaveSpeed’s defaults for the selected model. See the model catalog for each model’s parameters and limits.

On success, the tool result names the output URLs and attaches them as image or video artifacts. The media stays on WaveSpeed’s side — the bytes are not downloaded — and WaveSpeed keeps generated media for up to 7 days per its data retention policy. Failures come back as tool-result strings (“No output received from the model.”, or “Error: …” with the reason), never raised.

Toolkit Params

Parameter	Type	Default	Description
api_key	Optional[str]	None	WaveSpeed API key. If not provided, uses the WAVESPEED_API_KEY env variable.
image_model	str	"bytedance/seedream-v5.0-pro"	WaveSpeed model id for image generation.
video_model	str	"bytedance/seedance-2.5/text-to-video"	WaveSpeed model id for video generation.
poll_interval	float	1.0	Seconds between result polls, forwarded to the WaveSpeed SDK.
timeout	float	600.0	Wall-clock cap in seconds on one generation, submit to finish.
generate_image	bool	True	Enable the generate_image function.
generate_video	bool	True	Enable the generate_video function.
all	bool	False	Enable all functions.

Toolkit Functions

Function	Description
generate_image	Generate one or more images from a text prompt and return them as remote-URL image artifacts. Parameters: prompt (str), model (Optional[str]) to override the instance’s image model for this call.
generate_video	Generate one or more videos from a text prompt and return them as remote-URL video artifacts. Parameters: prompt (str), model (Optional[str]) to override the instance’s video model for this call.

Developer Resources

• Tools
• Cookbook
• WaveSpeed Docs