Complete

Kasamila developer guide

SDK 2.1：GLSL/ONNX 加密与 Runtime 临时授权，第三方无需配置解密密钥。参见 AILIVE 升级与保护说明。固定 2.0.0 仍受支持。

Kasamila API / Web SDK 2.1.0 开发者手册

SDK 2.1.0 已上线：请先阅读新 Runtime 版本契约。不兼容 SDK 1 或旧可变入口。本文固定版本检查仅适用于显式 pinned 的样例，不能与服务端全局最新版本比较。后端须透传 Session 返回的 sdk，网页使用 bootstrap 加载。HLS 已内置。现在可以按清单迁移。

本文是第三方接入 Kasamila 的当前入口。生产系统自 1.11.0 起只接受和运行 build_mode=geometry 的几何模型模板；人物专属 MouthUNet、微调任务和 V7+v29 混合渲染已经退役。旧微调接口、旧渲染器和旧示例只具有历史审计意义，不能用于新接入。

面向已有接入方的逐项迁移说明见 sdk_1_11_0_third_party_migration.md。完整字段、HLS、透明媒体和浏览器实现见 api_v1_geometry_runtime_guide.md，可运行代码见 examples/geometry-runtime-web。

1. 当前生产契约

项目	SDK 2.1.0 契约
模板模式	仅 `geometry`
SDK 地址	`https://www.kasamila.com/sdk/releases/2.1.0/kasamila.js`
媒体交付	所有长短模板统一使用接入方托管的 HLS
几何数据	Kasamila Runtime Manifest 签发，V7 + 468 点 + 分块几何轨道
默认口型	C
候选口型	G/H/I 仅用于显式测试；I 不会自动启用
牙齿与口腔	SDK 的 V7 WebGL renderer 统一生成；不是 HLS 视频的一部分
透明媒体	Packed Matte HLS；不能把普通 HLS 当作 Alpha 视频
浏览器凭据	仅短期 `ks_rt_` Runtime Token
服务端凭据	永久 `ks_live_` / `ks_test_` API Key

计费边界：登录用户在 Kasamila Portal 站内进行内置预览不扣推理额度。通过 API/SDK 创建 Runtime Session 后立即开始按服务端实际经过时间计费；创建时预留租约额度，提前结束会返还未使用的秒数，直到租约到期仍未结束则消耗完整租约。新注册账号赠送的 1 小时仅供 API/SDK 使用，注册后 30 天有效。官方 SDK 会在销毁时发送 end，第三方自行管理 Token 时也应及时调用 POST /api/v1/runtime/sessions/end。站内免费预览 Token 同时绑定有效 Portal 登录 Cookie，不可复制到第三方页面使用；第三方必须用自己的 API Key 签发普通 Runtime Token。

SDK 2.1.0 增加 client 协商和 sdk 描述符；口型与媒体字段的语义保持不变。V7 对开口原片完成源牙清理后，会沿实时 468 点内唇曲线重建闭合接触层，并随声音开度连续淡出。接触层颜色来自几何模型中已经过鲁棒取样和时序滤波的上下唇材质，减少逐帧原视频取样的影响，旨在抑制 IDLE、静音和闭合音中牙齿、高光或编码噪声形成的乳白像素、双排亮片和肉色补片；个别模板仍需按实际效果验收，不保证消除所有伪影。声音真正驱动张口后，程序化上下牙仍按开度和闭合权重平滑显示。该规则适用于所有 geometry 模板，不包含模板编号特判。现有 templateMedia 和口腔校准参数无需迁移，模板无需重新进行几何训练。

媒体和数据必须使用同一个 timelineId、帧数、fps、逻辑尺寸和 2 秒分块契约。 SDK 会拒绝不一致的描述符，不能在第三方页面跳过检查。

2. 最小接入流程

第三方后端用永久 API Key 查询 ready 的 geometry 模板。
后端创建绑定模板、网页 Origin、输入方式和输出方式的 Runtime Session。
后端只把短期 client_token 及自己保存的 templateMedia 描述符返回网页。
网页加载官方 SDK 2.1.0，将 Token 与 HLS 描述符传给

Kasamila.create()。

SDK 获取签名几何数据，加载 V7 renderer、口腔材质和牙齿纹理，在浏览器中

接收音频并实时渲染。

页面退出或组件卸载时调用 destroy()。

第三方后端                      浏览器
ks_live_/ks_test_               ks_rt_
      │                            │
      ├─ POST /runtime/sessions ───┤
      │                            ├─ Kasamila.create()
      │                            ├─ 第三方 HLS 视频
      │                            ├─ Kasamila 签名几何分块
      │                            └─ WebGL V7 口腔/牙齿渲染

3. 后端创建 Runtime Session

永久 Key 只能保存在第三方服务器或 Secret Manager 中：

const response = await fetch(
  'https://www.kasamila.com/api/v1/runtime/sessions',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.KASAMILA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      avatar_id: '999000000001',
      template_code: '001',
      origin: 'https://app.example.com',
      input_modes: ['file', 'audio_url', 'pcm_stream', 'tts_stream'],
      output_mode: 'original',
      max_duration_seconds: 600
    })
  }
);
const payload = await response.json();
if (!response.ok) {
  throw new Error(payload.error?.message || `Kasamila ${response.status}`);
}

// 先验证自己的终端用户与模板权限，再返回给网页。
return {
  sdk: payload.data.sdk, sessionToken: payload.data.client_token,
  expiresAt: payload.data.expires_at,
  mediaDelivery: payload.data.media_delivery,
  templateMedia: loadTrustedMediaDescriptor(
    payload.data.output_mode,
    '999000000001-001'
  )
};

