REST API 参考（备用）

本页是 commonsrv 底层 HTTP 接口的参考文档，仅用于以下场景：你所在的运行时无法引入 SDK（例如某些嵌入式环境、CLI 工具、其它语言后端）、你正对接 OpenAI 兼容客户端（LangChain / Cherry Studio 等），或你在排查网络层问题。

日常接入请回到主文档 /docs：用 CommonSrv.billing.* / CommonSrv.ai(...) / CommonSrv.auth.* 等命名空间 API， token、续期、401 重试、异步轮询、跨标签同步全部由 SDK 内部处理。

所有 REST 路径基址：https://<your-commonsrv-host>/api/public/v1

⛔ 红线： 使用 REST 时，Bearer token 必须来自 SDK 的CommonSrv.auth.getAccessToken() 或你后端已保存的 access_token；永远不要自己实现 refresh_token 轮换、自建轮询、把 token 传给第三方来源。这些能力都封装在 SDK 里；如果你正在手写这些逻辑，说明应该回到 /docs 用 SDK。

钱包（REST）

SDK 等价写法：await CommonSrv.billing.balance() / await CommonSrv.billing.ledger({ page, pageSize })。

GET/api/public/v1/walletBearer当前积分钱包

输出

字段	类型	必填	说明
balance	number	可选	当前可用积分余额
total_earned	number	可选	累计获得积分（订阅 + 积分包 + 赠送）
total_spent	number	可选	累计消费积分

GET/api/public/v1/wallet/ledger?limit=50Bearer积分流水（对账 / 导出用，最新在前）

输入

字段	类型	必填	说明
limit	number (query)	可选	每页数量，默认 50，最大 200
cursor	string (query)	可选	分页游标，传上一次返回的 next_cursor

输出

字段	类型	必填	说明
entries	LedgerEntry[]	可选	流水项数组，含 id / delta / balance_after / reason / ref_type / ref_id / created_at
next_cursor	string \| null	可选	下一页游标，null 表示无更多

curl https://<your-commonsrv-host>/api/public/v1/wallet \
  -H "Authorization: Bearer $ACCESS_TOKEN"

AI 调用（REST · LLM / 图像 / 视频 / TTS）

SDK 等价写法：await CommonSrv.ai(modelKey, input)（同步 llm） /await CommonSrv.ai.submit(modelKey, input) + await CommonSrv.ai.wait(job_id, { onProgress })（异步任务）。

模型目录

只需指定 model_key，路由、权重、降级由服务端统一调度。

GET/api/public/v1/modelsBearer启用的模型列表

输出

字段	类型	必填	说明
model_key	string	可选	模型标识，如 "google/gemini-2.5-flash"
display_name	string	可选	人类可读的模型名称
category	string	可选	"llm" \| "image" \| "video" \| "tts" \| "stt"；非 llm 类必须走 /ai/jobs
enabled	boolean	可选	是否启用

同步调用（LLM）

POST/api/public/v1/ai/invokeBearer通用 LLM 调用，自动扣积分

输入

字段	类型	必填	说明
model_key	string	必填	模型标识，如 "google/gemini-2.5-flash"
messages	Message[]	必填	OpenAI 风格的消息数组
params	object	可选	本次请求覆盖参数。优先级：Model Key 默认参数 → 请求 params → 通道协议适配
ref_type	string	可选	你系统的业务类型，用于流水溯源
ref_id	string	可选	你系统的业务 ID（建议每次请求唯一）
meta	object	可选	meta.feature 控制统计页「功能」列显示，用法见 /docs 的多语言章节

输出

字段	类型	必填	说明
ok	boolean	可选	调用是否成功
text	string	可选	模型返回的文本内容
usage	{ input_tokens, output_tokens }	可选	本次调用的 token 用量
credits_consumed	number	可选	本次扣减的积分数
balance_after	number	可选	扣费后用户当前余额

POST/api/public/v1/chat/completionsBearerOpenAI 兼容入口（可对接 OpenAI SDK / LangChain / Cherry Studio）。当前仅支持非流式 (stream:false)。

输入

