接入文档

本服务只支持 SDK 接入。浏览器端 1 个文件，Node 端 1 个文件。

也可直接 <script src="https://<your-commonsrv-host>/sdk/commonsrv-browser.js"></script> 引用。

两个 SDK 各干什么？怎么配合？

两个 SDK 不是二选一，也不是"浏览器 SDK 通过服务端 SDK 转发"。它们分别驻扎在浏览器和你的后端，各自直连 CommonSrv，处理只有自己那一侧能安全做的事，再通过用户身份（app_user）和订单 Webhook 串起来。

配合方式（典型时序）

浏览器 (Browser SDK)                你的后端 (Node SDK)                CommonSrv
      │                                    │                                │
① 用户点"购买"                             │                                │
   billing.open()  ─────────────────────────────────────────────────────►   │  弹出购买页
② 用户付款完成                             │                                │
   (前端只收到 UX 事件 order.paid, 用来刷新 UI；权益开通不能只信这个)        │
      │                                    │◄── ③ Webhook (签名)  ──────    │
      │                                    │    cs.mount 内部验签           │
      │                                    │    onPaid(data) → 你落库/发权益 │
      │                                    │                                │
④ 之后调用 AI                              │                                │
   ai.submit(...)  ─────────────────────────────────────────────────────►   │  扣积分 + 派发上游
      │                                    │                                │
   (可选) 长任务想在后端跑：                │                                │
      │    传当前用户 access_token 给后端 → cs.ai.useToken(t).submit(...)  ─►

• Browser SDK 必装：只要终端用户在浏览器里操作（登录 / 付款 / 用 AI），就用它。购买弹窗、AI 调用、endpoints、对象存储上传都直接在这里做，不需要经过你的后端中转。
• Node SDK 什么时候真的需要装：只在下面这些场景才装，不要平白拉入：
  • 接 Webhook（强烈建议）：付款成功后把订单 / 权益写进你自己的数据库——这是权益开通的唯一可信源，前端 order.paid 事件只做 UX。
  • 后台看某用户余额：服务端要展示 / 风控 / 门槛判断时用 cs.wallet.balance(userAccessToken)。
  • （不常用）自建订单页、定时任务代用户跑 AI、Node 侧本地文件传 对象存储——见上表【一般不用】项。
• 不做的事：Browser SDK 不会把请求转发给你的后端再由后端打 CommonSrv；Node SDK 也不是浏览器 SDK 的代理层。两边都直连 CommonSrv，只是各自带的凭证不同：浏览器带用户 access_token，Node 带项目 API Key（或用 useToken 临时借用用户 token）。

语言代号统一走 BCP-47（en / zh-CN / zh-TW / ja / ko / es…）。 业务端要做的事：① 切 UI 语言（SDK 打开的所有弹窗跟随）；② 在请求 meta 里给出需要多语言展示的字段。

① UI 语言

SDK 自动跟随用户账户偏好 / 浏览器语言，无需在 configure 中传 lang。用户切换语言统一在 CommonSrv.profile.open() 集成页面内完成，业务端不需要也不应该再做语言切换 UI。当前 UI 已上线 en / zh-CN / zh-TW，后续持续新增。

// 运行时读取（登录时来自账户，未登录来自本地/浏览器）
const lang = await CommonSrv.lang.getLang();

② meta.feature —「功能」显示名（用户端唯一入口）

CommonSrv.ai(...) / CommonSrv.ai.submit(...) / CommonSrv.endpoints.call(...) 的 opts.meta.feature可以供 commonsrv 系统中需要多语言切换显示的时候使用，比如用户积分明细的功能列。两种写法：

// ① 多语（推荐，默认使用这种）
//    只要你的界面需要跟随用户语言切换，一律传多语对象。
{
  meta: {
    feature: {
      "zh-CN": "选品定稿",
      "zh-TW": "選品定稿",
      "en":    "Picking Finalize",
      "ja":    "商品選定"
    }
  }
}

// ② 单语 —— 仅当你确定该场景不需要多语言切换时使用
//    命中内置词典会自动翻译，未命中就原样展示。
{ meta: { feature: "图像生成" } }

多语对象回退规则：当前语言未命中 → 回退 en → 回退字典里任意首个非空值。至少提供 en 一种以保证兜底可读。

前端 1 个按钮 + 后端 1 个接口 + Webhook 1 个处理函数。金额与商品由服务端决定，权益开通以 Webhook 为准。

先在 项目管理 复制 API Key 和 Webhook Secret，并把你应用的域名（开发 / 预览 / 生产）加到 「允许的来源域名」。

① 前端（1 行绑定按钮）

<script src="https://<your-commonsrv-host>/sdk/commonsrv-browser.js"></script>
<button id="buy">购买 / 充值</button>
<script>
  CommonSrv.configure({ clientId: "<your_client_id>" });
  document.querySelector("#buy").addEventListener("click", () =>
    CommonSrv.billing.open({
      onEvent: (e) => e.type === "order.paid" && location.reload(),
    })
  );
</script>

打开形式（mode）

• popup（默认）：SDK 自建的遮罩 + 居中 iframe + 关闭按钮；PC 上占页面 70%（最大 900×800），手机自动全屏。点击弹窗外的遮罩、可见关闭按钮或 Esc 可退出；关闭按钮位于内容区外，手机端有独立顶部空间，不覆盖购买页内的按钮。
• iframe：只创建 <iframe> 挂到你指定的 container，由你控制布局。
• redirect：整页跳转，支付完成后按 return_url 跳回。

// popup（默认）
CommonSrv.billing.open({ onEvent: (e) => e.type === "order.paid" && location.reload() });

// iframe
CommonSrv.billing.open({
  mode: "iframe",
  container: document.getElementById("checkout-box"),
  onEvent: (e) => { if (e.type === "order.paid") location.reload(); },
});

// redirect
CommonSrv.billing.open({ mode: "redirect" });

import express from "express";
import { CommonSrv } from "./commonsrv-node.mjs";

const app = express();
const cs = new CommonSrv({
  apiKey: process.env.COMMONSRV_API_KEY,
  webhookSecret: process.env.COMMONSRV_WEBHOOK_SECRET,
  baseUrl: "https://<your-commonsrv-host>",
});

cs.mount(app, {
  getUserRef: (req) => req.user?.id,
  onPaid: async (data) => {
    // data: { order_no, user_ref, plan_code, pack_code, amount_cents, ... }
    await refreshCredits(data.user_ref);
  },
  onTaskDeliveryReady: async (data, event) => {
    await bindGeneratedResult(data.task_id, event.id);
  },
});

// 开始购买
app.post("/api/billing/start", (req, res) =>
  cs.checkout.start(req, res, { getUserRef: (req) => req.user?.id })
);

// Webhook（内部完成验签 + 事件路由）
app.post("/webhooks/commonsrv", cs.webhooks.handler({
  onOrderPaid:     async (data) => { await refreshCredits(data.user_ref); },
  onOrderRefunded: async (data) => { await revokeAccess(data.user_ref); },
  onTaskDeliveryReady: async (data, event) => {
    // data.task_id 已完成生成和转存。用项目 API Key 读取该任务结果，
    // 按提交时的 delivery_binding 幂等写入业务表，再提交资源引用回执。
    await bindGeneratedResult(data.task_id, event.id);
  },
  onEvent: async (event) => { await recordKnownEvent(event.id, event.event); },
}));

cs.ai.useToken(userAccessToken);   // 传入该用户的 access_token
const { job_id } = await cs.ai.submit("kling-v2", { prompt: "..." });
const done   = await cs.ai.wait(job_id);

// 只要求登录
app.get("/api/any-login", cs.auth.requireUser(), (req, res) => {
  // req.commonsrvUser = { id, project_id, display_name, role_codes, ... }
  res.json({ hello: req.commonsrvUser.display_name });
});

// 要求管理员角色（数组表示"任一即可"）
app.get("/api/admin/x", cs.auth.requireRole(["admin", "operator"]), (req, res) => {
  res.json({ ok: true });
});

// 手动校验（框架无关）
const user  = await cs.auth.me(accessToken);              // { role_codes: ["admin"], ... }
const isAdm = await cs.auth.hasRole(accessToken, "admin"); // true / false

CommonSrv.requireUser() 一行搞定：未登录自动弹登录 → 之后所有 SDK 调用自动带 Bearer、静默续期、401 自动重试、跨标签同步。

登录页按「项目管理 → 配置 → 登录配置」生效（启用的登录方式、是否开放注册、是否人机验证）；修改后立即跟随，无需改代码。 必须先在 项目管理 拿到 clientId。

三步接入

