开放 API 文档（v1）

鉴权（签名换取 authKey）

为避免密钥在网络上传输，API 采用两段式鉴权：原始 API Key 只在你的服务端本地参与 HMAC 签名运算，用签名换取短时 authKey（有效期 15 分钟），业务接口只接受 authKey。直接在请求头里发送 sk_kipin_ 原始密钥会被拒绝（raw_key_not_allowed）。

1. 本地计算签名密钥 signingKey = hex(SHA-256(API Key))，再对 keyId.timestamp.nonce 做 HMAC-SHA256 得到 signature。
2. 调用 POST /api/v1/auth/token 换取 authKey（15 分钟有效，过期随时重新换取）。
3. 之后所有接口用 Authorization: Bearer authKey 调用。

签名规范与请求体（keyId 与密钥一同下发；timestamp 为 Unix 秒，允许 ±300 秒时钟偏差；nonce 为 8–128 位随机串，窗口期内不可复用）：

message    = `${keyId}.${timestamp}.${nonce}`
signingKey = hex(SHA-256(API Key))          // 服务端只存此哈希,可直接验签
signature  = hex(HMAC-SHA256(signingKey, message))

POST /api/v1/auth/token
{
  "keyId": "apikey-xxxxxxxx",   // 密钥 ID(与密钥一同下发)
  "timestamp": 1782981000,      // Unix 秒,允许 ±300s 时钟偏差
  "nonce": "b3f1c9d0a4e2...",   // 8–128 位随机串,窗口期内不可复用
  "signature": "9f86d081884c..."
}

Node.js 签名与换取示例：

import {createHash, createHmac, randomBytes} from 'node:crypto';

const signingKey = createHash('sha256').update(process.env.KIPIN_API_KEY).digest('hex');
const timestamp = Math.floor(Date.now() / 1000);
const nonce = randomBytes(16).toString('hex');
const signature = createHmac('sha256', signingKey)
  .update(`${process.env.KIPIN_KEY_ID}.${timestamp}.${nonce}`)
  .digest('hex');

const {authKey, expiresIn} = await fetch(`${BASE}/auth/token`, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({keyId: process.env.KIPIN_KEY_ID, timestamp, nonce, signature}),
}).then((r) => r.json());

响应

{
  "ok": true,
  "tokenType": "Bearer",
  "authKey": "eyJhbGciOiJIUzI1NiJ9...",
  "expiresIn": 900
}

拿到 authKey 后，所有业务接口统一通过请求头传递：

Authorization: Bearer <authKey>

请妥善保管 Key：仅在服务端参与签名，不要写入前端代码或公开仓库。原始 Key 永远不需要（也不应该）通过网络发送。

快速开始

四步完成一次生成：签名换 authKey → 列模型 → 创建任务 → 轮询结果。

# 0) 签名换取 authKey（shell + openssl 示例）
SIGNING_KEY=$(printf %s "$KIPIN_API_KEY" | openssl dgst -sha256 -hex | awk '{print $NF}')
TS=$(date +%s); NONCE=$(openssl rand -hex 16)
SIG=$(printf %s "$KIPIN_KEY_ID.$TS.$NONCE" | openssl dgst -sha256 -hmac "$SIGNING_KEY" -hex | awk '{print $NF}')
AUTH_KEY=$(curl -s -X POST https://kipin.soyoco.top/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d "{\"keyId\":\"$KIPIN_KEY_ID\",\"timestamp\":$TS,\"nonce\":\"$NONCE\",\"signature\":\"$SIG\"}" \
  | jq -r .authKey)

# 1) 列出可用模型
curl -H "Authorization: Bearer $AUTH_KEY" \
  https://kipin.soyoco.top/api/v1/models

# 2) 创建生成任务
curl -X POST https://kipin.soyoco.top/api/v1/generations \
  -H "Authorization: Bearer $AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "platform": "volcengine",
    "model": "doubao-seedream-5-0-260128",
    "prompt": "A cinematic photo of a red fox in snow"
  }'

# 3) 轮询任务状态
curl -H "Authorization: Bearer $AUTH_KEY" \
  https://kipin.soyoco.top/api/v1/generations/task-xxxxxxxx

模型参数矩阵

各模型支持的能力与参数范围不同，创建任务时的 duration / resolution / 参考素材数量必须落在下表范围内，否则返回 generation_rejected。数据与站内生成页、后端校验同源，实时反映当前启用的模型。

图像模型（type: image）

视频模型（type: video）

3D 模型（type: 3d）

说明：t2i=文生图,i2i=图生图(需参考图),t2v=文生视频,i2v=图生视频(需 1 张图),v2v=视频生视频(需视频),r2v=参考生视频(图/视频参考均可)。「—」表示该项不适用或由引擎自动决定。参考素材通过 inputUrl / inputUrls 以公网 URL 传入。

任务状态与轮询

任务创建后异步执行，状态流转如下：

建议每 3–5 秒轮询一次；图片任务通常几十秒内完成，视频任务可能需要数分钟。

const BASE = 'https://kipin.soyoco.top/api/v1';
// authKey 来自上文 POST /auth/token(有效期 15 分钟,过期重新换取即可)
let authKey = await exchangeAuthKey();

async function waitForTask(id) {
  for (;;) {
    const res = await fetch(`${BASE}/generations/${id}`, {
      headers: {Authorization: `Bearer ${authKey}`},
    });
    if (res.status === 401) {
      // token 端点有 30 次/分钟限流,先退避再重新换取,避免自旋撞 429
      await new Promise((ok) => setTimeout(ok, 2000));
      authKey = await exchangeAuthKey();
      continue;
    }
    const task = await res.json();
    if (task.status === 'succeeded') return task.outputUrl;
    if (task.status === 'failed' || task.status === 'cancelled') {
      throw new Error(task.error?.message || task.status);
    }
    await new Promise((ok) => setTimeout(ok, 5000));
  }
}

错误码

出错时响应包含 ok=false 与 error 字段（多数场景附带 message），并配合以下 HTTP 状态码：