字段	类型	必填	说明
model	string	必填	对应 model_key
messages	Message[]	必填	OpenAI chat messages
max_tokens	number	可选	最大生成 token 数
temperature	number	可选	温度参数 0~2
thinking	{ type: enabled \| disabled }	可选	思考模式开关；deepseek-v4-pro / genllm / genlongtext 默认关闭，需要推理的业务须显式开启
reasoning_effort	low \| medium \| high \| xhigh \| max	可选	思考强度；DeepSeek V4 将 medium/xhigh 映射为 high
top_p	number	可选	核采样参数；通道会移除与推理模式互斥的字段
response_format	object	可选	结构化输出格式，如 { type: json_object }
frequency_penalty	number	可选	频率惩罚；不支持的通道会移除
presence_penalty	number	可选	存在惩罚；不支持的通道会移除
stop	string \| string[]	可选	停止序列
system_prompt	string	可选	附加系统提示词
timeout_ms	number	可选	本次上游调用超时；受服务端安全上限约束
stream	boolean	可选	暂不支持，必须为 false 或省略

输出

字段	类型	必填	说明
(OpenAI 标准字段)	object	可选	id / choices / usage 等 OpenAI chat.completion 字段
credits_consumed	number	可选	附加字段：本次扣减积分

给 OpenAI 兼容流水打功能名（body 不能加自定义字段，改用 HTTP header）：
• X-CommonSrv-Feature: 解析剧本 — 简写，直接传功能名字符串。
• X-CommonSrv-Meta: {"feature":{"zh-CN":"解析剧本","en":"Parse Script"}} — 完整 JSON，与 /ai/invoke 的 meta 一致。
两个 header 同时给以 X-CommonSrv-Meta 为准。

curl -X POST https://<your-commonsrv-host>/api/public/v1/ai/invoke \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model_key":"google/gemini-2.5-flash","messages":[{"role":"user","content":"hi"}]}'

异步任务（LLM 长任务 / 图像 / 视频 / TTS）

统一入口，兼容所有 category：llm（长文本 / 深度推理）、image、video、tts、stt。 LLM 长任务模式下最长可跑到 24 小时。用 SDK 时请优先 CommonSrv.ai.wait，内置指数退避轮询，避免自建 setInterval。

LLM 参数推荐直接放在 input 顶层；兼容旧调用的 input.params 也会由服务端规范化。参数同样遵循“Model Key 默认值 → 请求覆盖 → 通道适配”，DeepSeek 系列默认关闭推理，需要时请显式开启。

POST/api/public/v1/ai/jobsBearer创建异步任务

输入

字段	类型	必填	说明
model_key	string	必填	任意模型
input	object	必填	LLM：{ messages, ... }；图像/视频/语音：{ prompt, ... }
callback_url	string	可选	可选的单任务 Webhook 覆盖地址；省略则使用项目统一 Webhook URL。必须 https 且命中项目允许来源域名
ref_type	string	可选	业务类型
ref_id	string	可选	业务 ID（建议唯一）
meta	object	可选	同 /ai/invoke.meta，随任务落库

输出

字段	类型	必填	说明
job_id	string (uuid)	可选	任务 ID
status	"pending"	可选	初始状态

GET/api/public/v1/ai/jobs/:idBearer查询任务状态（轮询）

输出

字段	类型	必填	说明
status	"pending" \| "running" \| "succeeded" \| "failed"	可选	任务状态
progress	number	可选	0~100
output	object	可选	succeeded 时的模型输出，按 category 对齐 OpenAI 协议：LLM→chat.completion（choices[]）；Image→images.generations（data[]）；Video→videos（Sora 基座 + data[]）；TTS→audio.speech（data[]）；STT→transcriptions（text）
error	string	可选	failed 时的错误信息
credits_consumed	number	可选	完成后实际扣减的积分

POST/api/public/v1/media/assets/resolveBearer批量刷新任务结果中的媒体读取地址（最多 100 个）

输入

字段	类型	必填	说明
ids	string[]	必填	任务 output.data[].media_asset_id 数组；只返回当前用户可访问且已就绪的资源

输出

字段	类型	必填	说明
assets	MediaAsset[]	可选	包含 id / kind / content_type / size_bytes / url / url_expires_at

POST/api/public/v1/media/assets/intentsBearer创建业务媒体意图。仅在项目已启用 CloudBase 媒体灰度且服务端完整配置后可用；项目和用户从 CommonSrv Bearer JWT 推导。请求不能指定对象路径、存储 provider、CloudBase fileID 或完整 URL。完成后必须继续请求 upload-ticket、浏览器直传和 complete，不能把文件主体发到本接口。

输入

