将 Ultimate Image Upscaler 与 Comfy Router 配合使用
通过 Comfy Router 调用 wavespeed/ultimate-image-upscaler：端点、请求形状以及 Router 返回的响应。
将 Ultimate Image Upscaler 与 Comfy Router 配合使用
通过 Comfy Router 调用 wavespeed/ultimate-image-upscaler：端点、请求形状以及 Router 返回的响应。
wavespeed/ultimate-image-upscaler 的 API 参考，由 Comfy Router 从 WaveSpeed 提供。
输入： 图像 · 输出： 图像
快速开始
在你的 Comfy 工作区中创建一个密钥，并将其导出为 COMFY_API_KEY。Python 和 TypeScript 代码片段使用 Comfy SDK（pip install comfy-sdk 和 npm install @comfyorg/sdk）；cURL 代码片段则是通过原始 HTTP 发起的同一调用。
模型 ID： wavespeed/ultimate-image-upscaler
端点： POST https://api.comfy.org/v2/models/wavespeed/ultimate-image-upscaler
[tab] 等待结果 ``python Python theme={null} from comfy_sdk import Comfy # 从环境变量中读取 COMFY_API_KEY。 # SDK 会自动创建幂等键，并在自动重试时复用它。 with Comfy() as client: result = client.models.run( "wavespeed/ultimate-image-upscaler", { "image": "https://images.pexels.com/photos/346529/pexels-photo-346529.jpeg", "target_resolution": "4k", }, ) print(result)``typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // SDK 会自动创建幂等键，并在自动重试时复用它。 const { data } = await comfy.models.run("wavespeed/ultimate-image-upscaler", { image: "https://images.pexels.com/photos/346529/pexels-photo-346529.jpeg", target_resolution: "4k", }); console.log(data);``bash cURL theme={null} curl https://api.comfy.org/v2/models/wavespeed/ultimate-image-upscaler \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"image\": \"https://images.pexels.com/photos/346529/pexels-photo-346529.jpeg\", \"target_resolution\": \"4k\"}"``
[tab] 提交排队，稍后收取 相同的请求体，发送至POST https://api.comfy.org/v2/models/wavespeed/ultimate-image-upscaler/requests。运行一经受理，Router 立即以201返回一个request_id，结果就绪后即可收取，无论在当前进程还是另一个进程中都可以。队列投递会带你了解状态查询、取消和收取的完整流程。 ``python Python theme={null} import asyncio from comfy_sdk import AsyncComfy # 从环境变量中读取 COMFY_API_KEY。 # 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 async def main(): async with AsyncComfy() as client: handle = await client.models.submit( "wavespeed/ultimate-image-upscaler", { "image": "https://images.pexels.com/photos/346529/pexels-photo-346529.jpeg", "target_resolution": "4k", }, ) print("request_id:", handle.request_id) # 配合模型 ID，这就是另一个进程所需的全部信息 # 轮询直到请求完成，每次等待服务器指定的 Retry-After 时长。 async for update in handle.iter_events(): print(update.status, update.queue_position) # 提供商自己的响应载荷，与 models.run() 返回的值相同。 # 失败或已取消的请求会在此处抛出类型化的 Router 错误。 result = await handle.get() print(result) asyncio.run(main())``typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 const handle = await comfy.models.submit("wavespeed/ultimate-image-upscaler", { image: "https://images.pexels.com/photos/346529/pexels-photo-346529.jpeg", target_resolution: "4k", }); console.log("requestId:", handle.requestId); // 配合模型 ID，这就是另一个进程所需的全部信息 // 轮询直到请求完成，每次等待服务器指定的 Retry-After 时长。 for await (const update of handle.events()) { console.log(update.status, update.queuePosition); } // 与 models.run() 返回的结果相同。失败或已取消的请求会在此处被拒绝。 const result = await handle.get(); console.log(result.data);``bash cURL theme={null} # 1. 提交。Router 返回 201，并带上 request_id、status_url、response_url 和 cancel_url。 curl https://api.comfy.org/v2/models/wavespeed/ultimate-image-upscaler/requests \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"image\": \"https://images.pexels.com/photos/346529/pexels-photo-346529.jpeg\", \"target_resolution\": \"4k\"}" # 2. 轮询直到状态为 COMPLETED，每次等待响应中指定的 Retry-After 秒数。 REQUEST_ID="<request_id from the 201 body>" curl -i https://api.comfy.org/v2/models/wavespeed/ultimate-image-upscaler/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. 收取。完成时返回 200 及模型的原生输出；仍在运行时返回 202 及状态正文。 curl https://api.comfy.org/v2/models/wavespeed/ultimate-image-upscaler/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY"``
Schema
输入
enable\_base64\_output boolean (default: false)
如果启用，输出将被编码为 BASE64 字符串，而不是 URL。
image string required
需要 upscale 的图像的 URL。
output\_format string (default: "jpeg")
输出图像的格式。
可选值：jpeg、png、webp
target\_resolution string (default: "4k")
输出图像的目标分辨率。
可选值：2k、4k、8k
由 Router 在 GET /v2/models/wavespeed/ultimate-image-upscaler/openapi.json 提供的 schema 生成，这也是请求到达提供商之前 Router 用于校验调用的同一份文档。
输出
code integer
WavespeedAI 自己的信封状态码，对应 HTTP 状态（在本文档所描述的文档中为 200）。Wavespeed 会把某些失败报告在这里，而不是报告在传输状态中。
data object required
data.created\_at string
Wavespeed 创建该预测时的 ISO-8601 时间戳。
data.error string
Wavespeed 的自由文本失败原因，没有错误时为空字符串。真正失败的预测会以 Comfy Router 错误的形式到达 Router 调用方，而不是以本文档的形式。
data.id string
Wavespeed 为 Router 提交并轮询的预测分配的标识符。
data.model string
该预测运行所用的 Wavespeed 模型 id。
data.outputs string[] required
已完成的生成结果。在 Router 返回的文档中存在且非空；这个列表就是结果本身。每个元素都是指向已生成内容的 URL：wavespeed/flashvsr 返回 MP4，两个 upscaler 返回图像；或者，对于这两个图像 id，当请求设置了 enable_base64_output 时，元素是 base64 编码的字节本身。这些链接由 Wavespeed 提供，并且会过期。
data.status string required
预测的终端状态，按 Wavespeed 的拼写。此处未收窄为枚举：Router 原样转发该值，轮询分类器在比较前会将其转为小写，因此成功状态可以合理地以 completed、succeeded、success 或 done 出现，大小写不限。
data.timings object
Wavespeed 自己的计时测量。
data.timings.inference integer
推理时间，单位为毫秒。这是 Wavespeed 的数字，不是 Comfy 的计费。
data.urls object
Wavespeed 为该预测提供的链接。
data.urls.get string
Router 轮询的预测结果 URL。
message string
信封状态消息，例如 success。
示例
输入
{
"image": "https://images.pexels.com/photos/346529/pexels-photo-346529.jpeg",
"target_resolution": "4k"
}
输出
{
"code": 200,
"data": {
"created_at": "2027-01-01T00:00:00Z",
"error": "",
"id": "3f6c1a90-2b47-4d18-9a55-7c0e8b21d4f3",
"outputs": [
"https://example.invalid/wavespeed/ultimate-image-upscaler/upscaled.png"
],
"status": "completed",
"timings": {
"inference": 9100
}
},
"message": "success"
}
发布前须知
SDK 会生成 Idempotency-Key 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。
请求失败时，Router 会发送 X-Comfy-Error-Type 响应头说明原因。422 表示 Router 在调用提供商之前就拒绝了输入，413 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为结果 URL 会过期。
上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见请求体大小。
本页记录的是通过 Comfy Router 调用的某一个合作伙伴模型。同一个 comfy-sdk / @comfyorg/sdk 包还提供第二个客户端，用于在 Comfy Cloud 上运行完整的 ComfyUI 工作流图：Comfy(api_key=...) / new Comfy({ apiKey })，并带有 client.workflows、client.assets 和 client.jobs。请参阅 Comfy SDKs。
[card] 请求头 身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
[card] 使用 Router API 模型发现、验证错误、重试与计费。
[card] 限制 Router 目前不支持的功能，以及替代方案。