用 WaveSpeedAI API 提交生成任务并取回结果

WaveSpeedAI 是一个把图像、视频、音频、3D 等生成模型聚合到同一套接口下的平台。对开发者来说，它解决的核心问题是：不必为每个模型分别对接一套 SDK 和鉴权方式，只要拿到模型标识，就能用同一种请求结构提交任务、取回结果。本文面向需要以编程方式调用生成能力的读者，讲清楚从注册账号到跑通第一次生成、再到处理返回结果与常见错误的完整路径。如果你更想先在网页上试效果，可以从 WaveSpeedAI 的模型页开始，无需 API Key 即可运行。

准备工作

账号与登录方式

在 wavespeed.ai 注册账号，支持使用 Google 或 GitHub 账号登录。符合条件的新用户可能获得 1 美元的试用额度，可用于受支持的模型。需要注意，仅用新邮箱注册并不保证一定具备领取资格，额度发放以平台判定为准。

额度与付费组织

API Key 生成后立即生效，不需要先充值才能激活。但真正发起计费请求时，账户里必须有足够的余额；部分模型还要求使用已付费的组织。价格、额度与计费规则会调整，具体以官网当前页面显示为准。

生成 API Key

进入 API Keys 页面，填写一个便于识别的名称，点击 Generate 即可。密钥一旦生成就处于可用状态。平台对密钥做了权限分级，选型时要按用途挑：

• Owner / Admin：拥有完整的 API 访问权限。
• Developer：可以运行模型、读取本组织的预测记录与余额，但读不到逐项费用明细与用量统计。
• Billing：可以读取余额、费用与用量，但不能运行模型。

发票、付款与组织计费信息只能在控制台里查看，不通过 API 暴露。

密钥安全

把 API Key 当作密码对待：存放在环境变量里，不要写进前端代码，并定期轮换。下面的示例统一使用环境变量 WAVESPEED_API_KEY。

选择接入方式

平台提供多种接入路径，按团队情况选择即可：

方式	适合的场景
REST API	自建集成、任意语言
Python SDK	Python 项目快速接入
JavaScript SDK	Node 或前端构建流程
桌面应用	不写代码、本地使用
ComfyUI 集成	节点式工作流
N8N 集成	无代码自动化
CLI / MCP Server	命令行与智能体调用

操作步骤

第一步：确定模型标识

所有请求都以模型标识作为路径的一部分，形如 wavespeed-ai/z-image/turbo。在模型页面可以浏览全部可用模型，每个模型页都提供四个标签页：Playground 用于配置参数并运行；JSON 显示当前输入对应的 JSON，便于调试或复制到代码里；API 根据你当前的参数设置生成可直接使用的 cURL、Python 等代码；History 显示该模型的历史生成记录。右上角工具栏里还有收藏、Schema 查看输入输出结构，以及部分模型支持的 LLM 后端切换。

最省事的做法是：先在 Playground 里把参数调到满意，再切到 API 标签页复制代码，这样参数名和取值都不会写错。

第二步：用 cURL 提交任务

下面是最小可用的请求，向图像生成模型提交一个提示词：

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

几个参数值得留意：--fail-with-body 让 curl 在 HTTP 状态码异常时仍然输出响应体，便于看到平台返回的错误说明；--connect-timeout 与 --max-time 分别限制连接与整体耗时，避免请求无限挂起。请求体里的 size 使用 宽*高 的写法，星号两侧不加空格。

第三步：用 Python SDK 提交并等待结果

SDK 把提交与轮询封装成一次调用，适合脚本和批处理：

import wavespeed

try:
    output = wavespeed.run(
        "wavespeed-ai/z-image/turbo",
        {"prompt": "A cat wearing a space suit", "size": "1024*1024"},
        poll_interval=2.0,
    )
    print(output["outputs"])
except Exception as error:
    raise SystemExit(f"Generation failed: {error}") from error

poll_interval 控制两次查询之间的间隔秒数。生成类任务耗时差异很大，图像通常较快，视频和数字人明显更久，间隔设得太小只会增加无意义的请求。

第四步：读取结果