字段	类型	必填	说明
kind	"image" \| "video" \| "audio"	必填	媒体类别
content_type	string	必填	必须与 kind 匹配
size_bytes	integer	必填	1~536870912
source_ref	string \| null	可选	可选业务来源引用
visibility	"private" \| "public"	可选	默认 private
idempotency_key	string	可选	可选，重复创建时复用 pending 意图

输出

字段	类型	必填	说明
asset.id	uuid	可选	供业务表持久化和后续解析的非透明媒体 ID
asset.status	"pending"	可选	尚未就绪，不能读取
upload.object_key	string	可选	CommonSrv 分配的直传目标；不是 URL 或凭据
reused	boolean	可选	相同幂等键复用了现有 pending 意图

POST/api/public/v1/media/assets/:id/upload-ticketBearer为当前用户自己仍处于 pending 的媒体意图签发一次短期 CloudBase 自定义登录 Ticket。只能从你的服务端调用：CommonSrv JWT、CloudBase 私钥和 CAM 凭据都不能进入浏览器。

输出

字段	类型	必填	说明
asset.id	uuid	可选	与 pending 意图相同的资源 ID
upload.env_id	string	可选	传统 CloudBase Storage 环境 ID
upload.object_key	string	可选	唯一允许直传的对象路径
upload.ticket	string	可选	短期自定义登录 Ticket；不是 CAM 密钥或永久凭据
upload.ticket_expires_in	integer	可选	秒；过期后重新请求本接口

POST/api/public/v1/media/assets/:id/completeBearer浏览器用传统 CloudBase Web SDK 直传成功后，由你的服务端提交 SDK 返回的 file_id。CommonSrv 会重新校验固定路径、对象大小、MIME 和文件签名，只有通过后才会将资源标记 ready。

输入

字段	类型	必填	说明
file_id	string	必填	CloudBase Web SDK uploadFile 返回的 fileID

输出

字段	类型	必填	说明
asset.id	uuid	可选	资源 ID
asset.status	"ready"	可选	校验成功后可读取
asset.url	string	可选	经项目和用户授权后返回的短期读取地址；不是应持久化的 URL，也不包含 CAM 凭据
asset.url_expires_at	datetime \| null	可选	读取地址到期时间

POST/api/public/v1/media/assets/:id/abortBearer关闭失败的浏览器直传意图。若浏览器已取得 CloudBase file_id，CommonSrv 会先删除该精确对象再退休中央记录；未取得 file_id 时只退休 pending 记录，必须由 COS 为 user-assets/ 配置的生命周期规则清理无法确认的孤儿对象。对象路径、所有者与 provider 均从已认证的中央记录推导。

输入

字段	类型	必填	说明
file_id	string	可选	仅在 SDK 已返回 fileID、但 complete 或业务绑定失败时提交

输出

字段	类型	必填	说明
asset.id	uuid	可选	已退休的资源 ID
asset.deleted	true	可选	中央记录已标记删除
asset.providerDeleted	boolean	可选	是否删除了已确认的 CloudBase 对象

GET/api/public/v1/media/assets/:idBearer解析单个已就绪媒体的短期读取地址；只允许资源所属项目和用户读取。

DELETE/api/public/v1/media/assets/:idBearer删除所属媒体。对尚未上传的 pending 意图只逻辑删除元数据；对象已存在时由 CommonSrv 删除对象后标记删除。

输出

字段	类型	必填	说明
deleted	boolean	可选	对象与中央媒体记录均已删除

# 1) 提交任务
curl -X POST https://<your-commonsrv-host>/api/public/v1/ai/jobs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model_key": "genlongtext",
    "input": {
      "messages": [{"role":"user","content":"写一篇 5000 字的深度分析..."}],
      "max_tokens": 8000,
      "thinking": {"type":"enabled"},
      "reasoning_effort": "high"
    }
  }'
# → { "ok": true, "job_id": "xxxx-...", "status": "pending" }

# 2) 轮询结果（每 3~5 秒一次；SDK 已内置指数退避）
curl https://<your-commonsrv-host>/api/public/v1/ai/jobs/xxxx-... \
  -H "Authorization: Bearer $ACCESS_TOKEN"

统一换脸 / 换人 · change-face / change-person

业务按能力选择 model_key，并通过 subject_mappings 将每个原人物、目标人物和声音设置一一绑定； Magic Hour、AKOOL、腾讯 MPS 或后续供应商只存在于后台通道。通道启用合规检测后，素材必须先通过 compliance_check。

