API Reference

开发文档

通过 REST API 接入灵慧智慧 AI 平台，轻松集成图片、视频、3D 模型生成能力。

🚀 强烈推荐：使用 Webhook 回调获取结果

提交任务时传入 webhook_url 参数， 任务完成后我们会自动将结果推送到您的服务器。 无需轮询，零延迟，大幅降低您的服务器开销。

零轮询开销 即时结果推送 服务器负载最低

快速开始

1. 在控制台创建 API Key（格式：sk-xxx）

2. 所有 API 请求需在 Header 中携带 X-API-Key 进行鉴权

3. 基础 URL：https://lhzh.site/api/v1

提交生成任务

POST /api/v1/generate

请求参数

参数类型必填说明
modelstring是模型路径，如 wavespeed-ai/flux-dev
promptstring否提示词
imagestring否图片（Base64 或 URL），图生图/图生视频时使用
parametersobject否模型特定参数（如 duration、aspect_ratio 等）
webhook_urlstring否⭐ 推荐！回调通知地址，任务完成后自动推送结果

请求示例（带 Webhook）

cURL
curl -X POST https://lhzh.site/api/v1/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-api-key" \
  -d '{
    "model": "wavespeed-ai/flux-dev",
    "prompt": "A cat wearing a space suit",
    "webhook_url": "https://your-server.com/callback"
  }'

响应示例

JSON Response（异步模型 — 需轮询/Webhook）
{
  "task_id": "pred_abc123",
  "status": "processing",
  "model": "wavespeed-ai/flux-dev",
  "cost": 1,
  "balance_after": 49
}

⚡ 同步返回模式（部分图像模型）

部分图像生成模型（如 nano-banana 系列）支持同步返回， 响应中会直接包含生成结果，无需后续轮询或等待 Webhook。 您可以通过检查响应中是否存在 sync_result 字段来判断。

💡 不处理 sync_result 也完全没问题 — 您仍可使用轮询或 Webhook 来获取结果，系统完全向后兼容。

同步响应示例

JSON Response（同步模型 — 直接返回结果）
{
  "task_id": "vapi_sync_nb_1714838400000",
  "status": "completed",
  "model": "Nano Banana Pro 文生图",
  "cost": 0.08,
  "balance_after": 49.92,
  "sync_result": {
    "type": "image",
    "url": "https://cdn.example.com/generated/xxx.png"
  }
}

客户端处理建议

JavaScript
const res = await fetch('/api/v1/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sk-your-api-key'
  },
  body: JSON.stringify({
    model: 'google/nano-banana-pro/text-to-image',
    prompt: 'A beautiful sunset over the ocean'
  })
})
const data = await res.json()

if (data.sync_result) {
  // 同步模型：直接使用结果
  console.log('图片地址:', data.sync_result.url)
} else {
  // 异步模型：需要轮询或等待 Webhook
  console.log('任务已提交:', data.task_id)
}

Webhook 回调（推荐）

提交任务时传入 webhook_url， 任务完成或失败时，我们会向该地址发送 POST 请求，推送结果数据。

回调要求

成功回调示例

POST → 您的 webhook_url
{
  "task_id": "pred_abc123",
  "status": "completed",
  "model": "wavespeed-ai/flux-dev",
  "result": {
    "type": "image",
    "url": "/api/proxy?url=https://...",
    "thumbnail": null
  },
  "created_at": "2025-03-19T14:00:00.000Z"
}

失败回调示例

POST → 您的 webhook_url
{
  "task_id": "pred_abc123",
  "status": "failed",
  "model": "wavespeed-ai/flux-dev",
  "error": "生成失败: 内容审核未通过",
  "created_at": "2025-03-19T14:00:00.000Z"
}

轮询查询（备选方案）

⚠️ 如果您无法接收 Webhook 回调，也可以通过轮询接口查询任务状态。 建议轮询间隔不低于 10 秒，避免给双方服务器造成不必要的负担。

GET /api/v1/status/{task_id}

请求示例

cURL
curl https://lhzh.site/api/v1/status/pred_abc123 \
  -H "X-API-Key: sk-your-api-key"

响应示例

JSON Response
{
  "task_id": "pred_abc123",
  "status": "completed",
  "result": {
    "type": "image",
    "url": "/api/proxy?url=https://..."
  }
}

两种方式对比

对比项✅ Webhook（推荐）轮询
获取结果延迟即时推送取决于轮询间隔
API 请求量0 次额外请求每次轮询消耗 1 次
服务器负载极低（被动接收）较高（主动请求）
适用场景生产环境、批量任务调试、简单脚本

错误码说明

HTTP 状态码说明
200请求成功
400请求参数错误（缺少 model 等必填字段）
401API Key 无效或未提供
402账户余额不足
404模型不存在或已下线
500服务器内部错误

高可用与自动切换

平台内置智能渠道切换 (Failover) 机制。 当主渠道临时不可用时，系统会自动将请求切换到备用渠道完成生成，整个过程对开发者完全透明。

  • 无需修改任何代码或请求参数
  • 扣费逻辑保持一致，不会重复扣费
  • 部分模型在 Failover 后可能以同步模式返回结果（见上方同步返回说明）
  • 当前支持自动切换的模型：nano-banana、nano-banana-2、nano-banana-pro 系列

准备开始集成？