<script src="https://<your-commonsrv-host>/sdk/commonsrv-browser.js"></script>
<script>
  // ① 配置一次
  CommonSrv.configure({ clientId: "<your_client_id>" });

  // ② 登录（未登录自动弹登录页；也可用 CommonSrv.auth.openLogin({ view }) 主动打开）
  const user = await CommonSrv.requireUser();

  // ③ 之后调各功能命名空间即可（token 全自动）
  const wallet = await CommonSrv.billing.balance();

  // 监听会话变化（含跨标签页同步）
  CommonSrv.auth.onChange((e) => { if (!e.session) location.href = "/"; });

  // 退出登录
  // await CommonSrv.auth.logout();
</script>

登录页打开形式（mode）

// popup（默认）
await CommonSrv.auth.openLogin();

// iframe — 内嵌到页面某个区域
await CommonSrv.auth.openLogin({ mode: "iframe", container: document.getElementById("login-box") });

// redirect — 整页跳转
CommonSrv.auth.openLogin({ mode: "redirect" });

用户信息 API

两个读用户的方法：CommonSrv.user() 同步读缓存（首屏 / 渲染判断用）；CommonSrv.auth.me() 异步拉服务端权威资料（含最新 email / phone / metadata，也可用来校验 token 是否仍有效）。常规业务用 user() 即可。

// 同步读缓存
const u = CommonSrv.user();

// 异步拉服务端权威
const me = await CommonSrv.auth.me();
// { id, email?, phone?, metadata, created_at, ... }

读取当前用户的积分余额与累计获得 / 消费。SDK 已封装：

const { balance, total_earned, total_spent, updated_at } = await CommonSrv.billing.balance();

统一入口：只指定 model_key，通道路由 / 权重 / 降级由服务端调度。按 token / 时长 / 张数自动扣积分。

AI 调用计费优先使用实际通道的用户价格，通道未配置时才使用模型价格兜底；模型价格可以留空。调用前仅按本次可用通道的有效规则估算并预授权，故障切换后按实际通道规则结算。未配置有效价格的通道不参与本次分发；没有可用价格时返回 PRICING_RULE_MISSING。

APIMart Gemini 3.8 Flash 通道通过同步聊天接口调用；对外 model_key 以当前模型目录为准。上游即使返回分块事件，服务端也会合并为一次聊天响应并使用上游最终 token 用量结算。输入、缓存输入和输出按实际 token 分别计费；用户价为 APIMart 对应 USD 成本乘以 1.2，再按当前积分汇率换算。此入口不提供 APIMart 的 Google Web Search 或显式上下文缓存创建能力，不能用本模型的 token 价格估算这两类额外收费。

genllm 与 genlongtext 的 APIMart GPT-6 Astra、Claude Opus 5.5 通道按上游回传的实际 token 用量结算。输入、缓存读取、缓存写入和输出分别计价；Astra 输入超过 272,000 token 时整次调用使用长上下文价格，Claude 缓存写入区分 5 分钟与 1 小时。用户价格为 APIMart 当前配置的渠道 USD 单价乘以 1.2，再按调用时积分汇率换算。APIMart 的聊天响应不返回实际货币费用，因此此处按服务端费率规则计算，不使用“按服务方回传实际费用结算”。发起时缓存是否命中尚不可知，服务端先预授权，完成后依实际用量找平；最终价格以服务端结算记录为准。

按 token 用量计费的视频生成任务，创建时按请求参数匹配价格档位并预授权；实际用量尚未产生时，不会因 token 数为零而拒绝已匹配的档位。任务完成后按服务商回传的实际 token 用量，用提交时选中通道的价格结算并记录价格、用量与成本快照；缺少有效用量或结算失败时保留待核对状态，不会按零 token 完成结算。请求参数没有对应价格档位时返回 PRICING_NO_MATCH。

视频素材可在客户端读取实际上传文件的大小、时长作提前提示；客户端提供的时长不替代服务端校验。 仅配置外部长任务通道且按 token 计费的模型，在任务领取时由 CommonSrv 检查素材， 创建成功不代表素材已通过检查。其他模型保留创建时预检，以满足计费需要。 检查先读取最多 64 KB 文件头，时长不足才读取最多 256 KB 文件尾，不主动下载完整视频； 源站忽略 Range 时会取消继续读取，但已在途数据仍可能产生流量。 文件缺失、无权限、超限或无法确认必需的大小/时长时，任务失败且不调用模型，释放预扣积分； 网络超时、限流与源站 5xx 最多检查 3 次，仍失败则结束任务并释放预扣积分。请通过任务查询获取最终状态。

图片输入同样检查：图生视频首尾帧、参考图片，以及换脸/换人的目标图片。 服务端最多读取 256 KB 文件头，识别 PNG、JPEG、WebP、GIF 的实际格式和尺寸； 不执行完整图片解码或人脸质量识别。无法识别时返回 IMAGE_HEADER_UNVERIFIED，需转换格式后重试。 模型 params 可配置 max_input_image_mb、allowed_input_image_formats、 min_input_image_width、min_input_image_height、max_input_image_width、max_input_image_height；未配置的尺寸与大小限制不额外强加。 检查失败通过错误响应 hint 或任务 error 返回中文原因，领取阶段失败标记在 meta.media_validation。

图片按不同地址去重，未命中校验记录时最多并发检查 8 张。 携带 meta.input_media_ids 的本人受管图片，若已有可信封存内容版本，成功的格式、尺寸和大小记录按内容版本、输入变体和校验器版本复用，不因超过 5 分钟重复读取。 历史未封存资源仍最多复用 5 分钟；纯外链每次提交重新检查，同一次提交内相同完整地址的成功图片校验结果最多复用 5 分钟，避免提交检查与派发检查重复读取。每次仍检查链接有效期、受管资源归属和状态，并应用当前模型限制；变换参数、内容版本变化或缓存失效时补验。资产数量与 HTTP 记录数量分别统计，一条 HTTP 记录不代表新增了一个输入资产。 文件存在性按需核对：页面解析本次资源或生成任务实际使用资源时才检查，不扫描其他用户或未访问的历史资源。404 表示已缺失，403、超时和 5xx 表示暂时无法确认。 默认申请 6 小时下载链接。受管图片在真正派发及队列领取前按模型取图窗口检查；可通过模型 params.input_fetch_window_seconds 指定窗口，否则采用 max_execution_seconds 或通道执行超时，另留默认 10 分钟余量。 图片的实际签名、临时凭据或任务保护期限更短时，以较短者为准；不足时返回 IMAGE_URL_LIFETIME_TOO_SHORT，不会调用上游。视频理解在派发边界重新签名并立即执行真实 Range 探测，不要求视频下载链接覆盖完整生成周期，也不会返回图片专用的有效期错误码。已知过期的纯图片外链仍返回 IMAGE_URL_EXPIRED。 成功预检不保证文件以后不会被存储管理员删除；换链接不能恢复已删除的文件。

时时科技异步视频通道创建任务时，若服务端确认连接尚未建立（DNS 失败或连接超时）， 可使用同一个幂等任务标识最多尝试 3 次； 仍失败时任务以确定失败结束并自动释放全部预扣积分。已建立连接后的读取超时、HTTP 5xx 或其他无法确认上游是否受理的错误不会自动重发，以避免上游重复计费；此类任务保留为结果不确定，等待对账处理。

视频超分

视频生成通道可设置 config.supports_post_upscale，缺省为 true。应用在生成完成后可查询原任务的 GET /ai/jobs/:id；其 job.post_upscale 返回 supported、source_media_asset_id、source_model_key 和组合任务的 pipeline_mode。独立超分应提交原始素材的 media_asset_id、原视频时长 duration（秒）与显式 resolution，每次创建独立任务和计费；原始素材不存在时停止提交。

video-upscale 是独立的视频超分 Model Key，通过异步任务接口调用。腾讯 MPS 提交使用平台生成且持久化的 SessionId；若 ProcessMedia 的响应在返回 TaskId 前中断，任务进入只读对账状态，通过 DescribeTasks 与 DescribeTaskDetail 找回原任务，绝不重新提交付费处理。明确的 CAM 鉴权拒绝会标记为未提交且停止自动重试；对账窗口耗尽后才暂停等待人工核查。 传入 input.video_url，目标分辨率用 resolution 选择 480p、720p、1080p、2k、4k、8k、数字p、source 或 custom。2k/4k 分别表示短边 1440/2160； source 保持源尺寸；custom 使用 width/height 或 target_short_edge/target_long_edge，两组参数互斥。resolution 必须显式传入；自定义尺寸也要传 resolution="custom"。 缺少分辨率会在计价和供应商调用前返回错误。此模型不使用 size 字段。 可选 super_resolution_type = lq | hq（低清噪声/高清素材），未传沿用通道默认； 可选 super_resolution_scale = 2 对应腾讯 Size 字段，不能传入平台未声明的其他倍数。 输出为 MP4 文件；codec 支持 h264/h265/h266/av1/mv-hevc。常规编码显式边长范围为 0 或 128–4096， MV-HEVC 扩展到 7680 且要求多视角源；8k 不代表任意编码都支持，超出对应范围返回 INVALID_INPUT。 默认 H.264、6000kbps、源帧率、AAC 音频；这些默认值可由本次请求覆盖。不包含 AI 插帧或大模型增强。 超分补出的细节不保证与原始场景完全一致。