loadTrustedMediaDescriptor() 必须从第三方受信配置或数据库读取，不能接受浏览器任意提交的 URL。永久 Key、Runtime Token 和签名资产 URL 不得写入日志。

4. 浏览器初始化

<div id="avatar" style="width:540px;height:960px"></div>
<script type="module">
  import { loadKasamila } from "https://www.kasamila.com/sdk/bootstrap/1/loader.mjs";
  const response = await fetch("/api/runtime-token", {
    method: "POST", credentials: "same-origin"
  });
  const bootstrap = await response.json();
  if (!response.ok) throw new Error("Runtime bootstrap failed");
  const Kasamila = await loadKasamila(bootstrap.sdk, "https://www.kasamila.com");
  const player = await Kasamila.create({
    element: document.querySelector("#avatar"),
    sessionToken: bootstrap.sessionToken,
    templateMedia: bootstrap.templateMedia
  });
  window.addEventListener("pagehide", () => player.destroy(), { once: true });
</script>

Safari 可使用原生 HLS；Chrome、Edge、Firefox 和多数 Android 浏览器需要接入方使用 SDK 包内的 hls.js，无需外部脚本地址。 SDK 会在几何、纹理和口型运行时就绪后才从第 0 帧启动视频；HLS 与 2 秒几何分块分别预缓冲，几何解压解析在 Blob Worker 中完成。模板始终以 1.0 倍速运行，接入方不要直接修改 SDK 内部 video 的 currentTime 或 playbackRate。

5. 音频输入

Runtime Session 必须授权对应的 input_modes：

await player.setAudioFile(file);                       // file
await player.setAudioUrl(corsEnabledTemporaryUrl);    // audio_url
await player.setPcmStream(readable, { sampleRate: 16000 });
await player.setPcmStream(ttsReadable, {
  mode: 'tts_stream', sampleRate: 16000
});
await player.setMicrophone();                          // microphone
await player.setMediaStreamTrack(remoteRtcTrack);      // rtc

生产 TTS 优先提供可解码音频文件，或 16 kHz 单声道 Int16/Float32 PCM。浏览器 speechSynthesis 无法稳定导出 PCM，只适合演示，不应作为口型质量验收依据。

6. 口型和牙齿规则

不传 profile 时，SDK 使用模板 Manifest 的默认档位；生产默认是 C。
setProfile('I') 只应在明确的候选测试中调用。
不要把旧系统的 MouthUNet/v29 参数、嘴部 mask 或牙齿图层叠加到 SDK Canvas。
不要把 teeth_scale 初始化为 0。除非有明确产品需求，使用 Manifest 下发值。
牙齿不是 HLS 视频的一部分，也不由第三方单独上传。SDK 会从 Kasamila 静态域

加载 V7 renderer 和 teeth_cavity_texture.png，并从签名几何资产加载内唇材质。

不要直接实例化 KasamilaGeometryWebGLPlayer，也不要只复制

custom_live_geometry_ghi_v7.js。公开稳定入口只有 Kasamila.create()。

如果人物有口型但没有牙齿，优先检查浏览器 Network/Console：

SDK 必须显示 Kasamila.version === '2.1.0'；清理旧 Service Worker/CDN 缓存。
/web/common/teeth_cavity_texture.png 必须返回 200，不能被 CSP、CORS、广告

拦截器或第三方代理改写。

player.getMouthConfiguration().parameters.teeth_scale 不得为 0。
页面不得在 SDK Canvas 上覆盖自己的嘴部/牙齿层。
若缺少 V7 内唇材质，SDK 会报

Geometry v7 oral material is incomplete，不得捕获后回退旧 renderer。

7. HLS、透明媒体、CORS 和 CSP

所有 geometry 模板，不论 10 秒还是 5 分钟，都传完整 templateMedia 描述符。描述符不能只传 .m3u8 URL；必须包含 timelineId、frameCount、fps、尺寸、 layout、segmentDuration 和规范视频 SHA-256。透明输出必须使用与 Session 输出模式匹配的 packed_matte 描述符。

第三方媒体域至少返回：

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Expose-Headers: Content-Length, Content-Range, Accept-Ranges, ETag

建议 CSP 起点：

script-src 'self' https://www.kasamila.com;
connect-src 'self' https://www.kasamila.com https://media.example.com;
media-src 'self' https://media.example.com blob:;
worker-src 'self' blob:;
img-src 'self' https://www.kasamila.com data: blob:;

特别注意 img-src https://www.kasamila.com 与 worker-src blob:：前者允许牙齿和材质纹理，后者允许 Audio2Viseme 与几何分块解码 Worker。HLS 的播放列表、初始化段和所有 .m4s 分片都必须有正确 CORS，不能只给 .m3u8 加响应头。

8. 版本升级与验收

上线前至少验证：

原背景、Packed Matte 透明背景各一个模板；
10–15 秒短模板和 5 分钟以上长模板的首播、跨段、seek、loop；
文件音频、第三方 TTS 音频或 PCM 流至少各一种；
静音、张口、闭口、唇齿音和大幅左右口型均能看到上下牙及正确遮挡；
C 是默认档位，未被业务代码隐式改成 I；
断网恢复、HLS 签名过期、Runtime Token 过期都有明确错误状态；
长时间播放无固定 2 秒周期卡顿、循环边界停顿或临时快进，实际倍速始终为 1.0；
SPA 路由切换和页面退出调用 destroy()，没有重复 Canvas、音频节点或计量心跳；
Windows/macOS/iOS/Android 真机长时间运行内存稳定。

第三方升级时可直接采用 sdk_1_11_0_third_party_migration.md 作为交付和验收清单。