跳转到主要内容

​
调用模式总览

BizyAir 提供 3 种调用模式，通过 HTTP Header 切换，无需修改请求体：
模式启用方式行为适用场景
同步阻塞不设置任何特殊 Header连接保持打开直到任务完成，直接返回结果短任务、简单调试
异步查询X-Bizyair-Task-Async: enable立即返回 requestId，客户端轮询查结果长任务、网络不稳定、无回调地址
WebHookX-BizyAir-Task-WebHook-Url: <url>立即返回 requestId，任务完成后主动 POST 回调生产环境、高并发、长耗时任务

​
同步阻塞调用

默认模式。HTTP 连接保持打开直到任务完成。无需额外 Header。 
curl -X POST "https://api.bizyair.ai/w/v1/webapp/task/openapi/create" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "web_app_id": 38214,
    "suppress_preview_output": false,
    "input_values": {
      "84:CLIPTextEncode.text": "a futuristic cityscape at sunset",
      "88:KSampler.seed": 354884000907176,
      "81:EmptySD3LatentImage.width": 1280,
      "81:EmptySD3LatentImage.height": 1280
    }
  }'
响应即任务结果，包含 outputs[].object_url。
同步模式需保持长连接，请确保 HTTP 客户端的读取超时 (Read Timeout) 至少 60 秒，避免任务执行过程中客户端主动断开。

​
异步查询模式

启用方式：在请求头加入 X-Bizyair-Task-Async: enable。

​
步骤 1：发起异步任务，立即获取 requestId

curl -X POST "https://api.bizyair.ai/w/v1/webapp/task/openapi/create" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Bizyair-Task-Async: enable" \
  -d '{
    "web_app_id": 38214,
    "input_values": {
      "84:CLIPTextEncode.text": "a futuristic cityscape at sunset",
      "88:KSampler.seed": 354884000907176,
      "81:EmptySD3LatentImage.width": 1280,
      "81:EmptySD3LatentImage.height": 1280
    }
  }'
立即返回 202 Accepted： 
{"requestId": "29f53793-12d3-4dd3-b2a8-4d9848e0c7da"}

​
步骤 2：轮询任务状态

curl -X GET "https://api.bizyair.ai/w/v1/webapp/task/openapi/detail?requestId=29f53793-12d3-4dd3-b2a8-4d9848e0c7da" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY"

​
步骤 3：任务 Success 后获取结果

curl -X GET "https://api.bizyair.ai/w/v1/webapp/task/openapi/outputs?requestId=29f53793-12d3-4dd3-b2a8-4d9848e0c7da" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY"

​
完整 Python 示例

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.bizyair.ai/w/v1/webapp/task/openapi"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-Bizyair-Task-Async": "enable",
}

# 1. 提交任务
resp = requests.post(f"{BASE}/create", headers=HEADERS, json={
    "web_app_id": 38214,
    "input_values": {
        "84:CLIPTextEncode.text": "a futuristic cityscape at sunset",
        "88:KSampler.seed": 354884000907176,
        "81:EmptySD3LatentImage.width": 1280,
        "81:EmptySD3LatentImage.height": 1280,
    }
})
request_id = resp.json()["requestId"]
print(f"任务已提交: {request_id}")

# 2. 轮询状态
HEADERS.pop("X-Bizyair-Task-Async")
while True:
    r = requests.get(f"{BASE}/detail", params={"requestId": request_id}, headers=HEADERS)
    status = r.json()["data"]["status"]
    print(f"当前状态: {status}")
    if status == "Success":
        break
    elif status in ("Failed", "Canceled"):
        print("任务失败或取消"); exit(1)
    time.sleep(2)

# 3. 获取结果
r = requests.get(f"{BASE}/outputs", params={"requestId": request_id}, headers=HEADERS)
for out in r.json()["data"]["outputs"]:
    print("结果 URL:", out["object_url"])

​
WebHook 回调模式

启用方式：在请求头加入 X-BizyAir-Task-WebHook-Url。

​
步骤 1：发起带 WebHook 的任务

curl -X POST "https://api.bizyair.ai/w/v1/webapp/task/openapi/create" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-BizyAir-Task-WebHook-Url: https://your-server.com/api/callback" \
  -H "X-BizyAir-Task-Authorization: Bearer YOUR_CALLBACK_TOKEN" \
  -d '{
    "web_app_id": 35661,
    "input_values": {
      "1:EmptyLatentImage.width": "1024",
      "1:EmptyLatentImage.height": "1024",
      "2:BizyAir_BasicScheduler.steps": "20",
      "3:BizyAir_RandomNoise.noise_seed": "1",
      "4:BizyAirSiliconCloudLLMAPI.user_prompt": "小猫，梵高风格",
      "4:BizyAirSiliconCloudLLMAPI.system_prompt": "你是一个 stable diffusion prompt 专家..."
    }
  }'