受理后返回 CommonSrv 任务 ID，按通用任务接口查询状态与结果；腾讯任务结束不代表超分成功， 必须取得成功的转码子任务及输出文件。结果进入通用媒体回存流程，遵循相同的任务完成与回调契约。 模型与通道初始禁用，管理员需配置腾讯凭据、备用腾讯 COS 存储通道、积分价格并完成实测后启用。 腾讯云凭据统一为同一对 SecretId 与 SecretKey，支持通过环境变量引用； 调用方仍使用平台 API Key，公开请求格式和认证方式不变。服务端认证配置缺失或无效时请求会失败， 不会使用已停用的历史认证配置。 SecretId 所属身份需要 MPS 的 ProcessMedia、DescribeTasks、DescribeTaskDetail 和 DescribeMediaMetaData 权限；这与 MPS 读取和写入 COS 所用的 MPS_QcsRole 服务角色是两项独立授权。主账号可在 MPS 控制台概览页执行“COS 授权”， 授权完成后可在访问管理的角色列表核对 MPS_QcsRole。 MPS 通道不重复保存 Bucket、COS 地域或 COS 密钥：运行时优先复用项目当前的腾讯 COS 或 CloudBase 写入通道； CloudBase 会解析为其底层 COS，MPS 直接读取和输出，并将结果登记回同一 CloudBase 环境，不再复制到另一存储桶。 项目使用其他存储时，改用管理员选择的备用腾讯 COS 或 CloudBase 通道。Bucket、地域和凭据均来自该存储通道， MPS 的 API 地域只决定任务提交位置。受管素材若能验证为腾讯 COS 对象，会用原生 COS 输入提交，避免按普通外链取回。 服务端在扣费前通过腾讯 DescribeMediaMetaData 核验尺寸、帧率和时长；无法核验返回 VIDEO_METADATA_UNVERIFIED， 不信任客户端传入的计价维度。参考成本按输出短边、帧率 ≤30/≤60/≤120 和编码计入超分费及普通转码费， 自定义及源尺寸也按实际规格匹配。无价格档位时返回 PRICING_NO_MATCH，不会按1080P或30帧兜底。 上海、广州等中国大陆地域使用同一档内置参考成本；海外地域不会自动套用大陆价。 参考价仅供配置，以账户合同及地域为准；平台积分以管理员配置价格为准，源视频时长用于提交计价。

const { job_id } = await CommonSrv.ai.submit("video-upscale", {
  video_url: "https://example.com/source.mp4", duration: 5, resolution: "4k",
  super_resolution_type: "lq", codec: "h265", fps: 60, video_bitrate: 12000
});
const result = await CommonSrv.ai.wait(job_id);

视频超分增强

video-upscale-enhance 是独立的视频超分增强 Model Key，与普通超分分别选用、分别配置价格。 输入同样使用 video_url 和上述可配置尺寸、编码及音频参数， 可选 operation = "enhance" 及 strength：weak、normal、strong，默认采用通道的enhance_strength（未设置时为 normal）；无效强度返回 INVALID_INPUT。 腾讯通道仅开启 Diffusion 大模型增强，不同时开启普通超分、降噪或插帧。 输出尺寸、音频、任务查询和回存规则与视频超分相同。增强模型不接受 super_resolution_type/scale， 普通超分不接受 strength，避免普通超分与大模型增强被静默混用。增强可能改变人脸、文字或纹理细节，先用短样片对比效果。 此模型与通道初始禁用，需独立配置价格并实测后启用。

const { job_id } = await CommonSrv.ai.submit("video-upscale-enhance", {
  video_url: "https://example.com/source.mp4", duration: 5,
  resolution: "1080p", strength: "normal"
});
const result = await CommonSrv.ai.wait(job_id);

视频生成 2.5 超分 / 超分增强（透明组合）

video-2.5-cf 对应用表现为一个视频模型。应用提交提示词、参考图、时长、比例和最终resolution；平台内部先生成视频，再执行超分，最终只返回超分后的视频。 参考图既可放在 OpenAI 兼容的 content 多模态数组中，也可使用first_frame、last_frame 或 reference_images；这些字段会原样进入第一步 Seedance 2.5 生成，不会交给超分步骤。 需要腾讯 DiffusionEnhance 大模型增强时，改用独立的 video-2.5-cf-enhance； 它的公开输入、分辨率选择、任务状态和结果结构与 video-2.5-cf 相同，内部第二步固定选择video-upscale-enhance，不会与普通超分静默互换。resolution 是必填计费参数；应用应从模型目录的 params.resolutions 读取管理员开放的选项， 不要在客户端写死分辨率列表。缺少或不在开放范围内时，任务在预授权和调用供应商前报错。

用户价格按本次分辨率实际命中的生成步骤价格与超分步骤价格相加，再乘组合售价倍率，只预授权和结算一次。 因此同一时长下 720p、1080p、2k、4k 可以显示不同总价；应用不会看到两笔独立订单。

const model = (await CommonSrv.ai.models()).items
  .find((item) => item.model_key === "video-2.5-cf");
const supported = model?.params?.resolutions ?? [];

const { job_id } = await CommonSrv.ai.submit("video-2.5-cf", {
  prompt: "电影感海边日落，人物向镜头走来，无字幕",
  content: [{ type: "image_url", image_url: { url: referenceImageUrl }, role: "first_frame" }],
  duration: 5,
  ratio: "16:9",
  resolution: supported.includes("2k") ? "2k" : "1080p"
});
const result = await CommonSrv.ai.wait(job_id);

const enhancedModel = (await CommonSrv.ai.models()).items
  .find((item) => item.model_key === "video-2.5-cf-enhance");

const { job_id } = await CommonSrv.ai.submit("video-2.5-cf-enhance", {
  prompt: "电影感人像近景，保留自然皮肤纹理，无字幕",
  duration: 5,
  ratio: "16:9",
  resolution: enhancedModel?.params?.resolutions?.includes("2k") ? "2k" : "1080p"
});
const result = await CommonSrv.ai.wait(job_id);

列出启用模型

视频任务受理后会尝试唤醒已授权的维护 Worker。时时科技创建响应丢失时， 服务端使用生成前持久化的 client_task_id，只读查找最多 500 条平台原任务； 找到同模型的唯一匹配后继续查询原任务，不重发生成。未找到、匹配不明确或查找失败时仍转人工核查。 平台明确拒绝创建（例如模型维护）不会进入此恢复流程。

时时科技视频任务查询的 HTTP 错误、响应读取失败或无效响应不会被当作生成失败； 已取得供应商任务 ID 的任务保留原 ID，由任务维护机制退避重试查询，连续失败达到上限后暂停待审核。 创建响应丢失且未取得供应商任务 ID 时，需先核对并找回原任务，查询重试不会重新提交生成请求。

图像和视频模型的 params.resolutions 来自已启用模型通道的分辨率能力并集； 视频模型的 params.duration_min / params.duration_max 同样从已启用通道聚合。 这些能力在通道配置中维护；按分辨率分档计价时，保存会校验能力列表与价格档位一致。 分档价格必须明确匹配所有计价维度，未匹配返回 HTTP 400、PRICING_NO_MATCH， 在积分预授权和上游生成前拒绝请求，不套用兜底或最后一档价格；明确统一按张或按次收费仍可使用统一价格。 应用每次打开模型设置需重新读取目录，展示本地选项缺少或多出的分辨率以及时长范围差异，修正后才保存启用配置。 组合模型在目录中返回 model_kind="pipeline" 以及管理员配置的 input_schema、output_schema；应用仍只提交一个 model_key 和一份 input，不需要知道内部使用了哪些生成、超分、转码或其他步骤。管理员调整流程并保存后，目录文档随该模型协议一起更新；内部固定参数不会出现在公开文档中。 组合步骤返回已存储的产物时，平台完成资产登记后重新核对资源状态，再提供读取地址；资源仍在处理时保持等待，资源缺失、失败或已删除时不返回读取地址。已保存的原对象与登记回执会保留，读取地址生成失败后的存储恢复复用原结果，不需要重新上传或生成。步骤结果尚未完成存储收尾时，不代表整个组合任务已完成交付。 组合任务按各步骤当次匹配价格求和，再乘组合售价倍率并统一向上取整，只预授权和结算一次。平台在父任务内保存每一步的输入、结果、供应商任务号与计费判断：前一步成功而后一步失败时会保留前一步结果，只推进失败步骤。只有连接前失败、明确拒绝或限流等可证明供应商未受理的错误才有限次自动重试；提交结果不确定、供应商任务已创建或自动重试用尽时会暂停并等待管理员核查，不会因查询、恢复或刷新再次扣用户积分。管理员创建步骤重试时按原任务账务事实自动确定承担方：原任务已经产生用户扣款时由平台承担；尚未扣费时只按该步骤冻结的价格预授权，供应商受理后结算，明确未提交时释放。 步骤之间需要移动图片、视频或音频时，平台先通过持久化文件转存任务保存中间产物，再开始下一付费步骤；浏览器可用时优先协助传输，页面关闭或不支持跨域时由 Worker 接管。转存完成会立即唤醒父任务。组合通道明确设置中间文件过期小时数后，仅非最终步骤新生成的资源进入平台临时对象目录；未配置的新任务按普通用户资源保存并占用用户空间。组合任务全部完成后仍立即删除配置为临时的中间资源，对象存储生命周期为删除失败的兜底。转存期间父任务继续保持处理中，应用不需要读取内部文件任务，也不需要重新提交组合模型。 公开任务查询只读持久快照，不查询供应商、不续执行租约。供应商查询由统一协调器的到期推进和 Worker 完成，均受数据库维护租约与 next_poll_at 约束。响应 retry_after_ms 与 Retry-After 提供观察建议；手动刷新不会提前执行供应商重试。任务日志按持久 task_id 区分，trace_id 只关联一次请求；合并请求的摘要与其中每个任务的执行日志分别记录，不能用共同 trace_id 推断任务归属。

