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
{
  "task_id": "pred_abc123",
  "status": "processing",
  "model": "wavespeed-ai/flux-dev",
  "cost": 1,
  "balance_after": 49
}

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服务器内部错误

准备开始集成？