curl -X POST https://<your-commonsrv-host>/api/public/v1/ai/jobs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model_key": "change-person",
    "input": {
      "source": { "type": "video", "url": "https://cdn.example.com/source.mp4" },
      "subject_mappings": [{
        "id": "person-1",
        "source_subject": {
          "selection": "reference_image",
          "reference_image_urls": ["https://cdn.example.com/original-person.jpg"]
        },
        "target": { "type": "image", "url": "https://cdn.example.com/person.jpg" },
        "voice": { "mode": "preserve" }
      }],
      "audio": { "mode": "preserve" },
      "options": {
        "preserve_audio": true,
        "preserve_timing": true,
        "preserve_camera": true,
        "preserve_motion": true,
        "preserve_background": true
      }
    }
  }'

工具型接口（REST · 接口管理）

接口管理下的一次性工具型接口（如音色克隆、抖音视频解析等）。 SDK 使用方式：await CommonSrv.rest('/endpoints/<key>', { method:'POST', body: JSON.stringify({ input, meta }) })。

GET/api/public/v1/endpointsPublic列出当前启用的工具型接口（动态发现）

输出

字段	类型	必填	说明
items	Endpoint[]	可选	含 key / display_name / description / category / pricing_rule / pricing_summary / request_schema

POST/api/public/v1/endpoints/:keyBearer调用一个工具型接口（自动通道 failover、自动扣费）

输入

字段	类型	必填	说明
:key	string (path)	必填	接口标识，从 GET /endpoints 获取
input	object	必填	上游入参，原样透传（见 GET /endpoints 的 request_schema）
ref_type	string	可选	业务类型
ref_id	string	可选	业务 ID（建议唯一）
meta	object	可选	meta.feature 用法同 /ai/invoke

输出

字段	类型	必填	说明
ok	boolean	可选	是否成功
output	object	可选	上游返回结果，原样透传
credits_charged	number	可选	本次实际扣减积分
balance	number \| null	可选	扣费后余额

GET/api/public/v1/endpoints/:key?job_id=:job_idBearer轮询异步工具任务（视频、语音合规检测等）

输入

字段	类型	必填	说明
:key	string (path)	必填	必须与创建任务时的接口 key 相同
job_id	uuid (query)	必填	POST 返回的 CommonSrv 工具任务 ID

输出

字段	类型	必填	说明
status	"running" \| "succeeded" \| "failed"	可选	任务状态
output	object	可选	最终统一输出
error	string \| null	可选	失败原因

统一合规检测 · compliance_check

一次请求可混合文字、图片、视频和语音。同步素材直接返回终态；包含视频或语音时可能返回status: running 与 job_id，再使用上面的 GET 接口轮询。

curl -X POST https://<your-commonsrv-host>/api/public/v1/endpoints/compliance_check \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "content": [
        { "type": "text", "text": "待检测文字" },
        { "type": "image", "url": "https://cdn.example.com/image.jpg" },
        { "type": "video", "url": "https://cdn.example.com/video.mp4" },
        { "type": "audio", "url": "https://cdn.example.com/audio.mp3" }
      ]
    }
  }'

# 异步时轮询；终态 output 固定包含 verdict / passed / risk_level / labels / results
curl "https://<your-commonsrv-host>/api/public/v1/endpoints/compliance_check?job_id=<job_id>" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

示例 · minimax-voice-design（音色克隆）

preview_text 必填（上游用它合成试听音频），本接口按其字符数计费（中日韩字符按 2 计）。成功响应中的 output 含 media_asset_id 与短期 url；原始试听音频不会透传，业务侧应保存媒体 ID；若项目未启用媒体存储或服务端配置不完整，接口会在调用上游前返回 ENDPOINT_MEDIA_STORAGE_UNAVAILABLE。

curl -X POST https://<your-commonsrv-host>/api/public/v1/endpoints/minimax-voice-design \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "prompt": "温柔女声，30 岁左右", "gender": "female", "age": "young",
               "preview_text": "你好，这是一段试听文本。" },
    "ref_type": "your_app", "ref_id": "voice-clone-001"
  }'

示例 · apify-run-actor（按服务方实际花费计费）

curl -X POST https://<your-commonsrv-host>/api/public/v1/endpoints/apify-run-actor \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "actor_id": "apify/website-content-crawler",
      "run_input": { "startUrls": [{ "url": "https://example.com" }] },
      "fetch_items": true, "item_limit": 100
    }
  }'

示例 · douyindl（抖音视频解析）