返回结果中的 outputs 字段承载生成产物。产物链接属于临时下载地址，需要长期保存的文件应当及时转存到自己的存储里，不要依赖平台链接长期有效。历史记录页面同样可以查看并下载这些临时产物。

第五步：按需接入其他能力

同一套鉴权与请求结构可以复用到平台的其他能力上：

• 文件上传：图生图、图生视频等任务需要先上传素材。
• Webhook：不想轮询时，用回调接收任务完成通知，并可校验回调来源。
• 流式输出：适合需要边生成边展示的场景。
• 同步模式：请求直接等待结果返回，省去轮询逻辑。
• Base64 输出：需要把产物直接嵌入响应体时使用。

一个完整示例

下面把前面的步骤串成一条可执行的流程：从环境变量读取密钥，提交一个图像生成任务，打印产物地址，并在失败时给出明确退出码。

export WAVESPEED_API_KEY="你的密钥"

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

如果更习惯 Python，等价写法如下，并且可以直接把结果写进后续处理流程：

import os
import wavespeed

assert os.environ.get("WAVESPEED_API_KEY"), "请先设置 WAVESPEED_API_KEY"

try:
    output = wavespeed.run(
        "wavespeed-ai/z-image/turbo",
        {
            "prompt": "A cat wearing a space suit, studio lighting",
            "size": "1024*1024",
        },
        poll_interval=2.0,
    )
except Exception as error:
    raise SystemExit(f"Generation failed: {error}") from error

for url in output["outputs"]:
    print(url)

跑通之后，把模型标识和参数换成目标模型即可复用同一段代码。参数名以模型页 Schema 中列出的为准，不同模型的输入字段并不完全一致。

LoRA 的使用与训练

在生成中套用已有 LoRA

平台支持在调用时挂载 LoRA 模型，来源可以是 Hugging Face 或 Civitai。要点如下：

• 文件格式：只支持 .safetensors。
• 路径写法：Hugging Face 使用 owner/model-name 形式，Civitai 使用直链 URL。
• Scale：控制 LoRA 影响强度，默认值为 1。
• 触发词：需要写进提示词里才会激活对应的风格。
• 兼容性：LoRA 必须与基础模型完全匹配，模型名称、版本、参数规模都要一致，否则无法生效。

训练自己的 LoRA

不写代码也能训练：把 10 到 20 张风格多样的图片压缩成一个 .zip 上传；设定一个唯一的触发词，例如 p3r5on；调整步数、学习率与 LoRA rank；点击 Run 等待完成；最后通过链接访问或下载 .safetensors 文件。训练时长取决于数据集大小与参数设置，实际耗时往往超过页面给出的预估时间，需要留出余量。若出现超时或系统错误，平台会自动退款。

注意事项

计费与批量模式

网页端的 Run 按钮会在点击前显示预估费用，但最终扣费可能略有浮动。开启批量模式后，计费按实际生成的图片或产物数量计算。提示词增强功能位于提示词输入框旁，可以自动优化提示词，但每次使用都会产生额外费用。价格与计费方式以官网当前信息为准。

内容审核

网页端默认开启 Safety Checker，对输出做内容审核以符合内容政策。通过 API 调用时同样受内容政策约束，提交前应确认素材与提示词合规。

密钥权限的边界

Developer 密钥读不到逐项费用与用量统计，Billing 密钥不能运行模型。如果自动化流程既要跑任务又要统计花费，需要分别配置两类密钥，而不是指望一个密钥包办。发票与付款信息只能进控制台查看。

超时与重试

生成任务耗时不可控，尤其是视频与数字人。给请求设置合理的超时上限，并在客户端实现重试与退避；轮询间隔不要设得过密。平台对错误码、重试与超时有专门说明，遇到非预期状态码时应先查错误码含义再决定是否重试。

产物留存

生成结果通过临时链接提供，过期后无法再取。需要长期保存的内容应在任务完成后立即下载或转存。

模型选择

平台覆盖图像、视频、音频、3D、内容审核、视觉检测等多个类别，模型数量超过一千个，且会持续更新。选型时优先看模型页的 Schema 与示例参数，不要凭记忆填写字段名。具体可用模型、参数与价格以官网当前信息为准。