https://api.xiaohao-manju.example/v1
接口待接入
01快速开始
小豪漫剧的接口只有一个核心动作:提交一个任务,然后拿任务 ID 去查结果。出图、图生视频、配音、剧本改写都走同一套
/v1/tasks,靠 type 字段区分。这样你只需要接一次,后面换模型不用改代码。
下面是最短的完整流程,四步:
- 在控制台拿到
API Key(形如xhmj_sk_...),存到服务端环境变量,别写进前端。 - 调
POST /v1/tasks提交任务,拿到task_id。 - 用
GET /v1/tasks/{id}轮询,或者配一个回调地址等我们推。 - 状态变成
succeeded后,从outputs里取成片和封面的 URL。
一个最小示例
curl -X POST https://api.xiaohao-manju.example/v1/tasks \
-H "Authorization: Bearer $XHMJ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "image2video",
"model": "kling-1.6",
"image_url": "https://your-cdn.example/kf_01.png",
"duration": 5,
"aspect": "9:16"
}'
返回的 data.task_id 就是后面查询用的凭据,务必存下来。
02鉴权
所有请求都要带 Authorization 头,格式是 Bearer <API Key>。Key 分两种:服务端 Key 能调全部接口,
临时 Key 只能查任务、有效期 24 小时,适合发给客户预览。
Authorization: Bearer xhmj_sk_live_7f3a9c2e4b8d1f60 Content-Type: application/json X-XHMJ-Version: 2026-11-01
- Key 泄露请立刻在控制台吊销,吊销后 30 秒内全节点生效。
- 签名头
X-XHMJ-Version用于锁定接口版本,不传默认用最新版。 - 浏览器里直接调会返回
40101:我们校验Origin,前端请走自己的后端转发。
03创建任务
https://api.xiaohao-manju.example/v1/tasks
请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | text2image / image2video / text2video / tts / script |
| model | string | 是 | 模型标识,见模型广场,如 kling-1.6 |
| prompt | string | 否 | 文生图 / 文生视频必填,中文即可,最长 2000 字 |
| image_url | string | 否 | 图生视频必填,公网可访问的 jpg/png,≤ 10 MB |
| duration | int | 否 | 单个分镜秒数,4 – 10,默认 5 |
| aspect | string | 否 | 9:16 / 16:9 / 1:1 / 4:3,默认 9:16 |
| episodes | int | 否 | 批量集数,1 – 12,默认 1 |
| callback_url | string | 否 | 回调地址,不填就要自己轮询 |
请求示例
{
"type": "image2video",
"model": "kling-1.6",
"image_url": "https://cdn.example/kf_01.png",
"duration": 5,
"aspect": "9:16",
"episodes": 2,
"callback_url": "https://your.app/hooks/xhmj"
}
返回示例
{
"code": 0,
"message": "ok",
"data": {
"task_id": "task_20261120_8f2c9a",
"status": "queued",
"credit_cost": 216,
"credit_balance": 1064,
"created_at": "2026-11-20T03:26:00+08:00"
}
}
credit_cost 是提交时就锁定并扣除的,失败会全退。余额不足直接返回 40201,不会创建任务。
04查询任务
https://api.xiaohao-manju.example/v1/tasks/{task_id}
状态机只有四个值:queued → running → succeeded / failed。
建议间隔 2 秒轮询,跑完拿到结果就停,别做成 200ms 死循环。
{
"code": 0,
"data": {
"task_id": "task_20261120_8f2c9a",
"status": "running",
"progress": 62,
"stage": "image2video",
"outputs": null,
"error": null
}
}
完成后
{
"status": "succeeded",
"progress": 100,
"outputs": {
"video_url": "https://cdn.xiaohao-manju.example/out/8f2c9a.mp4",
"cover_url": "https://cdn.xiaohao-manju.example/out/8f2c9a.jpg",
"duration": 30,
"shots": 8
}
}
成片 URL 是签名链接,24 小时后失效,请及时转存到自己的存储。
TODO(api): GET /v1/tasks/{id} 待接入05回调
提交任务时传入 callback_url,状态变化时我们会 POST 一个 JSON 到你那个地址。
收到后请先做两件事:验签、返回 200。5 秒内没收到 200 我们重试,最多 5 次,间隔 1 / 5 / 30 / 300 秒。
POST https://your.app/hooks/xhmj X-XHMJ-Signature: t=1763600000,v1=9f2b7c1e... X-XHMJ-Timestamp: 1763600000 { "event": "task.succeeded", "task_id": "task_20261120_8f2c9a", "status": "succeeded", "outputs": { "video_url": "https://cdn.xiaohao-manju.example/out/8f2c9a.mp4" } }
验签逻辑
把 timestamp + "." + raw_body 用 HMAC-SHA256 加你的回调密钥算一遍,和 v1 里的值比对。时间戳超过 5 分钟直接丢掉。
import crypto from 'node:crypto'; function verify(rawBody, header, secret) { const parts = Object.fromEntries( header.split(',').map(p => p.split('=')) ); // t=时间戳 v1=签名 const payload = parts.t + '.' + rawBody; const mine = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return crypto.timingSafeEqual(Buffer.from(mine), Buffer.from(parts.v1)); }
06错误码表
所有错误都返回 { code, message, data },code 是数字,HTTP 状态码只做粗分类。按 code 分支处理更稳。
| code | HTTP | 含义 | 怎么处理 |
|---|---|---|---|
| 0 | 200 | 成功 | 照常解析 data |
| 40001 | 400 | 参数缺失或类型不对 | 看 message 里点名的字段,别猜 |
| 40002 | 400 | 时长 / 集数越界 | duration 4–10,episodes 1–12 |
| 40101 | 401 | API Key 无效或已吊销 | 去控制台重新生成,别在前端硬编码 |
| 40102 | 401 | 签名过期(回调) | 时间戳超过 5 分钟,丢弃并记日志 |
| 40301 | 403 | 该模型未开通 | 套餐档位不够,去价格页升档 |
| 40201 | 402 | 积分不足 | 充值,或降低集数 / 换低倍率模型 |
| 40401 | 404 | 任务不存在 | task_id 抄错,或者已被删除 |
| 40901 | 409 | 任务状态不允许该操作 | 已经成功的任务不能再取消 |
| 42201 | 422 | 内容审核不通过 | 改提示词,别反复重试同一条 |
| 42901 | 429 | 触发限流 | 看 Retry-After 头,指数退避重试 |
| 50001 | 500 | 内部错误 | 指数退避,3 次仍失败就提工单 |
| 50301 | 503 | 上游模型繁忙 | 换模型或等一会,积分已自动退回 |
07限流
限流按 Key 维度算,滑动窗口。响应头会带上当前配额,方便你提前减速,而不是撞墙后再退避。
| 接口族 | 免费档 | 常用档 | 工作室 / 批量档 |
|---|---|---|---|
创建任务 POST /v1/tasks | 5 次 / 分 | 30 次 / 分 | 120 次 / 分 |
查询任务 GET /v1/tasks/{id} | 60 次 / 分 | 300 次 / 分 | 1200 次 / 分 |
| 并发生成任务 | 1 个 | 4 个 | 16 个 |
剧本改写 type=script | 10 次 / 分 | 60 次 / 分 | 200 次 / 分 |
X-RateLimit-Limit: 30 X-RateLimit-Remaining: 27 X-RateLimit-Reset: 1763600030 Retry-After: 12
撞到 429 时按 Retry-After 等,别用固定 1 秒硬刷 —— 会被判成攻击流量,反而封 10 分钟。
创作台里所有参数都能可视化调,调好之后看右下角的调用示例。