把「相见」做成 API。所有请求携带 Authorization: Bearer <API_KEY>（在控制台签发）。限流 120 次/分钟。

创建相见 POST /api/v1/encounters

为某个情境入口创建一场实时会话。返回 WebRTC 接入信息与（回访用户的）记忆开场白。冷启动时返回 202，按 retry_after_seconds 重试。

# 请求
curl -X POST https://你的域名/api/v1/encounters \
  -H "Authorization: Bearer ck_…" -H "Content-Type: application/json" \
  -d '{"entry_id":"suli","user_id":"你的用户ID"}'

# 响应
{ "session_id": "sess_…", "client_token": "…",
  "opener": "上次你说面试没通过，后来怎么样了？",
  "memory_hits": [...], "share_url": "https://…/a/suli" }

浏览器端用 client_token 建 WebRTC 连接收音视频流；或者干脆把 share_url 发给用户——网页形态开箱即用。

会话内导演指令 POST /api/v1/encounters/:sid

场控层的干预通道对外开放：op=context（软干预：注入指令改写风格）、say（让它说这句）、interrupt（打断接管）、end（结束并抽取记忆）。

curl -X POST …/api/v1/encounters/sess_xxx \
  -H "Authorization: Bearer ck_…" -d '{"op":"context","text":"用户情绪低落，放缓语速，先共情"}'

情境入口 GET · POST /api/v1/entries

查看可用入口，或自建角色（name 必填；可带 persona / speaking_style / opener / portrait / intro_video / goal_id / boundaries）。形象注册仅支持真人风格人像。

curl -X POST …/api/v1/entries -H "Authorization: Bearer ck_…" \
  -d '{"name":"小满","scene":"晚安电台","goalId":"soothe","persona":"你是温柔的深夜电台主播…"}'

横竖屏 / Aspect ratio

创建角色时传 aspect_ratio: "16:9"（横屏）或 "9:16"（竖屏，默认）。封面与情景视频需使用相同画幅。比例与文件真实尺寸分别返回；不会仅因浏览器窗口变化而切换素材。

Set aspect_ratio when creating a character. Existing clients default to portrait. Both entries and encounters return a frame object. Use it to size your player; do not stretch or crop the received video.

{ "name": "Landscape host", "aspect_ratio": "16:9" }

// entries[].frame / encounters.frame (also available while warming)
{ "aspect_ratio": "16:9", "target_width": 1280,
  "target_height": 720, "version": "frame-v1" }

// Browser renderer: retain the real stream's full canvas
video.style.aspectRatio = frame.aspect_ratio.replace(':', '/');
video.style.width = '100%';
video.style.objectFit = 'contain';

分享链接 /a/:id 自动继承角色画幅，无需增加参数。已创建角色不能直接改写画幅或混用其他画幅的素材；请新建对应画幅的角色。
Share links automatically inherit the character format; an existing character's format cannot be changed in place.

记忆层 GET · POST /api/v1/memory

MCP 工具形状：?entry_id=&user_id=&q=一句话 做语义召回；?stats=1 看统计；POST 写入记忆条目。禁区（boundary）类记忆无条件命中并被角色遵守。

curl "…/api/v1/memory?entry_id=suli&user_id=u1&q=昨天买坚果犹豫了" -H "Authorization: Bearer ck_…"
# → {"hit":{"type":"fact","content":"用户对花生过敏"}}

模型与计价

Sona-1 两档：Flash ¥0.005/秒 · Pro ¥0.008/秒。档位在控制台按入口配置，或开启智能路由。形象仅支持真人风格。

Beta 期接口可能调整 · 商务与技术支持：联系我们