const { items } = await CommonSrv.ai.models();
const { items: videoModels } = await CommonSrv.ai.models(CommonSrv.ai.CATEGORIES.VIDEO);
// items[i]: { model_key, display_name, category, async, params, test_fixture }
//   - category: "llm" | "image" | "video" | "tts" | "stt"
//               推荐用常量：CommonSrv.ai.CATEGORIES.LLM / .IMAGE / .VIDEO / .TTS / .STT
//   - async  : true  → 必须走 CommonSrv.ai.submit + .wait
//              false → 走 CommonSrv.ai(...) 同步调用
//
// 分流规则（服务端强制，靠 async 字段判断即可，别自己猜）：
//   if (m.async) { await CommonSrv.ai.submit(m.model_key, input); ... }
//   else         { await CommonSrv.ai(m.model_key, input); }

同步（LLM · 直接返回结果）

const reply = await CommonSrv.ai("google/gemini-2.5-flash", {
  messages: [{ role: "user", content: "hi" }],
  // params: { max_tokens: 2000, thinking: { type: "disabled" } },
}, {
  meta: { feature: "文本推理" },
  ref: { type: "your_app", id: "chat-1234" },
});
// reply: { ok, text, usage: { input_tokens, output_tokens }, credits_consumed, balance_after }

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

SDK 按响应 retry_after_ms 观察当前阶段（缺少建议时默认 30 秒，网络故障指数退避上限 300 秒，429/408 可重试且有效 Retry-After 可延长等待，其他 4xx 直接返回；signal 取消立即中止等待，默认 10 分钟等待期限覆盖卡住的网络请求），也可传 callbackUrl 让服务端在终态时主动推送——不要自建 setInterval。

// 1) 提交任务
const { job_id } = await CommonSrv.ai.submit("kling-v2", {
  prompt: "a running cat", duration: 5,
}, {
  meta: { feature: "视频生成" },
  // callbackUrl: "https://your-app.com/hooks/commonsrv-ai",
});

// 2) 等待完成
const done = await CommonSrv.ai.wait(job_id, {
  onProgress: (job) => console.log(job.status, job.progress),
  // timeoutMs: 30 * 60 * 1000,   // 长任务可放宽到 30 分钟 ~ 24 小时
});
if (done.status === "succeeded") {
  // done.output 已对齐 OpenAI 协议（按 category 不同）：
  //   LLM   → { id, object:"chat.completion", choices:[{ message:{ role, content } }], usage }
  //   Image → { created, data:[{ b64_json?, url?, width?, height? }] }
  //   Video → { id, object:"video", status, data:[{ url?, duration_sec? }] }
  //   TTS   → { data:[{ b64?, hex?, format, duration_sec? }] }
  //   STT   → { text, ... }
  // done.credits_consumed
}

// 3) 一次查状态（不轮询）
// const job = await CommonSrv.ai.get(job_id);

REST / OpenAI 兼容接入（无 SDK 运行时）

REST 基址为 https://<your-commonsrv-host>/api/public/v1。Bearer token 由业务登录流程获得； 服务端项目调用使用项目 API Key。同步 LLM 使用 /ai/invoke 或/chat/completions，异步 LLM、图像、视频与语音使用 /ai/jobs并查询 /ai/jobs/:id。不要自己实现 refresh token 轮换。

# 同步 LLM（统一 CommonSrv 协议）
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":"deepseek-v4-pro",
    "messages":[{"role":"user","content":"请返回 JSON"}],
    "params":{"max_tokens":2048,"thinking":{"type":"disabled"},"response_format":{"type":"json_object"}}
  }'

# OpenAI 兼容入口（非流式）
curl -X POST https://<your-commonsrv-host>/api/public/v1/chat/completions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"你好"}],"stream":false}'

# 异步任务：LLM 参数放在 input 顶层；input.params 仅作旧调用兼容
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":"写一篇深度分析"}],"max_tokens":8000,"thinking":{"type":"enabled"},"reasoning_effort":"high"}
  }'

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

以上是完成 AI 接入的核心流程；需要逐字段请求/响应定义时，从统一入口进入 REST / OpenAI 兼容专题文档。

视频理解模型通过异步任务接收 input.messages，用户消息的content 数组包含 {type:"video_url",video_url:{url:"https://..."}}。 腾讯 TokenHub 的混元视频通道使用该协议，视频地址须可由上游访问，单个文件上限为 100 MB； 该模型的输出上限为 8192 tokens。模型是否可用取决于管理员完成通道密钥与计费配置。

longvideoparse 下的腾讯 MPS 多模态理解通道也使用上述异步任务入口和统一输入输出： 输入一个 video_url 与文本解析指令，成功时返回兼容 Chat Completion 的文本内容。 通道将请求提交为ProcessMedia 的 AiAnalysisTask（Definition 33），随后通过DescribeTaskDetail 查询结果；使用腾讯云 SecretId/SecretKey 与项目关联的 COS 存储通道。 该通道须由服务端验证视频时长后才可参与路由；供应商成本按视觉理解每分钟 1.5 元折算为每秒 0.025 元， 用户价格按当前渠道加成及积分汇率计算。使用前须配置 MPS 服务权限。

一次性工具型调用。按每次 / 每千字符 / 按上游实际用量计费，上游返回资产原样透传。 与功能四的区别：模型按 token / 时长走通用入口；接口是一次性工具，每个 key 参数不同，按 request_schema 动态发现。

动态发现（免鉴权）

const { items } = await CommonSrv.endpoints.list();
// items[i]: { key, display_name, category, async, request_schema }
//   - async=true 表示该 endpoint 内部走异步 job，call() 会自动等待终态返回。
//   - request_schema: 每个 endpoint 入参不同，按此 schema 传参 / 渲染表单。

统一调用

const r = await CommonSrv.endpoints.call(
  "<endpoint_key>",
  { /* 每个 key 的入参，见 request_schema 或下方示例 */ },
  { meta: { feature: "..." }, ref: { type: "your_app", id: "..." } }
);
// r: { ok, output, credits_charged, balance }

当前启用的 endpoints

以下清单以 CommonSrv.endpoints.list() 返回为准；新增 / 停用会实时反映，业务端无需改代码。

1) minimax-voice-design — 音色设计（语音）

MiniMax voice_design 音色克隆，返回 voice_id、私有媒体资产 ID 与短期试听地址。 CommonSrv 会将上游试听音频持久化到统一媒体存储；不会把原始音频 body 透传给客户端。 项目未开启媒体灰度或服务端存储配置不完整时，会在调用上游前返回ENDPOINT_MEDIA_STORAGE_UNAVAILABLE，不会产生该次上游调用费用。 其中 preview_text 为必填（上游用它合成试听音频）， 本接口即按 preview_text 的字符数计费（中日韩字符按 2 计）。

const r = await CommonSrv.endpoints.call("minimax-voice-design", {
  prompt: "温柔女声，30 岁左右",
  gender: "female",
  age: "young",
  preview_text: "你好，这是一段试听文本。",   // 必填，计费依据
}, { meta: { feature: "音色克隆" } });
// r.output: { voice_id, media_asset_id, url, expires_at, trace_id, ... }
// url 是私有短期读取地址；业务表应保存 media_asset_id，不保存 url。

2) douyindl — 抖音解析（工具）

通过短链或 web 地址拿到抖音视频的无水印直链、封面、标题等。

const r = await CommonSrv.endpoints.call("douyindl", {
  url: "https://v.douyin.com/xxxxxxx/",
}, { meta: { feature: "抖音解析" } });
// r.output: 上游 body 原样透传（含 data / aweme_details 等抖音字段）

