跳到主要内容
小豪漫剧XIAOHAO MANJU
首页 模型广场 创作台 价格与充值 接入文档 登录 / 注册
BASE 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。

一个最小示例

bash
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 小时,适合发给客户预览。

http
Authorization: Bearer xhmj_sk_live_7f3a9c2e4b8d1f60
Content-Type: application/json
X-XHMJ-Version: 2026-11-01
  • Key 泄露请立刻在控制台吊销,吊销后 30 秒内全节点生效。
  • 签名头 X-XHMJ-Version 用于锁定接口版本,不传默认用最新版。
  • 浏览器里直接调会返回 40101:我们校验 Origin,前端请走自己的后端转发。
TODO(api): 鉴权中间件待接入

03创建任务

POST https://api.xiaohao-manju.example/v1/tasks

请求字段

字段类型必填说明
typestring是text2image / image2video / text2video / tts / script
modelstring是模型标识,见模型广场,如 kling-1.6
promptstring否文生图 / 文生视频必填,中文即可,最长 2000 字
image_urlstring否图生视频必填,公网可访问的 jpg/png,≤ 10 MB
durationint否单个分镜秒数,4 – 10,默认 5
aspectstring否9:16 / 16:9 / 1:1 / 4:3,默认 9:16
episodesint否批量集数,1 – 12,默认 1
callback_urlstring否回调地址,不填就要自己轮询

请求示例

json
{
  "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"
}

返回示例

json
{
  "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,不会创建任务。

TODO(api): POST /v1/tasks 待接入

04查询任务

GET https://api.xiaohao-manju.example/v1/tasks/{task_id}

状态机只有四个值:queued → running → succeeded / failed。 建议间隔 2 秒轮询,跑完拿到结果就停,别做成 200ms 死循环。

json
{
  "code": 0,
  "data": {
    "task_id": "task_20261120_8f2c9a",
    "status": "running",
    "progress": 62,
    "stage": "image2video",
    "outputs": null,
    "error": null
  }
}

完成后

json
{
  "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 秒。

http
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 分钟直接丢掉。

node
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));
}
TODO(api): 回调投递与重试队列待接入

06错误码表

所有错误都返回 { code, message, data },code 是数字,HTTP 状态码只做粗分类。按 code 分支处理更稳。

codeHTTP含义怎么处理
0200成功照常解析 data
40001400参数缺失或类型不对看 message 里点名的字段,别猜
40002400时长 / 集数越界duration 4–10,episodes 1–12
40101401API Key 无效或已吊销去控制台重新生成,别在前端硬编码
40102401签名过期(回调)时间戳超过 5 分钟,丢弃并记日志
40301403该模型未开通套餐档位不够,去价格页升档
40201402积分不足充值,或降低集数 / 换低倍率模型
40401404任务不存在task_id 抄错,或者已被删除
40901409任务状态不允许该操作已经成功的任务不能再取消
42201422内容审核不通过改提示词,别反复重试同一条
42901429触发限流看 Retry-After 头,指数退避重试
50001500内部错误指数退避,3 次仍失败就提工单
50301503上游模型繁忙换模型或等一会,积分已自动退回
TODO(api): 错误码枚举与后端需保持一致

07限流

限流按 Key 维度算,滑动窗口。响应头会带上当前配额,方便你提前减速,而不是撞墙后再退避。

接口族免费档常用档工作室 / 批量档
创建任务 POST /v1/tasks5 次 / 分30 次 / 分120 次 / 分
查询任务 GET /v1/tasks/{id}60 次 / 分300 次 / 分1200 次 / 分
并发生成任务1 个4 个16 个
剧本改写 type=script10 次 / 分60 次 / 分200 次 / 分
http
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1763600030
Retry-After: 12

撞到 429 时按 Retry-After 等,别用固定 1 秒硬刷 —— 会被判成攻击流量,反而封 10 分钟。

文档看完了,想直接跑一版?

创作台里所有参数都能可视化调,调好之后看右下角的调用示例。

去创作台