curl -X POST https://<your-commonsrv-host>/api/public/v1/endpoints/douyindl \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "url": "https://v.douyin.com/xxxxxxx/" } }'

邀请奖励 / 分销（REST）

SDK 侧只对外暴露 CommonSrv.invite.open()（打开一体化邀请中心），所有数据接口都由 /invite 页面内部消费；本节仅供无法引入 SDK 的运行时（后端 / 其他语言 / CLI）参考。规则、币种、奖励额度均在后台按项目独立配置，REST 只暴露读取和提现申请。

注册时携带邀请码（终端用户注册接口）

邀请关系不可补 —— 必须在注册那一次调用带上 ref_code；已注册用户后续再带 ref_code 也不会绑定。

POST/api/public/v1/auth/app/signupX-Api-Key终端用户注册（邀请码上报即在此接口）

输入

字段	类型	必填	说明
email	string	必填	登录邮箱
password	string	必填	密码
ref_code	string	可选	邀请码（8 位大写字母数字，如 A3F9K2LX）。SDK 加载时自动从 ?ref= 捕获并本地持久化，随后 auth.openLogin 会自动带上，无需手动传。

输出

字段	类型	必填	说明
user	object	可选	app 用户对象
session	object	可选	access_token / refresh_token 等

邀请中心 · 概览

返回当前登录 app 用户的邀请码、链接、规则快照、拉新统计与现金钱包。

GET/api/public/v1/invite/meBearer邀请中心概览

输出

字段	类型	必填	说明
code	string	可选	邀请码，8 位大写字母数字
invite_link	string	可选	完整邀请链接（含 ?ref=）
project	{ id, name }	可选	所属项目
settings	object	可选	邀请规则快照：enabled / bind_ttl_days / invitee_welcome / inviter_signup / inviter_first_purchase / inviter_commission（rate · duration_days · currency · min_payout_cents）
stats	object	可选	拉新统计：invited_total / invited_active / invited_first_purchased / earned_by_type
cash	object	可选	现金钱包：balance_cents / total_earned_cents / total_withdrawn_cents / currency / min_payout_cents

邀请历史与排行榜

GET/api/public/v1/invite/history?page=1&page_size=20Bearer当前用户已邀请的用户列表（含状态、首购时间、分成到期时间）

GET/api/public/v1/invite/leaderboard?limit=20Bearer项目内邀请排行榜（昵称已脱敏，非本项目管理员不可见完整信息）

输出

字段	类型	必填	说明
items	LeaderboardItem[]	可选	{ rank, nickname, invited_active, invited_first_purchased }

现金提现（银行卡）

低于 min_payout_cents 会 400 AMOUNT_BELOW_MIN；余额不足 400 INSUFFICIENT_BALANCE；24h 内已有 pending 申请 409 PENDING_WITHDRAWAL_EXISTS。

GET/api/public/v1/invite/withdraw?page=1&page_size=20Bearer申请历史（pending / approved / rejected / paid）

POST/api/public/v1/invite/withdrawBearer发起一笔提现申请（自动冻结余额，等待后台审核 / 打款）

输入

字段	类型	必填	说明
amount_cents	number	必填	提现金额（分）；≥ min_payout_cents
bank_name	string	必填	银行名称
bank_account_no	string	必填	银行卡号
account_holder	string	必填	开户人姓名

输出

字段	类型	必填	说明
ok	boolean	可选	true
id	string	可选	提现单 id
status	string	可选	"pending"

# 1) 读取邀请中心
curl https://<your-commonsrv-host>/api/public/v1/invite/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 2) 发起提现（¥100 = 10000 分）
curl -X POST https://<your-commonsrv-host>/api/public/v1/invite/withdraw \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 10000,
    "bank_name": "招商银行",
    "bank_account_no": "6225 **** **** 1234",
    "account_holder": "张三"
  }'

错误码速查（REST）

402 INSUFFICIENT_CREDITS：积分不足，响应体附带 required 与 current。
404 MODEL_NOT_FOUND：model_key 不存在或已停用。
403 MODEL_DISABLED：模型已被禁用。
400 USE_JOBS_ENDPOINT：该模型是异步类别，请改用 POST /ai/jobs。
429：限流（默认每用户 60 req/min），稍后重试即可。
502 AI_INVOKE_FAILED / MODEL_NOT_ROUTABLE：可重试。

响应体统一形如 { error: "CODE", detail: "..." }。error 是机器可读英文码，detail 仅供日志排查，都不要直接 toast 给用户。展示规范见 /docs。