3) apify-run-actor — Apify Actor 抓取（工具）

通过 Apify Actor 抓任意站点。按 Apify run.usageTotalUsd 实际消耗换算积分。

const r = await CommonSrv.endpoints.call("apify-run-actor", {
  actor_id: "apify/web-scraper",
  run_input: { startUrls: [{ url: "https://example.com" }] /* 每个 Actor 不同 */ },
  // memory_mb: 2048, build: "latest",
  // fetch_items: true, item_limit: 1000, timeout_secs: 300,
}, { meta: { feature: "数据抓取" } });
// r.output: { items, run_id, dataset_id, usage_usd, ... }  // 上游 run 结构原样

4) brightdata — Bright Data（工具）

专门用于抓取 TikTok Shop 数据；入参按启用通道的 request_schema 提供。

const r = await CommonSrv.endpoints.call("brightdata", {
  /* 入参以 endpoints.list() 返回的 request_schema 为准 */
}, { meta: { feature: "TikTok Shop 抓取" } });

5) send-sms — 发送短信（工具）

统一短信发送入口。默认走「验证码 + 有效期分钟」两参模板（模板变量顺序固定为 {1}=验证码, {2}=有效分钟）； 管理员在「接口管理 · send-sms」挂通道（腾讯云 / 阿里云 / 未来海外通道）并填 sign_name / template_id。output 已归一化契约，切换通道调用方零改动。

const r = await CommonSrv.endpoints.call("send-sms", {
  phone: "+8613800138000",       // 或 phones: [...] 批量（<= 200）
  code: "123456",                 // 验证码
  expires_in_minutes: 5,          // 有效期分钟（1–60，默认 5）
}, { meta: { feature: "发送短信" } });
// r.output（跨通道稳定契约）：
// {
//   request_id,                  // 上游请求 ID
//   phone_count,                 // 本次调用手机号数（计费快照用）
//   accepted_count, failed_count,
//   per_phone: [{
//     phone,                     // E.164
//     status: "accepted" | "failed",
//     code,                      // 成功统一 "OK"，失败为上游码
//     message,
//     provider_message_id?,      // 腾讯 SerialNo / 阿里子 BizId 等
//     fee?, country_code?,
//   }],
//   raw,                         // 上游原始响应（仅排障用，不算契约）
// }

6) storage-sign — 对象存储直传（OSS / TOS / COS 可配置）

原始 object_key 写入接口已停止开放。上传统一使用后文 uploadManaged，读取和清理统一使用资源 ID。

const asset = await CommonSrv.storage.uploadManaged(file, {kind: "video"});
// 保存 asset.id 到业务记录；关联通过 references/upsert 同步。
// 签名过期后按资源 ID 重新读取；删除先预览，确认后执行。

浏览器直传等无法由 CommonSrv 直接观测的失败，可由已认证应用通过POST /api/public/v1/client-events 上报诊断事件。仅允许阶段、错误和关联 ID 等结构化元数据，禁止上传文件内容、凭据或渠道配置。

加一个入口执行 CommonSrv.invite.open() 即可打开集成邀请界面。

document.querySelector("#menu-invite").onclick = () => CommonSrv.invite.open();

// 可选：CommonSrv.invite.open({ mode: "iframe", container: el });
// 可选：CommonSrv.invite.open({ mode: "redirect" });

配置了临时／长期双空间的项目无需旧超额清理协议：临时文件到各自保存日期后、长期文件到付费截止日加宽限天数后，由维护任务自动进入物理清理流程，不依赖用户登录。其他尚未启用双空间的项目仍沿用原有超额通知与业务清理协议。

配置双空间的项目为每人提供免费临时空间，并可单独用积分购买长期空间。订阅套餐只发积分，不提供空间容量。两种空间分别计量，文件不会自动转移；用户选择新资源的默认目标并保存偏好，新上传在创建资源时冻结目标，异步生成在受理任务时冻结目标。业务页面可用 CommonSrv.billing.open({ tab: "storage" }) 直接打开长期空间购买页。

配置双空间的项目调用 GET /api/public/v1/storage?view=space-usage；返回 temporary_quota_bytes、temporary_used_bytes、long_term_capacity_bytes、long_term_used_bytes，以及各自预占、剩余和选中目标、长期付费截止日期及保留截止日期。还返回图片／视频默认保存天数、长期到期保留天数、购买容量的最小值／步长／默认值／快捷列表／最大值，均来自项目配置。容量单位为字节，1 GB = 1024³ 字节。?view=usage 为其他项目的原有汇总接口。

图片／视频／音频任务在服务端原子预占容量，空间不足返回 409 STORAGE_QUOTA_EXCEEDED，不启动付费模型。异步受理后的拒绝任务在 GET /ai/jobs/:id 的 job.storage_requirement 和任务快照的 error_details 提供拒绝当时的 storage_space、required_bytes、available_bytes、shortfall_bytes；同步拒绝的 409 响应也带 storage_requirement。这些字段均为字节，客户端应显示需要、可用与差额，不应把当前空间页面读数当作当时快照。配置双空间的项目从「存储空间配置」读取视频每秒、图片每张的预留 MiB（1 MiB = 1048576 字节）：当前初始值分别为 1 MiB/秒和 5 MiB/张，视频时长向上取整；请求未提供 seconds/duration、模型也无时长默认值时，按项目「存储空间配置」中的未知时长估算秒数（初始 60 秒）预留，不要求用户补填。明确传入非正数或非数字时返回 STORAGE_VIDEO_DURATION_INVALID。图片缺省一张，张数无效返回 STORAGE_IMAGE_COUNT_INVALID。模型 params.storage_output_budget_bytes 的显式预算仍优先；非双空间项目沿用视频 512 MiB、其他媒体 64 MiB。已接受任务实际结果超预算仍保存，随后限制新增。未知任务不因超时释放预占。

异步生成请求可选传 storage_space（temporary／long_term）及仅供临时空间使用的 storage_retention_days（正整数，不得超过项目配置上限）。省略目标时读取用户已保存的选择，首次为临时空间。受理时冻结目标和保存天数，并只在此时检查相应空间是否可用。长期空间过期返回 409 STORAGE_LONG_TERM_EXPIRED，需提示用户明确切换到临时空间；临时空间不足返回 409 STORAGE_QUOTA_EXCEEDED。已受理结果仍保存到原目标，即使完成时已超额或到期。

临时空间默认容量初始配置为 2 GB，图片默认保存 30 天、视频默认 7 天，业务最多指定 30 天；项目管理员可修改这些值，修改保存天数只影响新文件。长期空间初始价格配置为每 GB 每自然月 200 积分、到期宽限 30 天；购买容量初始最少 5 GB、步长 5 GB、默认 10 GB，快捷 50／100／1000 GB，均可在项目配置中修改。购买页只展示长期空间。先调用 ?view=credit-quote&action=buy|expand|renew&target_gb=整数 展示积分，再 POST /storage 提交 credit_purchase（含原报价 expected 和稳定 idempotency_key）。POST /storage 的 selected_space 保存用户新资源的默认空间，适用于新上传素材和省略 storage_space 的异步生成请求；异步生成请求显式传 storage_space 时以本次请求为准。普通上传创建资源时按当前默认空间检查容量和权益，成功创建后冻结目标；已受理的生成结果沿用任务受理时冻结的目标。auto_renew.enabled 保存自动续费。所有显示期限为项目日历时区的日期，到该日 23:59:59 结束；清理从次日开始。

普通上传在创建意图时若长期空间已到期返回 409 STORAGE_LONG_TERM_EXPIRED，若所选空间不足返回 409 STORAGE_QUOTA_EXCEEDED。用户可见的“免费临时空间”有自身容量与保存期限。平台内部使用的 temporary/<小时数>hour-cleanup/ 对象目录独立于用户空间，不允许将正式用户素材上传到该目录；应用始终保存并传递资源 ID。

资源状态为 pending、ready、failed、deleting、deleted。GET /storage 可按 state、after、limit 查询。CommonSrv.storage.open() 提供通用容量与关系页面；应用的主整理入口应按作品和版本实现。CommonSrv.assets.changeMany(items) 仅支持 organize 元数据修改；save、trash、restore 和 saveMany 已退役。

永久删除先 POST /storage 传 deletion={action:"preview",asset_ids:[UUID]}，返回不可扩大的计划、版本快照、阻止原因和 estimated_released_bytes；确认传 deletion={action:"confirm",plan_id:UUID}。确认幂等，返回每项 accepted／skipped 与 released_bytes。新增引用、活跃任务、未知关系和版本变化均会阻止执行。逻辑容量释放不代表对象存储已完成物理回收；没有撤销和回收站。