立即返回 202 Accepted + requestId。

​
步骤 2：在回调端接收结果

任务完成后 BizyAir 会向你指定的 URL 发起 POST 请求：
  • Method: POST
  • Headers: Content-Type: application/json、User-Agent: Go-http-client/1.1、以及你设置的 X-BizyAir-Task-Authorization 和其他 X-Bizyair-Task-* Header
  • Body: 包含完整任务结果

​
回调端 Node.js 示例

const express = require("express");
const app = express();
app.use(express.json());

const EXPECTED_TOKEN = process.env.CALLBACK_TOKEN;

app.post("/api/callback", (req, res) => {
  const auth = req.get("Authorization");
  if (EXPECTED_TOKEN) {
    const ok = auth?.startsWith("Bearer ") && auth.split(" ")[1] === EXPECTED_TOKEN;
    if (!ok) return res.status(401).json({ message: "invalid token" });
  }

  const payload = req.body;
  console.log("Received callback for request_id:", payload.request_id);

  res.status(200).json({ ok: true });
});

app.listen(3000, () => console.log("Callback server on :3000"));
回调端必须返回 HTTP 200 OK。若返回非 200、超时或无响应，平台会按策略重试（约每 6 秒一次，最多 10 次）。单次回调超时时间约 10 秒。

​
如何选择调用模式

你的场景推荐模式理由
本地脚本快速验证同步阻塞最简单，一次请求直接拿结果
短任务集成到后端同步阻塞短任务 HTTP 连接开销可接受
视频生成 / 3D 渲染（长任务）WebHook不阻塞服务、可大规模并行
客户端网络不稳定异步查询不依赖长连接，可按需轮询
批量并行百上个任务异步查询 或 WebHook全部排队后慢慢回收
生产环境高可用WebHook主动推送 + 重试机制

​
查询任务状态

获取任务的当前状态与详细元数据（排队信息、运行时长等）。 
curl -X GET "https://api.bizyair.ai/w/v1/webapp/task/openapi/detail?requestId={requestId}" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY"
响应字段（data 内）：
字段类型说明
typestring任务类型，如 "API"
statusstring任务状态枚举
created_atstring创建时间（UTC+8）
updated_atstring最后更新时间
executed_atstring开始执行时间
ended_atstring | null结束时间，未结束为 null
expired_atstring结果文件过期时间
inference_cost_timeinteger推理耗时（秒）
queue_infoobject | null仅 Queuing 时出现
状态枚举：
状态值含义建议操作
Queuing排队中，等待资源调度继续轮询，间隔 1-3 秒
Preparing准备中，正在加载模型 / 环境继续轮询
Running运行中继续轮询
Success成功停止轮询，获取结果
Failed失败停止轮询，检查 error_message
Canceled已取消停止轮询

​
查询任务结果

获取已完成任务的产出物（object_url 等）。 
curl -X GET "https://api.bizyair.ai/w/v1/webapp/task/openapi/outputs?requestId={requestId}" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY"
响应示例： 
{
  "code": 20000,
  "message": "Ok",
  "status": true,
  "data": {
    "request_id": "29f53793-12d3-4dd3-b2a8-4d9848e0c7da",
    "status": "Success",
    "outputs": [
      {
        "object_url": "https://storage.bizyair.ai/outputs/xxx.png",
        "output_ext": ".png",
        "cost_time": 10657,
        "audit_status": 2,
        "error_type": "NOT_ERROR"
      }
    ]
  }
}
outputs[]. 字段说明：
字段类型说明
object_urlstring结果文件下载 URL
output_extstring文件扩展名（含 .）
cost_timeinteger从任务开始到产出此结果的耗时（毫秒）
audit_statusinteger审核状态：1 未审核 / 2 通过 / 3 不通过 / 4 报错
error_typestring失败时为具体错误码，成功为 "NOT_ERROR"
error_msgstring失败时的详细原因（可选）

​
取消任务

仅对排队中（Queuing）的任务生效，将其从队列移除。 
curl -X PUT "https://api.bizyair.ai/w/v1/webapp/task/openapi/cancel?requestId={requestId}" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json"
取消操作是幂等的，重复调用不会产生副作用。若任务已进入运行态，请改用中断任务。

​
中断任务

仅对运行中（Running）的任务生效，强制停止。 
curl -X PUT "https://api.bizyair.ai/w/v1/webapp/task/openapi/interrupt?requestId={requestId}" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json"
中断运行中的任务，已执行部分仍会产生费用。仅当任务处于 Queuing 时取消才不计费。