API 文档

基础信息

Base URL	`http://kb.apimar.online`
Content-Type	`application/json`
字符编码	UTF-8（返回中文不转义）

鉴权

付费接口需在请求头携带用户 API Key，管理接口需携带管理员令牌。

Authorization: Bearer svt_xxxxxxxxxxxxxxxxxxxx
# 也支持：X-API-Key: svt_xxxxxxxxxxxxxxxxxxxx

调用示例

以解析一个视频链接为例（POST /v1/transcribe）。把 YOUR_API_KEY 换成你的密钥。

cURL

curl -X POST http://kb.apimar.online/v1/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://v.douyin.com/xxxxx/"}'

Python

import requests

API_BASE = "http://kb.apimar.online"
API_KEY = "YOUR_API_KEY"

resp = requests.post(
    f"{API_BASE}/v1/transcribe",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"url": "https://v.douyin.com/xxxxx/"},
    timeout=180,
)
data = resp.json()
if resp.ok:
    print("平台:", data["platform"])
    print("文案:", data["transcript"])
    print("本次扣费:", data["billing"]["total_credits"], "积分，余额:", data["balance"])
else:
    print("失败:", data.get("message"), "(stage:", data.get("stage"), ")")

Node.js (v18+，内置 fetch)

const API_BASE = "http://kb.apimar.online";
const API_KEY = "YOUR_API_KEY";

const res = await fetch(`${API_BASE}/v1/transcribe`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://v.douyin.com/xxxxx/" }),
});

const data = await res.json();
if (res.ok) {
  console.log("平台:", data.platform);
  console.log("文案:", data.transcript);
  console.log("扣费:", data.billing.total_credits, "余额:", data.balance);
} else {
  console.error("失败:", data.message, "stage:", data.stage);
}

Node.js (axios)

const axios = require("axios");

const client = axios.create({
  baseURL: "http://kb.apimar.online",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

const { data } = await client.post("/v1/transcribe", {
  url: "https://v.douyin.com/xxxxx/",
});
console.log(data.transcript, "| 余额:", data.balance);

兑换卡密 / 查询余额

# 兑换卡密充值
curl -X POST http://kb.apimar.online/v1/redeem \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"code": "SVT-XXXX-XXXX-XXXX"}'

# 查询余额与邀请信息
curl http://kb.apimar.online/v1/balance -H "Authorization: Bearer YOUR_API_KEY"

POST /v1/transcribe 需要 API Key

解析一个视频/图文链接，返回转写正文、结构化报告与计费明细。仅在处理成功时扣费。

请求体

字段	类型	必填	说明
`url`	string	是	公开的视频或图文链接
`transcribe`	boolean	否	是否执行转写/识别，默认 `true`。为 `false` 时只解析元信息

请求示例

curl -X POST http://kb.apimar.online/v1/transcribe \
  -H "Authorization: Bearer svt_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://v.douyin.com/xxxxx/"}'

成功响应 `200`

{
  "url": "https://v.douyin.com/xxxxx/",
  "platform": "抖音",
  "title": "示例标题",
  "author": "作者",
  "publish_time": "2026-01-01 12:00:00",
  "media_url": "https://.../audio.mp3",
  "content_type": "video",          // 或 "image_note"
  "transcript": "校对后的正文…",
  "corrected": true,
  "report_markdown": "# 视频内容解析报告\n…",
  "notes": "",
  "billing": {
    "base_credits": 1,
    "transcribe_tokens": 1200,
    "correction_tokens": 800,
    "vision_tokens": 0,
    "token_credits": 4,
    "total_credits": 5
  },
  "balance": 92
}

GET /v1/balance 需要 API Key

查询当前账户余额。

{ "balance": 92, "name": "alice" }

GET /v1/usage?limit=50 需要 API Key

查询最近的调用流水（含每次的 token 消耗与扣费）。

{ "usage": [ { "url": "...", "status": "success",
    "transcribe_tokens": 1200, "vision_tokens": 0,
    "credits_charged": 5, "balance_after": 92,
    "created_at": 1768500000.0 } ] }

GET /pricing 公开

返回当前计费费率，供客户端展示价格。

GET /health 公开

健康检查，返回当前使用的模型与解析器配置状态。

管理接口

以下接口用 Authorization: Bearer <ADMIN_TOKEN> 鉴权，用于发放密钥与充值。

POST /admin/users 管理员

创建用户并返回其 API Key。请求体：{ "name": "alice", "initial_credits": 100 }

POST /admin/credits 管理员

给指定用户充值。请求体：{ "api_key": "svt_...", "amount": 100 }

计费规则

每次成功解析的扣费 = 保底积分 + token 附加积分（向上取整）：

项目	费率
保底 / 次	1 积分
语音转写	2.0 积分 / 1K tokens（模型 gpt-4o-transcribe）
文本纠错	1.0 积分 / 1K tokens
图像识别	2.0 积分 / 1K tokens（多模态视觉模型）

附加积分公式：ceil(transcribe/1000×费率 + correction/1000×费率 + vision/1000×费率)，与保底相加为总扣费。解析、下载或转写失败均不扣费。

错误码

HTTP	error	说明
400	missing_url	请求体缺少 url
401	missing_api_key / invalid_api_key	未提供或无效的 API Key
402	insufficient_credits	余额不足以支付保底积分
403	forbidden	管理员令牌无效
502	processing_failed	解析/下载/转写失败（不扣费，含 stage 字段）