配置双空间的项目不再提供现金购买存储订单；使用积分购买长期空间。新购、扩容和续费都通过 /storage 的积分报价与确认接口，积分不足不透支。尚未配置双空间的其他项目保留原有 storage_service 接口。

双空间项目没有容量缩减时按作品挑选超额文件的流程。长期空间到期后停止新的长期生成；文件保留到配置的统一宽限截止日。宽限期内续费可继续保留原文件；过期后自动清理。临时文件按各自固定日期清理。运行中任务及未确认的资源关系仍受现有安全锁保护，保护解除后维护任务继续清理。

读取意图与实际读取分开记录。签发地址不能作为下载证明；HEAD／Range 可用性探测不计为用户访问。访问覆盖未知时不得推断为冷数据。本期不启用自动冷存储转换。

浏览器 SDK 3.17 的 CommonSrv.storage.uploadManaged(file, options) 统一处理上传。options 支持 sourceRef、visibility、idempotencyKey、waitMs（0–180000）、signal、onPrepared、onProgress。成功返回 id、status、url、url_expires_at，不返回存储位置或凭据。status=processing 时额外返回 completion_file_id，仅用于恢复确认：保留 id 并调用 completeManagedUpload(id, completion_file_id)，不要重传。请求失败时错误对象可带 assetId／completionFileId。SDK 不因网络错误自动删除资源。

客服工单截图可在上传意图中指定 purpose: "support-feedback"；仅接受图片，单张最多 10 MiB，供同一用户的客服工单引用，720 小时后由平台清理，不计入用户素材空间。普通素材不要设置该用途。组合任务的中间文件期限由平台组合通道配置，公开上传接口不接受业务自行指定临时对象路径或过期小时数。

统一上传会自动为本次操作发送 X-Upload-Trace-Id（UUID），创建、凭证、分片和完成确认共用链路；并发文件分别分组，失败对象带 traceId 便于定位。此标识只用于日志，不作为授权凭据。完成确认返回 HTTP 200 不代表资源已就绪，仍须检查 status。日志详情与复制只包含选中的单条记录。

SDK 3.17.2 自动向 client-events 上报浏览器传输成功或失败，标记“客户端上报”并使用同一 correlation_id。仅含资源 ID、文件大小、耗时与结果，不含上传凭据、路径或文件内容。上报失败不会改变上传结果。完成确认日志根据 asset.status 区分处理中、已就绪、失败，HTTP 状态码仍按原响应显示。

所有 storage-sign 通道的传输差异由 SDK 内部处理，包括 CloudBase；应用无需安装存储厂商 SDK，也无需提供 cloudbaseUpload。新素材上传统一为服务端签名 PUT，浏览器无需加载 CloudBase 组件或登录 CloudBase；旧 cloudbaseUpload 仅作过渡兼容。分步 REST 接入的 env_id、ticket、object_key 属于直传协议参数，不应保存到业务字段；ticket 和签名在日志写入、展示与复制时脱敏。原始 storage.upload 不再作为公开写入入口，不能将 object_key 当成资源 ID。

统一资源上传使用 intents → upload-ticket → 直传 → complete。新签发 upload-ticket 的 upload.transport 统一为 put，使用 method=PUT、url、headers 原样直传，确认时 file_id 传 completion_file_id；旧 PUT 响应缺少此字段时可使用 object_key。旧 cloudbase 响应（省略 transport 也按 CloudBase）由 SDK 兼容，使用 env_id／ticket。file_id 是历史字段名，客户端不得自行拼接。两条路径都返回同一资源 ID，并核验大小、文件签名和封存状态；当前统一直传上限 512 MB，原有大文件分片接口仍保留，尚不能当作受管资源上传替代。存储商由服务端选择，业务只持有资源 ID，不接触密钥。

同一上传 idempotency_key 只能重试相同的类型、大小、业务来源和可见性，冲突返回 409 MEDIA_IDEMPOTENCY_CONFLICT。明确指定的上传通道禁用、重复或不可用时返回 503 MEDIA_UPLOAD_BACKEND_UNAVAILABLE，不自动换存储商。取消先锁定待上传记录再删除对象，已完成或被取消锁定的上传不能再次确认（409 MEDIA_UPLOAD_NOT_PENDING）；删除失败保留容量预占和原对象位置，可重试原 abort。确认请求超时应重试原 complete，不要因响应丢失主动删除文件。

GET /api/public/v1/storage?view=thumbnails&ids=UUID,UUID 使用用户 Bearer 身份，最多 100 个资源 ID，返回 thumbnails（id、url、expires_at）；未就绪／已删除／无权访问时 url 为 null，不返回原文件作为替代。小图与原件共享归属检查，签名最长 300 秒。文件保留期限与访问凭证有效期相互独立。COS／OSS／TOS 的受管读取支持不足 60 秒的短有效期，不向上放大。

封存对象使用服务端专属 sealed-assets 命名空间。公开 storage-sign 接口不能直接读写／删除该命名空间，返回 STORAGE_RESOURCE_ID_REQUIRED；必须使用资源 ID 接口进行归属检查。封存、缩略图处理和永久保留策略核验分别记录，复制成功不代表已经通过永久保留核验。

资源就绪后自动保存。双空间项目的临时资源使用受理时确定的保存天数计算截止日期；长期资源使用账户统一的付费日期与宽限天数。

双空间项目的临时资源有固定保存截止日期；不要把读取签名的 expires_at 当成文件清理日期。

CommonSrv 统一支持已配置的 CloudBase、腾讯 COS、火山 TOS、阿里云 OSS。业务端不用选择厂商或处理桶路径。CloudBase 换链按环境分组、每批最多 50 个；原生返回时长不足时，仅对 SDK 确认的真实 COS 对象尝试重签并验证读取权限，验证失败保留原短链并阻止超出期限的生成；COS/TOS/OSS 在服务端本地签名。它们都不提供一次请求返回任意 100 张图片内容尺寸的通用接口，缺少内容证据时仍需有界并发读取。其他对象存储尚需独立适配，不能仅因兼容 S3 就视为已经接入。

整批生成先调用 CommonSrv.storage.beginBatch(key, assetIds, jobKeys)，对应 POST /storage 请求 batch 对象包含 operation=begin、key（最多 200 字符）、asset_ids（最多 2000 个 UUID）、job_keys（1–1000 个、每项最多 200 字符）。响应 batch 包含 id、state、dispatch_closed、protected_until、automatic_until。相同 key 必须保持相同输入清单和任务键。使用 CommonSrv.storage.resolveManaged(ids, {batchId}) 获取资源，SDK 自动按 100 个分块；提交 /ai/jobs 时传 meta.input_batch_id、meta.input_media_ids，idempotency_key 必须来自 jobKeys。浏览器 SDK 和 SDK Core 的 ai.submit 第三个参数可传 idempotencyKey、mediaIds、batchId。

全部子任务已登记后调用 CommonSrv.storage.closeBatch(batchId)，即 POST /storage 的 batch={operation:"close",batch_id}。关闭阻止迟到的新派发，已登记任务继续使用自己的保护；网络结果不确定时先查询原任务，不能另起付费任务。普通单次 /ai/jobs 带受管输入时服务端自动登记单任务批次。批次默认滚动保护 6 小时、剩余不足 1 小时续租、自动上限 24 小时；超限停止新增派发并核对未完成任务，未知状态继续阻止物理清理。批次保护阻止删除在用资源；资源读取不因账户满额而停止。

资源存在性不运行全库定期扫描，也不接收云存储对象事件。POST /media/assets/resolve 只核对本次页面实际请求的 1–100 个资源；生成任务派发只核对本次任务实际引用的资源。未访问的历史资源不会产生存储请求。404 记录为缺失；403 或网络异常记录为暂时无法确认，不误判删除。

存储策略管理页可调整签名目标、并发、取图余量和保护/巡检时间，修改带版本冲突检查及审计。资源页显示实际占用批次和文件可用性。STORAGE_FILE_MISSING 表示文件缺失；STORAGE_CONTENT_VERSION_CHANGED 表示内容或封存条件变化；STORAGE_FILE_UNVERIFIED 表示暂时不能确认可读；STORAGE_BATCH_REVIEW_REQUIRED 表示需要核对长时间未结束的任务。批量解析、缓存命中和运行保护均按应用及用户隔离。

上传与模型生成统一由服务端 resolveStorageBackend 选择目的地。唯一依据是 CommonSrv 后台项目「存储管理」明确选择的写入通道；每个项目必须选择，不提供系统默认或继承。「接口管理 → storage-sign」只管理通道连接和凭据，CloudBase 也登记为该服务的存储通道。环境变量只提供凭据，不参与目的地判断；通道优先级、权重、旧 allowlist 均不能覆盖后台选择。未选择返回 STORAGE_CHANNEL_NOT_SELECTED，通道停用或停止写入返回 MEDIA_UPLOAD_BACKEND_UNAVAILABLE；不会自动换到其他通道。历史资源和进行中的上传始终按各自记录的位置读取、重签、恢复和删除，不随项目选择改变。原对象核验使用源文件元数据；CloudBase 使用 COS GET Range 0–0 的总长度，其他存储使用 HEAD，不使用展示图的下载大小。

