Skip to main content

LlamaIndex Tools Integration: WaveSpeed

PyPI

WaveSpeedToolSpec gives a LlamaIndex agent access to the WaveSpeed AI inference platform: text-to-image and text-to-video generation, running any model in the catalog by id, and recovering a long-running job from its prediction id.

It is built on the official wavespeed Python SDK, so it inherits the SDK's submission semantics — a submission POST is never retried, terminal statuses (failed / cancelled / timeout / deleted) are handled explicitly, and every request carries channel attribution.

Installation

pip install llama-index-tools-wavespeed
export WAVESPEED_API_KEY="your-api-key"   # https://wavespeed.ai

Tools

Tool What it does
generate_image Text to image. Default model bytedance/seedream-v5.0-pro. Accepts resolution and aspect_ratio.
generate_video Text to video. Default model bytedance/seedance-2.5/text-to-video, the same default as the WaveSpeed CLI and MCP server (use wavespeed-ai/minimax-h3/text-to-video for a lower price). Accepts duration.
run_model Runs any model id with an arbitrary input dict — image editing, upscaling, image-to-video, speech, and so on. See https://wavespeed.ai/models.
get_prediction Fetches an earlier prediction by id. Video jobs routinely outlive a single tool call; when one times out the error carries a task_id the agent can pass here.

Each tool returns the output URL(s), one per line, or a string starting with Error: that carries the prediction id and the platform's own error text.

Usage

import asyncio

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.wavespeed import WaveSpeedToolSpec

tool_spec = WaveSpeedToolSpec()  # reads WAVESPEED_API_KEY
# or: WaveSpeedToolSpec(api_key="...")

agent = FunctionAgent(
    tools=tool_spec.to_tool_list(),
    llm=OpenAI(model="gpt-4.1"),
)

response = asyncio.run(
    agent.run("Generate a 16:9 image of a red panda drinking boba tea.")
)
print(response)

ReActAgent works the same way:

from llama_index.core.agent.workflow import ReActAgent

agent = ReActAgent(tools=tool_spec.to_tool_list(), llm=OpenAI(model="gpt-4.1"))

You can also call the tools directly, without an agent:

tool_spec = WaveSpeedToolSpec()
print(tool_spec.generate_image("a lighthouse at dusk", aspect_ratio="16:9"))
print(tool_spec.run_model("wavespeed-ai/z-image/turbo", {"prompt": "a fox"}))

Configuration

WaveSpeedToolSpec(
    api_key=None,  # else WAVESPEED_API_KEY
    image_model="bytedance/seedream-v5.0-pro",
    video_model="bytedance/seedance-2.5/text-to-video",
    timeout=None,  # optional cap in seconds; unset = no short cap
    poll_interval=2.0,
)

There is no short default wait cap, since tasks can run for hours. If you set timeout and a job exceeds it, the task keeps running server-side — take the task_id out of the error and call get_prediction.

The underlying SDK client is created with max_retries=0 so a single tool call can never turn into a second, separately billed submission.

Why size and seed are not exposed

The platform's input whitelist silently drops parameters the default models do not declare. Advertising them in an LLM-facing schema would invite the agent to set values that are then ignored, so generate_image and generate_video expose only parameters that actually take effect. If a specific model you pick does support them, pass them through run_model.

A note on discovery

llamahub.ai is generated from metadata in the run-llama/llama_index monorepo, which no longer accepts new integration packages. This package is therefore not listed on LlamaHub. It is a normal PyPI distribution that installs into the llama_index.tools namespace package and works exactly like the official tool specs.

Development

uv sync --all-groups   # or: pip install -e . pytest ruff
pytest tests
ruff check .

The test suite mocks the SDK client and never calls the live API.

License

MIT


WaveSpeed AI — AI image & video generation platform. Try it in the browser: Image generator · Video generator

Metadata

Release files for llama-index-tools-wavespeed 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for llama-index-tools-wavespeed 0.1.4
File Size Uploaded Provenance Actions
llama_index_tools_wavespeed-0.1.4.tar.gz 9.7 kB With provenance Details for llama_index_tools_wavespeed-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for llama-index-tools-wavespeed 0.1.4
File Interpreter ABI Platform Actions
llama_index_tools_wavespeed-0.1.4-py3-none-any.whl Python 3 none any Details for llama_index_tools_wavespeed-0.1.4-py3-none-any.whl

Total release size: 18.0 kB

Release files / llama_index_tools_wavespeed-0.1.4.tar.gz

Download URL llama_index_tools_wavespeed-0.1.4.tar.gz
Size 9.7 kB
Tags Source
SHA-256 checksum
How to use checksums
4c97f434a3fd964b1107b8e8ed380a4782091f835ea53e6b56aeebe6e861d4da
BLAKE2b-256 checksum
How to use checksums
38bef154aea6aa3d9c475005d03b1b92e352bca8cfb5c02a6d406eed2a6e0803
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / llama_index_tools_wavespeed-0.1.4-py3-none-any.whl

Download URL llama_index_tools_wavespeed-0.1.4-py3-none-any.whl
Size 8.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
77b235d61ece45a9bcddd1f7281d168801006789130d08f4cd1aa9c247b1158d
BLAKE2b-256 checksum
How to use checksums
650489e5364b3cb44beb9049225ca74fa6140af1b0a71a4bf23ce60adfe86885
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for llama-index-tools-wavespeed 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for llama_index_tools_wavespeed-0.1.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page