模型通道后台的 Mock 图片／视频／音频上传使用后台登录所属的平台项目 OpenTiger（__platform__）的写入通道，请在「项目管理 → OpenTiger → 存储管理」选择并保存；Mock 用户白名单不决定上传目的地。平台项目的既有 ID 00000000-0000-0000-0000-000000000001 可用于项目配置、存储管理与存储 Hook 的 project_id；权限和 Hook 项目授权仍需单独满足。配置只保存可跨环境解析的存储引用，实际模拟结果与管理页预览会按当前环境重新签发短期读取地址。本地 Mock 开关属于环境运行状态，发布配置同步不会覆盖 Production 的开关；Production 配置检查会拒绝 localhost、127.0.0.1 与 ::1 的历史 Mock 媒体 URL。

购买目录 plans 返回会员权益档位及 offers[] 报价；双空间项目的档位只含积分，storage_quota_bytes 为 0。每个报价包含 id、currency、mode、price_cents、enabled，连续订阅另含 first_price_cents；套餐购买仍通过 /orders 或 /subscriptions。

连续订阅可 GET /api/public/v1/subscriptions 查询签约状态，DELETE 关闭自动续费。套餐订阅与长期空间积分续费是两套独立日期；套餐只发积分，不延长存储。

双空间项目的长期空间采用项目后台配置的积分单价，首次购买选择目标容量，扩容选择本次增加的 GB（接口仍提交扩容后的目标总 GB）；按自然月购买，扩容只补当期剩余自然日差额。手动购买、手动续费与定时自动续费的积分流水分别标明来源；公开购买接口的 idempotency_key 不可使用保留的 auto: 前缀。自动续费于当前有效期截止日尝试按届时单价扣除下一期整月积分；积分不足时不扣款、关闭自动续费，并在积分明细留下 0 积分的失败记录。买入或自动续费成功后统一延长账户日期，不逐文件更新。

多币种报价分别配置，订单使用所选报价的币种。真实微信 Native 下单目前只支持 CNY；非 CNY 报价不能通过该渠道购买，接口返回 PAYMENT_CURRENCY_UNSUPPORTED。项目 Mock 渠道可测试其他币种报价；实际多币种收款需接入支持对应币种的支付提供方。

双空间项目的 GET /api/public/v1/plans 中 storage_quota_bytes 为 0；订阅权益只有积分。免费临时空间与长期空间容量从 GET /api/public/v1/storage?view=space-usage 获取。

双空间项目在后台「存储空间配置」修改免费容量、生成视频每秒和图片每张的预留 MiB、未知视频时长的估算秒数（初始 60 秒）、默认及最长保存天数、长期宽限天数、积分单价、最大购买 GB 和日历时区；输入先进入草稿，统一点击顶部“保存修改”才生效。

下载签名采用分层策略：生成输入及受管资源解析使用项目「生成资源 · 校验与有效期」配置；生成输入申请时长为 max(项目下载申请时长, 取图窗口 + 项目取图余量)，取图窗口未设置时使用模型最大执行时长或通道执行超时。普通输出展示、mock 预览和元数据核验沿用 storage-sign 通道的读取默认值。实际链接有效期还受通道最大有效期、临时凭据和文件保留期限限制，以返回的 expires_at 为准；不足生成取图窗口时拒绝派发。本页参数不控制上传票据有效期。CloudBase 读取使用底层 COS 签名链接，元数据核验采用 GET Range 单字节请求；失败不回退原生短链接。配置修改只影响后续申请，缓存中仍满足所需时长的链接可以复用，已签发链接不会因此续期。项目配置版本 0 表示使用系统默认值；保存不覆盖已建立批次的策略快照。资源存在性按请求核验；旧版全库扫描及其状态表已退役，配置页不再查询或展示旧扫描完成记录，设置核对间隔不会启用周期扫描。

图片通道配置的 upstream_timeout_ms 按已保存的正整数毫秒值生效，不再被内部 120 秒下限覆盖；缺失时沿用原默认 180 秒，非法值返回 CHANNEL_MISCONFIGURED。

上传票据与下载链接分开管理：COS／OSS／TOS 上传使用通道 default_upload_ttl，不再固定覆盖为 600 秒。CloudBase 上传期限从供应商签名解析，不假定为 120 秒或 900 秒；无法解析返回 CLOUDBASE_STORAGE_UPLOAD_EXPIRY_UNKNOWN，已过期返回 CLOUDBASE_STORAGE_UPLOAD_EXPIRED。文件传输 claim 的 destination.expires_at 是签名截止时间，浏览器和 Worker 将单次上传超时限制为 min(配置的 I/O 超时, 票据剩余时间)，剩余时间小于或等于 0 时停止该次上传，沿用原有放弃／重试流程，不重新生成结果或重复扣费。浏览器上传失败日志可带 provider_error_code，HTTP 400 本身不代表票据过期；不记录原始响应正文或签名。

公开 raw-key storage-sign 请求统一返回 STORAGE_RESOURCE_ID_REQUIRED。所有厂商均使用统一资源 ID 接口，访问始终按资源记录的位置进行。

CommonSrv.storage.open() 打开创作空间页。双空间项目使用 ?view=space-usage 和 POST selected_space；其他项目的 storage.getUsage() 仍使用原汇总接口。assets.previewDelete(ids) 与 assets.confirmDelete(planId) 用于用户主动永久删除。

GET /api/public/v1/storage 仅返回当前应用内本人的文件，资源记录包含 storage_space 和临时空间的 retention_deadline；支持 state、after、limit、kind、min_bytes、category 查询。双空间使用 ?view=space-usage，其他项目仍可使用 ?view=usage。

POST /api/public/v1/storage 的 items 只支持 organize：含 id、version、action 和可选 title、category、starred，最多 100 项，逐项返回 ok／error。收藏和分类不影响容量与保留期限。删除使用独立 deletion 预览／确认协议；直接调用媒体删除入口返回 STORAGE_MANAGED_DELETE_REQUIRED。

受理时所选空间不足返回 HTTP 409 STORAGE_QUOTA_EXCEEDED；长期空间过期返回 STORAGE_LONG_TERM_EXPIRED。已受理任务的结果仍保存，不在保存时重查容量。STORAGE_IN_USE、STORAGE_REFERENCE_PENDING、STORAGE_RUNTIME_IN_USE 和 STORAGE_VERSION_CONFLICT 是用户主动删除时的保护结果。

可信业务服务通过 POST /api/public/v1/storage/references（仅 X-Api-Key，不是浏览器用户令牌）提交 events，最多 100 项：asset_id、entity_type、entity_id、slot、单调递增 revision、state（active／released）、title、breadcrumb，以及可选 intent_id。仅允许关联本产品资源，资源承担账户由服务端查询确定；旧 revision 返回 ok: true、superseded: true、current_revision，不会确认该旧事件的 intent，业务端不得将其标为已投递，须先核对远端当前引用；同 revision 内容冲突拒绝。跨环境恢复后，应在投递前核对资源与引用、调整后续 revision 基线，并仅重投当前业务状态，不能盲目重放旧 Outbox。title 应使用业务名称，breadcrumb 应包含真实工作空间和业务用途；分镜可包含序号和版本。展示信息在业务事务生成事件时固定，重试不能改写；更名或补齐历史用途须追加新 revision。缺少关联只表示待核验，不表示资源闲置或可删除。

新绑定前，业务服务先校验业务写权限与资源访问权限，再向同一路径提交 operation=prepare、intent（id 幂等 UUID、asset_id、entity_type、entity_id、slot），获得 pending 意图；旧引用此时仍保留。业务写入和带 intent_id 的 outbox 同事务提交，随后发送 active 事件，匹配已提交投影才确认意图。提交结果不明时继续保护，不按时间自动释放。待确认意图会令清理返回 STORAGE_REFERENCE_PENDING。按路径删除不能绕过资源保护。

失败绑定可由项目后端提交 operation=cancel 和原 intent；必须先在业务数据库中不可逆地终止对应写入（以同事务行锁状态机拒绝迟到写入），不能只凭超时取消。取消使用原 ID 幂等重试；cancelled 墓碑拒绝迟到 prepare，已 confirmed 不能取消。Drama 集成以本地事务栅栏和取消 outbox 实现此协议；迁移前没有栅栏的旧意图不自动取消。

空间列表中的 pending_references 为当前用户资源的待确认关联（业务类型、记录 ID、槽位、创建时间）；不应将暂时没有已提交 references 的资源直接显示成可删除闲置资源。

业务删除与资源删除是两件事：删除受管业务记录只提交 released 引用，不能直接按旧对象路径删除共享媒体。已有资源 ID 时下载必须重新解析该 ID，拒绝访问／已到期不能回退旧 URL 或预处理路径。公开原始对象路径接口统一返回 STORAGE_RESOURCE_ID_REQUIRED。

Drama 分段输出、生产来源 metadata 和成品 manifest 的显式 media_asset_id 使用 JSON 路径作为引用槽位（如 output.data.0.media_asset_id），与业务更新同事务入队；不从 URL 猜测资源归属。新 ID 或新绑定意图必须先 prepare，缓存 URL 刷新不改变引用，移除 ID 会释放对应引用。生产视图每次读取重新解析受管 ID；到期、越权或解析失败清空缓存链接，不回退旧地址。仅存 URL 的历史来源仍属兼容数据，并不代表已纳管。

异步 AI Job 的 meta.input_media_ids 可携带最多 100 个输入资源 UUID；服务端在扣费／调用模型前按当前产品和用户验证、原子锁定资源。任务输入清单不可在创建后修改；空间列表 runtime_tasks 展示仍在使用的任务。资源不存在／越权返回 403 STORAGE_JOB_INPUT_UNAVAILABLE；没有暂存转存步骤；已保存资源在未删除且可核验时可作为任务输入。成功任务或确定未出站的扣费预授权失败自动解除保护；一般失败、取消和未知结果不按时间自动解除，需核对上游结果。URL 本身不推断为资源 ID，尚未携带 ID 的旧入口不计入已覆盖。

工具接口 POST /endpoints/:key 也支持 meta.input_media_ids（最多 100 个 UUID），携带时必须提供 idempotency_key。输入按产品和用户锁定，相同键不能改变业务参数或资源清单；同对象签名续期不视为参数变化。执行中／结果未知返回 202 in_progress，不能更换幂等键盲目重试。确定未出站的拒绝释放保护并允许原键重试；已成功的同步结果和工具异步任务查询成功后释放保护。保护校验冲突返回 409；没有携带 ID 的历史 URL 不算已覆盖。

浏览器 SDK 3.15 的 uploadManaged 默认对 16 MB 以上文件尝试受管分片，固定 8 MB 分片、总文件上限 512 MB。COS／OSS／TOS 共享服务端会话；CloudBase 明确不支持此协议时才保留原 SDK 传输，不因权限或网络错误切换后端。onPrepared 返回 assetId，可持久保存该 ID；中断后重新选择原文件并传 assetId 恢复。SDK 分块计算 SHA-256 指纹，文件内容变化拒绝续传，不缓存签名或令牌。

受管分片使用 POST /media/assets/:id/upload-ticket，action 为 multipart-begin（fingerprint 必填）、multipart-status、multipart-part（part_number 必填）、multipart-complete、multipart-abort。服务端固定通道、对象、大小及分片边界，客户端不能指定 uploadId。上传授权十分钟、会话默认二十四小时；服务端从存储商查询已完成分片，不依赖浏览器自报 ETag。complete 合并核验后仍需用 completion_file_id 调用资源 complete，等待封存就绪。取消先终止上传 ID，再回收意图；合并中不能取消。创建回执丢失按唯一对象查询上传会话，查不到或多个候选保留预占并返回 MEDIA_MULTIPART_RECONCILIATION_REQUIRED，不重复创建上传。过期会话不能继续签发分片，但已完成上传仍可确认。

分片授权绑定精确 Content-Length，浏览器必须发送原文件对应的 Blob.slice，不手动设置浏览器禁用的 Content-Length 头。重复取消已删除意图返回成功，但不声称再次删除了文件。取消后保留原先分配路径的迟到上传监测；缺少 CloudBase fileID 时只核验服务端已分配路径，不猜测其他对象。未知结果继续保留观察，自动物理删除需另行启用。

资源列表 runtime_operations 展示仍受工具调用保护的资源与 operation_key，区别于异步 AI 的 runtime_tasks。后台单列已取消上传的 observed_present_bytes、未知／待检查数量和采集时间，不把它们冒充完整桶账单。有资源或迟到上传监测记录的通道不能原地更改桶／区域／端点，返回 STORAGE_CHANNEL_NAMESPACE_IN_USE；迁移位置应使用新通道并验证迁移，凭据轮换不受此限制。

后台容量统计包括上传与 AI 预占；7／30／90 天图按真实观察时间显示。源站 HEAD 观察仅覆盖已登记的位置（原件、封存副本、缩略图），单独标注缺失／未知数量，不等同于全桶清单、历史版本或流量账单。

加一个入口执行 CommonSrv.profile.open() 即可打开集成个人中心（昵称、绑定信息、语言偏好、退出登录）。

document.querySelector("#menu-profile").onclick = () => CommonSrv.profile.open();

// 可选：CommonSrv.profile.open({ mode: "iframe", container: el });
// 可选：CommonSrv.profile.open({ mode: "redirect" });

读取当前语言

const lang = await CommonSrv.lang.getLang();   // "en" | "zh-CN" | "zh-TW"

用户改语言只走 profile.open() 页面（登录入库，未登录存本地），业务端只读不写。

方案 A · 零代码（默认，推荐给多页面 / 传统站点）

SDK 默认在收到「语言变更」/「退出登录」消息时整页 location.reload()。多页面站点、后端渲染（SSR）站点、传统 jQuery / 服务端模板站点直接用默认值即可，什么都不用写。

// 默认行为 —— 什么都不用配
CommonSrv.configure({ clientId: "<your_client_id>" });

方案 B · 自己接管（推荐给单页应用 SPA：React / Vue / Angular / Svelte 等）

什么是 SPA（Single Page Application，单页应用）：整站只加载一次 HTML，之后靠前端路由切页面 —— React / Vue / Angular / Svelte / Next.js（客户端路由部分）都算。 SPA 页面一旦被 location.reload()，路由、表单、弹窗、Redux/Pinia 等前端状态会全部丢失，体验很差。 请关掉自动刷新并订阅两个事件，自己切 i18n / 清用户态。

CommonSrv.configure({
  clientId: "<your_client_id>",
  autoReloadOnLangChange: false,   // 关掉「语言变更整页刷新」
  autoReloadOnLogout:     false,   // 关掉「退出登录整页刷新」
});

// ① 语言变更 —— 用户在 profile.open() 里切了语言就会派发
CommonSrv.on("lang:change", (lang) => {
  // lang: "en" | "zh-CN" | "zh-TW" | ...
  i18n.changeLanguage(lang);   // 换成你自己的 i18n 库调用
  // 或者：window.__setAppLang(lang); / router.invalidate() 等
});

// ② 退出登录 —— 用户在 profile.open() 里点了退出，或跨标签页同步的退出
CommonSrv.on("auth:change", (e) => {
  if (e.type === "signout") {
    // 清接入方自己的用户态、跳登录页、清缓存 …
    yourStore.clearUser();
    router.navigate("/");
  }
});

• 402 INSUFFICIENT_CREDITS：积分不足，响应体附带 required 与 current，引导 CommonSrv.billing.open()。
• 404 MODEL_NOT_FOUND：传入的 model_key 不存在或已停用。
• 403 MODEL_DISABLED：模型已被禁用。
• 400 USE_JOBS_ENDPOINT：该模型是异步类别，请改用 CommonSrv.ai.submit / .wait。
• 429：限流（默认每用户 60 req/min），稍后重试。
• 502 AI_INVOKE_FAILED / MODEL_NOT_ROUTABLE：调用失败，可重试。
• 400 AMOUNT_BELOW_MIN（邀请奖励 · 提现）：提现金额低于后台配置的 min_payout_cents（默认 ¥100）。
• 400 INSUFFICIENT_BALANCE（邀请奖励 · 提现）：现金钱包余额不足。
• 409 PENDING_WITHDRAWAL_EXISTS（邀请奖励 · 提现）：24 小时内已有待审核申请，请稍后。

错误响应与任务错误展示

公共错误响应的 error 是稳定错误码；任意异常文本会收敛为REQUEST_FAILED 或 SERVICE_UNAVAILABLE。原始 服务商专属错误码会收敛为 UPSTREAM_ERROR，detail 保留在受限调用日志，不随共享错误响应返回。 异步任务查询的 job.error 仅返回适合用户阅读的原因，原始失败记录保留在任务及调用日志。 客户端按错误码选择操作，向用户展示本地化说明，不直接展示内部错误码。

try {
  await CommonSrv.ai("google/gemini-2.5-flash", { messages: [...] });
} catch (e) {
  const MESSAGES = {
    INSUFFICIENT_CREDITS: { "zh-CN": "积分不足，请前往充值", en: "Insufficient credits" },
    MODEL_NOT_FOUND:      { "zh-CN": "模型不存在",           en: "Model not found" },
  };
  toast(MESSAGES[e.code]?.[locale] ?? "请稍后重试 / Please retry");
  console.error("[commonsrv]", e.code, e.data);
}